Trait cuprate_database::Env

pub trait Env: Sized {
    type EnvInner<'env>: EnvInner<'env>
       where Self: 'env;
    type TxRo<'env>: TxRo<'env>
       where Self: 'env;
    type TxRw<'env>: TxRw<'env>
       where Self: 'env;

    const MANUAL_RESIZE: bool;
    const SYNCS_PER_TX: bool;

    // Required methods
    fn open(config: Config) -> Result<Self, InitError>;
    fn config(&self) -> &Config;
    fn sync(&self) -> Result<(), RuntimeError>;
    fn env_inner(&self) -> Self::EnvInner<'_>;

    // Provided methods
    fn resize_map(
        &self,
        resize_algorithm: Option<ResizeAlgorithm>,
    ) -> NonZeroUsize { ... }
    fn current_map_size(&self) -> usize { ... }
    fn disk_size_bytes(&self) -> Result<u64> { ... }
}

Database environment abstraction.

Essentially, the functions that can be called on ConcreteEnv.

Drop

Objects that implement Env should probably Env::sync in their drop implementations, although, no invariant relies on this (yet).

Lifetimes

The lifetimes associated with Env have a sequential flow:

Env -> Tx -> Database

As in:

• open database tables only live as long as…
• transactions which only live as long as the…
• database environment

Required Associated Constants

const MANUAL_RESIZE: bool

Does the database backend need to be manually resized when the memory-map is full?

Invariant

If this is false, that means this Env must never return a RuntimeError::ResizeNeeded.

If this is true, Env::resize_map & Env::current_map_size must be re-implemented, as it just panics by default.

const SYNCS_PER_TX: bool

Does the database backend forcefully sync/flush to disk on every transaction commit?

This is used as an optimization.

Required Associated Types

type EnvInner<'env>: EnvInner<'env> where Self: 'env

The struct representing the actual backend’s database environment.

This is used as the self in EnvInner functions, so whatever this type is, is what will be accessible from those functions.

type TxRo<'env>: TxRo<'env> where Self: 'env

The read-only transaction type of the backend.

type TxRw<'env>: TxRw<'env> where Self: 'env

The read/write transaction type of the backend.

Required Methods

fn open(config: Config) -> Result<Self, InitError>

Open the database environment, using the passed Config.

Invariants

This function does not create any tables.

You must create all possible tables with EnvInner::create_db before attempting to open any.

Errors

This will error if the database file could not be opened.

This is the only Env function that will return an InitError instead of a RuntimeError.

fn config(&self) -> &Config

Return the Config that this database was Env::opened with.

fn sync(&self) -> Result<(), RuntimeError>

Fully sync the database caches to disk.

Invariant

This must fully and synchronously flush the database data to disk.

I.e., after this function returns, there must be no doubts that the data isn’t synced yet, it must be synced.

Errors

If there is a synchronization error, this should return an error.

fn env_inner(&self) -> Self::EnvInner<'_>

Return the Env::EnvInner.

Locking behavior

When using the heed backend, Env::EnvInner is a RwLockReadGuard, i.e., calling this function takes a read lock on the heed::Env.

Be aware of this, as other functions (currently only Env::resize_map) will take a write lock.

Provided Methods

fn resize_map(&self, resize_algorithm: Option<ResizeAlgorithm>) -> NonZeroUsize

Resize the database’s memory map to a new (bigger) size using a ResizeAlgorithm.

By default, this function will use the ResizeAlgorithm in Env::config.

If resize_algorithm is Some, that will be used instead.

This function returns the new memory map size in bytes.

Invariant

This function must be re-implemented if Env::MANUAL_RESIZE is true.

Otherwise, this function will panic with unreachable!().

fn current_map_size(&self) -> usize

What is the current size of the database’s memory map in bytes?

Invariant

1. This function must be re-implemented if Env::MANUAL_RESIZE is true.
2. This function must be accurate, as Env::resize_map() may depend on it.

fn disk_size_bytes(&self) -> Result<u64>

Return the amount of actual of bytes the database is taking up on disk.

This is the current disk value in bytes, not the memory map.

Errors

This will error if either:

• std::fs::File::open
• std::fs::File::metadata

failed on the database file on disk.

Object Safety

This trait is not object safe.

Implementors

impl Env for ConcreteEnv

const MANUAL_RESIZE: bool = true

const SYNCS_PER_TX: bool = false

type EnvInner<'env> = RwLockReadGuard<'env, Env>

type TxRo<'tx> = RoTxn<'tx>

type TxRw<'tx> = RefCell<RwTxn<'tx>>