Trait Blob 

pub trait Blob:
    Send
    + Sync
    + 'static {
    // Required methods
    fn read_at_buf(
        &self,
        offset: u64,
        len: usize,
        bufs: impl Into<IoBufsMut> + Send,
        options: ReadOptions,
    ) -> impl Future<Output = Result<IoBufsMut, Error>> + Send;
    fn read_at(
        &self,
        offset: u64,
        len: usize,
        options: ReadOptions,
    ) -> impl Future<Output = Result<IoBufsMut, Error>> + Send;
    fn write_at(
        &self,
        offset: u64,
        bufs: impl Into<IoBufs> + Send,
        options: WriteOptions,
    ) -> impl Future<Output = Result<(), Error>> + Send;
    fn resize(&self, len: u64) -> impl Future<Output = Result<(), Error>> + Send;
    fn sync(&self) -> impl Future<Output = Result<(), Error>> + Send;
    fn start_sync(&self) -> impl Future<Output = Handle<()>> + Send;

    // Provided methods
    fn read_many(
        &self,
        ranges: &[(u64, usize)],
        options: ReadOptions,
    ) -> impl Stream<Item = Result<(usize, IoBufsMut), Error>> + Send { ... }
    fn start_read_many(
        &self,
        ranges: &[(u64, usize)],
        options: ReadOptions,
    ) -> impl Future<Output = Handle<Vec<IoBufsMut>>> + Send { ... }
}

Interface to read and write to a blob.

A blob represents one open. Opening it again while it is alive fails unless the blob was removed since, see Storage::open_versioned. Wrap the blob in an Arc to share access to that open.

When a blob is dropped, any unsynced changes may be discarded. Dropping does not synchronize the blob. Call Blob::sync before dropping to ensure all changes are durably persisted.

Durability

After a crash, a write not covered by a completed Blob::sync may be torn: any subset of its bytes may be durable. Bytes outside the written range remain unchanged.

Concurrency

A read observes every write and resize that completed before the read began. A read that overlaps a write or resize is not an atomic snapshot and may observe different stages of that mutation. The ranges of one batched read are not a snapshot either. Callers that need a stable view must synchronize mutations with their reads or read only immutable ranges.

Required Methods

fn read_at_buf( &self, offset: u64, len: usize, bufs: impl Into<IoBufsMut> + Send, options: ReadOptions, ) -> impl Future<Output = Result<IoBufsMut, Error>> + Send

Read exactly len bytes at offset into caller-provided buffers.

Returns the same buffers with their chunk layout preserved.

Panics

Panics if len exceeds the total capacity of bufs.

fn read_at( &self, offset: u64, len: usize, options: ReadOptions, ) -> impl Future<Output = Result<IoBufsMut, Error>> + Send

Read exactly len bytes at offset.

To reuse a buffer(s), use Blob::read_at_buf.

fn write_at( &self, offset: u64, bufs: impl Into<IoBufs> + Send, options: WriteOptions, ) -> impl Future<Output = Result<(), Error>> + Send

Write every remaining byte in bufs to the blob at offset.

The buffers are treated as one logical byte sequence in chunk order.

fn resize(&self, len: u64) -> impl Future<Output = Result<(), Error>> + Send

Resize the blob to the given length.

If the length is greater than the current length, the blob is extended with zeros. If the length is less than the current length, the blob is resized.

fn sync(&self) -> impl Future<Output = Result<(), Error>> + Send

Make every write and resize that completed before this call durable.

fn start_sync(&self) -> impl Future<Output = Handle<()>> + Send

Request that every write and resize that completed before this call is durable.

Awaiting this future waits until the runtime accepts responsibility for the sync. It continues even if the returned Handle is dropped. Awaiting that handle waits for the same durability guarantee as Blob::sync.

Provided Methods

fn read_many( &self, ranges: &[(u64, usize)], options: ReadOptions, ) -> impl Stream<Item = Result<(usize, IoBufsMut), Error>> + Send

Read every (offset, len) range in ranges, yielding (range index, buffer) as each read completes, in any order. Each buffer holds the len bytes at offset.

Without an error, every range is yielded exactly once. An error need not identify the ranges it affects, and those ranges may never be yielded, so treat any error as failing the call. Reads may begin before the stream is polled and continue after it is dropped.

fn start_read_many( &self, ranges: &[(u64, usize)], options: ReadOptions, ) -> impl Future<Output = Handle<Vec<IoBufsMut>>> + Send

Request the len bytes at offset of every (offset, len) range in ranges.

Awaiting this future waits until the runtime accepts responsibility for the reads. They then proceed whether or not the returned Handle is polled. Dropping the handle abandons them, and unlike a sync, an abandoned read may be cancelled or left to finish. Awaiting the handle yields the bytes of every range, in range order. Any error fails the whole read, as it does for Blob::read_many.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl<B: Blob> Blob for Arc<B>

Available on neither commonware_stability_DELTA nor commonware_stability_EPSILON nor commonware_stability_GAMMA nor commonware_stability_RESERVED.

fn read_at_buf( &self, offset: u64, len: usize, bufs: impl Into<IoBufsMut> + Send, options: ReadOptions, ) -> impl Future<Output = Result<IoBufsMut, Error>> + Send

fn read_at( &self, offset: u64, len: usize, options: ReadOptions, ) -> impl Future<Output = Result<IoBufsMut, Error>> + Send

fn read_many( &self, ranges: &[(u64, usize)], options: ReadOptions, ) -> impl Stream<Item = Result<(usize, IoBufsMut), Error>> + Send

fn start_read_many( &self, ranges: &[(u64, usize)], options: ReadOptions, ) -> impl Future<Output = Handle<Vec<IoBufsMut>>> + Send

fn write_at( &self, offset: u64, bufs: impl Into<IoBufs> + Send, options: WriteOptions, ) -> impl Future<Output = Result<(), Error>> + Send

fn resize(&self, len: u64) -> impl Future<Output = Result<(), Error>> + Send

fn sync(&self) -> impl Future<Output = Result<(), Error>> + Send

fn start_sync(&self) -> impl Future<Output = Handle<()>> + Send

Implementors

impl<B: Blob> Blob for DelayedSyncBlob<B>

impl<B: Blob> Blob for SyncFaultBlob<B>

impl<B: Blob> Blob for WriteFaultBlob<B>