pub trait Storage:
Send
+ Sync
+ 'static {
type Blob: Blob;
// Required methods
fn open_versioned(
&self,
partition: &str,
name: &[u8],
versions: RangeInclusive<BlobVersion>,
) -> impl Future<Output = Result<(Self::Blob, u64, BlobVersion), Error>> + Send;
fn remove(
&self,
partition: &str,
name: Option<&[u8]>,
) -> impl Future<Output = Result<(), Error>> + Send;
fn scan(
&self,
partition: &str,
) -> impl Future<Output = Result<Vec<Vec<u8>>, Error>> + Send;
// Provided method
fn open(
&self,
partition: &str,
name: &[u8],
) -> impl Future<Output = Result<(Self::Blob, u64), Error>> + Send { ... }
}Expand description
Interface to interact with storage.
Blobs can be read and written concurrently. The Concurrency section of Blob describes what such reads observe.
Storage can be backed by a local filesystem, cloud storage, etc.
§Durability
Runtimes must ensure that any data readable when user code starts
executing is crash-durable. Storage structures may rely on this during
recovery: data read at initialization can be assumed to survive a
subsequent crash without an explicit Blob::sync.
A blob reopened within a run has the same durability guarantee. Opening waits for outstanding operations from the previous open to finish and ensures that any data readable when it returns is crash-durable.
§Cancellation
Dropping an operation’s future does not guarantee cancellation: the operation may still complete, and later operations may observe its effect.
Runtimes must ensure that no operation issued by a previous run against the same storage is still in flight when a new run begins.
§Partition Names
Partition names must be non-empty and contain only ASCII alphanumeric
characters, dashes (-), or underscores (_). Names containing other
characters (e.g., /, ., spaces) will return an error. On case-insensitive
filesystems, partition names that differ only by letter case must not both
be used.
Required Associated Types§
Required Methods§
Sourcefn open_versioned(
&self,
partition: &str,
name: &[u8],
versions: RangeInclusive<BlobVersion>,
) -> impl Future<Output = Result<(Self::Blob, u64, BlobVersion), Error>> + Send
fn open_versioned( &self, partition: &str, name: &[u8], versions: RangeInclusive<BlobVersion>, ) -> impl Future<Output = Result<(Self::Blob, u64, BlobVersion), Error>> + Send
Open an existing blob in a given partition or create a new one, returning the blob and its length.
§Uniqueness
Only one handle can be opened for a blob at a time. Use an Arc to share the handle, and drop all owners before reopening the blob.
An otherwise valid open returns Error::BlobAlreadyOpen if a handle from an earlier
open of the blob is still alive and the blob has not been removed since.
§Durability
An Ok result indicates the blob is durably created (or already exists).
A runtime may retain a durability failure across logical opens. Later opens can return that failure even after every handle has been dropped.
§Versions
Blobs are versioned. If the blob’s version is not in versions, returns
Error::BlobVersionMismatch. versions must be non-empty.
§Layout
New blobs are created with the latest layout allowed by the runtime. Reopening an existing blob honors the layout recorded in its header when the runtime’s configured layout range allows it, and returns Error::BlobLayoutMismatch otherwise.
§Returns
A tuple of (blob, logical_size, blob_version).
Sourcefn remove(
&self,
partition: &str,
name: Option<&[u8]>,
) -> impl Future<Output = Result<(), Error>> + Send
fn remove( &self, partition: &str, name: Option<&[u8]>, ) -> impl Future<Output = Result<(), Error>> + Send
Remove a blob from a given partition.
If no name is provided, the entire partition is removed.
An Ok result indicates the blob is durably removed.
§Read-after-remove
Removal unlinks the blob’s name but does not invalidate previously opened handles: they remain fully readable until dropped, whether the blob was removed by name or by removing its entire partition. This includes bytes written but never synced. Physical resources are reclaimed once the last handle is dropped.
Re-opening a removed blob’s name creates a new, independent blob; handles opened before the removal continue to observe the removed blob’s contents.
Mutating a removed blob (e.g. via Blob::write_at, Blob::resize, or
Blob::sync) is unspecified: implementations may succeed or return an error.
Provided Methods§
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".