This is an automated email from the ASF dual-hosted git repository. xuanwo pushed a commit to branch proposal-native-capability in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit 52106f26c59bc15a3e0b7db081e1305e6b1389e5 Author: Xuanwo <[email protected]> AuthorDate: Fri Aug 11 16:54:44 2023 +0800 Add proposal Signed-off-by: Xuanwo <[email protected]> --- core/src/docs/rfcs/0000_native_capability.md | 35 ++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/core/src/docs/rfcs/0000_native_capability.md b/core/src/docs/rfcs/0000_native_capability.md index 2ab94bc31..3a6cd5ce0 100644 --- a/core/src/docs/rfcs/0000_native_capability.md +++ b/core/src/docs/rfcs/0000_native_capability.md @@ -1,43 +1,58 @@ -- Proposal Name: (fill me in with a unique ident, `my_awesome_feature`) -- Start Date: (fill me in with today's date, YYYY-MM-DD) +- Proposal Name: `native_capability` +- Start Date: 2023-08-11 - RFC PR: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/pull/0000) - Tracking Issue: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/issues/0000) # Summary -Add `native_capability` and `full_capability` for `Operator` so that users can make better decisions. +Add `native_capability` and `full_capability` to `Operator` so that users can make more informed decisions. # Motivation -OpenDAL adds `Capability` to let users know whether a service supports a specific feature. However, it is not enough for users to make decisions. But OpenDAL doesn't simply expose services API directly, instead it will try to simulate the behavior to make it more useful. +OpenDAL adds `Capability` to inform users whether a service supports a specific feature. However, this is not enough for users to make decisions. OpenDAL doesn't simply expose the services' API directly; instead, it simulates the behavior to make it more useful. -For examples, `s3` doesn't support seek operations like local fs. But it's a quiet common operation for users. So OpenDAL will try to simulate the behavior by calculate the correct offset and read the data from the offset instead. After this simulation, `s3` service has `read_can_seek` capability now. +For example, `s3` doesn't support seek operations like a local file system. But it's a quite common operation for users. So OpenDAL will try to simulate the behavior by calculating the correct offset and reading the data from that offset instead. After this simulation, the `s3` service has the `read_can_seek` capability now. -As another example, most services like `s3` doesn't support blocking operation, OpenDAL implements a `BlockingLayer` to make it possible. After this implementation, `s3` service has `blocking` capability now. - -However, these capabilities alone are insufficient for users to make informed decisions. Take the `s3` service's `blocking` capability as an example. Users are unable to determine whether it is a native capability or not, which may result in them unknowingly utilizing this feature in performance-sensitive scenarios and experiencing significantly poor performance. +As another example, most services like `s3` don't support blocking operations. OpenDAL implements a `BlockingLayer` to make it possible. After this implementation, the `s3` service has the `blocking` capability now. +However, these capabilities alone are insufficient for users to make informed decisions. Take the `s3` service's `blocking` capability as an example. Users are unable to determine whether it is a native capability or not, which may result in them unknowingly utilizing this feature in performance-sensitive scenarios, leading to significantly poor performance. +So this proposal intends to address this issue by adding `native_capability` and `full_capability` to `OperatorInfo`. Users can use `native_capability` to determine whether a capability is native or not. # Guide-level explanation +We will add two new APIs `native_capability()` and `full_capability()` in `OperatorInfo`, and remove the `capability()` and related `can_xxx()` API. + +```diff ++ pub fn native_capability(&self) -> Capability ++ pub fn full_capability(&self) -> Capability +- pub fn capability(&self) -> Capability +``` # Reference-level explanation +We will add two new fields `native_capability` and `full_capability` in `AccessorInfo`: + +- Services SHOULD only set `native_capability`, and `full_capability` will be the same as `native_capability`. +- Layers MAY change `full_capability` and MUST NOT modify `native_capability`. +- `OperatorInfo` should forward `native_capability()` and `full_capability()` to `AccessorInfo`. # Drawbacks +None # Rationale and alternatives - +None # Prior art - +None # Unresolved questions +None # Future possibilities +None
