Struct AccessorInfo

pub struct AccessorInfo { /* private fields */ }

Info for the accessor. Users can use this struct to retrieve information about the underlying backend.

This struct is intentionally not implemented with Clone to ensure that all accesses within the same operator, access layers, and services use the same instance of AccessorInfo. This is especially important for HttpClient and Executor.

Panic Safety

All methods provided by AccessorInfo will safely handle lock poisoning scenarios. If the inner RwLock is poisoned (which happens when another thread panicked while holding the write lock), this method will gracefully continue execution.

• For read operations, the method will return the current state.
• For write operations, the method will do nothing.

Maintain Notes

We are using std::sync::RwLock to provide thread-safe access to the inner data.

I have performed the bench across different arc-swap alike crates:

test arcswap                    ... bench:          14.85 ns/iter (+/- 0.33)
test arcswap_full               ... bench:         128.27 ns/iter (+/- 4.30)
test baseline                   ... bench:          11.33 ns/iter (+/- 0.76)
test mutex_4                    ... bench:         296.73 ns/iter (+/- 49.96)
test mutex_unconteded           ... bench:          13.26 ns/iter (+/- 0.56)
test rwlock_fast_4              ... bench:         201.60 ns/iter (+/- 7.47)
test rwlock_fast_uncontended    ... bench:          12.77 ns/iter (+/- 0.37)
test rwlock_parking_4           ... bench:         232.02 ns/iter (+/- 11.14)
test rwlock_parking_uncontended ... bench:          13.18 ns/iter (+/- 0.39)
test rwlock_std_4               ... bench:         219.56 ns/iter (+/- 5.56)
test rwlock_std_uncontended     ... bench:          13.55 ns/iter (+/- 0.33)

The results show that as long as there aren’t too many uncontended accesses, RwLock is the best choice, allowing for fast access and the ability to modify partial data without cloning everything.

And it’s true: we only update and modify the internal data in a few instances, such as when building an operator or applying new layers.

Implementations

impl AccessorInfo

pub fn scheme(&self) -> Scheme

Scheme of backend.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply returning the current scheme.

pub fn set_scheme(&self, scheme: Scheme) -> &Self

Set Scheme for backend.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply skipping the update operation rather than propagating the panic.

pub fn root(&self) -> Arc<str>

Root of backend, will be in format like /path/to/dir/

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply returning the current root.

pub fn set_root(&self, root: &str) -> &Self

Set root for backend.

Note: input root must be normalized.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply skipping the update operation rather than propagating the panic.

pub fn name(&self) -> Arc<str>

Name of backend, could be empty if underlying backend doesn’t have namespace concept.

For example:

• s3 => bucket name
• azblob => container name
• azdfs => filesystem name
• azfile => share name

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply returning the current scheme.

pub fn set_name(&self, name: &str) -> &Self

Set name of this backend.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply skipping the update operation rather than propagating the panic.

pub fn native_capability(&self) -> Capability

Get backend’s native capabilities.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply returning the current native capability.

pub fn set_native_capability(&self, capability: Capability) -> &Self

Set native capabilities for service.

NOTES

Set native capability will also flush the full capability. The only way to change full_capability is via update_full_capability.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply skipping the update operation rather than propagating the panic.

pub fn full_capability(&self) -> Capability

Get service’s full capabilities.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply returning the current native capability.

pub fn update_full_capability( &self, f: impl FnOnce(Capability) -> Capability, ) -> &Self

Update service’s full capabilities.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply skipping the update operation rather than propagating the panic.

pub fn http_client(&self) -> HttpClient

Get http client from the context.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply returning the current http client.

pub fn update_http_client( &self, f: impl FnOnce(HttpClient) -> HttpClient, ) -> &Self

Update http client for the context.

Note

Requests must be forwarded to the old HTTP client after the update. Otherwise, features such as retry, tracing, and metrics may not function properly.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply skipping the update operation.

pub fn executor(&self) -> Executor

Get executor from the context.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply returning the current executor.

pub fn update_executor(&self, f: impl FnOnce(Executor) -> Executor) -> &Self

Update executor for the context.

Note

Tasks must be forwarded to the old executor after the update. Otherwise, features such as retry, timeout, and metrics may not function properly.

Panic Safety

This method safely handles lock poisoning scenarios. If the inner RwLock is poisoned, this method will gracefully continue execution by simply skipping the update operation.

Trait Implementations

impl Debug for AccessorInfo

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AccessorInfo

fn default() -> AccessorInfo

Returns the “default value” for a type.

impl Hash for AccessorInfo

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for AccessorInfo

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for AccessorInfo