Trait async_mwmr::AsyncDatabase

pub trait AsyncDatabase: Sized + Send + Sync + 'static {
    type Error: Error + Send + Sync + 'static;
    type Options;
    type Key: Debug + Send + Sync + 'static;
    type Value: Debug + Send + Sync + 'static;
    type Item: Send + Sync + 'static;
    type ItemRef<'a>: Send + Sync
       where Self: 'a;
    type Iterator<'a>: Send + Sync
       where Self: 'a;
    type Keys<'a>: Send + Sync
       where Self: 'a;

    // Required methods
    fn max_batch_size(&self) -> u64;
    fn max_batch_entries(&self) -> u64;
    fn estimate_size(&self, entry: &Entry<Self::Key, Self::Value>) -> u64;
    fn validate_entry(
        &self,
        entry: &Entry<Self::Key, Self::Value>
    ) -> Result<(), Self::Error>;
    fn maximum_version(&self) -> u64;
    fn options(&self) -> &Self::Options;
    fn open(
        opts: Self::Options
    ) -> impl Future<Output = Result<Self, Self::Error>> + Send;
    fn fingerprint(&self, k: &Self::Key) -> u64;
    fn apply(
        &self,
        entries: OneOrMore<Entry<Self::Key, Self::Value>>
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
    fn get(
        &self,
        k: &Self::Key,
        version: u64
    ) -> impl Future<Output = Result<Option<Either<Self::ItemRef<'_>, Self::Item>>, Self::Error>> + Send;
    fn iter<'a, 'b>(
        &'a self,
        pending: impl Iterator<Item = EntryRef<'b, Self::Key, Self::Value>> + 'b,
        transaction_version: u64,
        opts: IteratorOptions
    ) -> impl Future<Output = Self::Iterator<'a>> + 'a
       where 'b: 'a;
    fn keys<'a, 'b>(
        &'a self,
        pending: impl Iterator<Item = KeyRef<'b, Self::Key>> + 'b,
        transaction_version: u64,
        opts: KeysOptions
    ) -> impl Future<Output = Self::Keys<'a>> + 'a
       where 'b: 'a;
}

An abstraction of database which can be managed by the [TransactionDB].

Required Associated Types

type Error: Error + Send + Sync + 'static

The error type returned by the database.

type Options

The options type of the database, which used to create the database.

type Key: Debug + Send + Sync + 'static

The key type of the database.

type Value: Debug + Send + Sync + 'static

The value type of the database.

type Item: Send + Sync + 'static

The owned item type can be returned by get.

type ItemRef<'a>: Send + Sync where Self: 'a

The reference item type can be returned by get.

type Iterator<'a>: Send + Sync where Self: 'a

The iterator type of the database.

type Keys<'a>: Send + Sync where Self: 'a

The key iterator type of the database.

Required Methods

fn max_batch_size(&self) -> u64

Returns the maximum batch size in bytes

fn max_batch_entries(&self) -> u64

Returns the maximum entries in batch

fn estimate_size(&self, entry: &Entry<Self::Key, Self::Value>) -> u64

Returns the estimated size of the entry in bytes when persisted in the database.

fn validate_entry( &self, entry: &Entry<Self::Key, Self::Value> ) -> Result<(), Self::Error>

Validate if the entry is valid for this database.

e.g.

• If the entry is expired
• If the key or the value is too large
• If the key or the value is empty
• If the key or the value contains invalid characters
• and etc.

fn maximum_version(&self) -> u64

Returns the maximum version of the entry in the database, if you are not implementing MVCC, you can just ignore this method.

fn options(&self) -> &Self::Options

Returns the options of the database.

fn open( opts: Self::Options ) -> impl Future<Output = Result<Self, Self::Error>> + Send

Open the database with the given options.

fn fingerprint(&self, k: &Self::Key) -> u64

Returns the fingerprint of key.

Implementors should ensure that the fingerprint is consistent for the same key.

fn apply( &self, entries: OneOrMore<Entry<Self::Key, Self::Value>> ) -> impl Future<Output = Result<(), Self::Error>> + Send

Applies a series of entries to the database. This method will be invoked in [Mwmr::commit] method.

This method is responsible for persisting a batch of entries to the database. It is called after the entries have been prepared and serialized by a higher-level [Mwmr] transaction manager, ensuring that consistency and isolation requirements are already satisfied. Users of this method do not need to handle these concerns; they can simply pass the entries to be applied.

Implementation Notes

Implementors of this method must ensure atomicity of the apply operation; either all entries are applied successfully, or none are, to prevent partial updates to the database state. It is assumed that the consistency and isolation levels required for the entries have been managed by a higher-level transaction manager before invocation of this method.

fn get( &self, k: &Self::Key, version: u64 ) -> impl Future<Output = Result<Option<Either<Self::ItemRef<'_>, Self::Item>>, Self::Error>> + Send

Get the item from the database by the key and the version (version can be used for MVCC).

fn iter<'a, 'b>( &'a self, pending: impl Iterator<Item = EntryRef<'b, Self::Key, Self::Value>> + 'b, transaction_version: u64, opts: IteratorOptions ) -> impl Future<Output = Self::Iterator<'a>> + 'a

where 'b: 'a,

Accepts an iterator of pending and returns an combined iterator.

It depends on the database implementation to decide how to handle the pending and construct the final conbined iterator.

The order of the items in the iterator depends on the [PendingManager] of the [WriteTransaction].

e.g.

• if users create [WriteTransaction] with IndexMap as the [PendingManager], the order of the entries in the iterator will be the same as the insertion order.
• if users create [WriteTransaction] with [BTreeCache] as the [PendingManager], the order of the entires in the iterator will be sorted by key.

fn keys<'a, 'b>( &'a self, pending: impl Iterator<Item = KeyRef<'b, Self::Key>> + 'b, transaction_version: u64, opts: KeysOptions ) -> impl Future<Output = Self::Keys<'a>> + 'a

where 'b: 'a,

Accepts an iterator of pending keys and returns an combined iterator.

It depends on the database implementation to decide how to handle the pending and construct the final conbined iterator.

The order of the items in the iterator depends on the [PendingManager] of the [WriteTransaction].

e.g.

• if users create [WriteTransaction] with IndexMap as the [PendingManager], the order of the keys in the iterator will be the same as the insertion order.
• if users create [WriteTransaction] with [BTreeCache] as the [PendingManager], the order of the keys in the iterator will be sorted by key.

Object Safety

This trait is not object safe.

Implementors