Struct ord_lmdb_zero::ConstTransaction

pub struct ConstTransaction<'env> { /* private fields */ }

Base functionality for an LMDB transaction.

The type is “const” in a similar usage to the modifier in C: One cannot use it to make any modifications, but also cannot rely on it actually being read-only. ConstTransactions are used to write code that can operate in either kind of transaction.

Unlike most other LMDB wrappers, transactions here are (indirectly) the things in control of accessing data behind cursors. This is in order to correctly express memory semantics: Moving a cursor does not invalidate memory obtained from the cursor; however, any mutation through the same transaction does. We therefore model accesses to data in the environment as borrows of the transaction and the database themselves (possibly mutable on the latter), which allows the borrow checker to ensure that all references are dropped before doing a structural modification.

Note that due to limitations in the Rust borrow checker, one actually needs to use the *Accessor structs to access data. Any transaction will yield at most one accessor, which is implemented with a runtime check that should in the vast majority of cases get optimised out.

Mutability of a transaction reference does not indicate mutability of the underlying database, but rather exclusivity for enforcement of child transaction semantics.

Ownership

Transactions support all three ownership modes (but owned mode is not useful). See ReadTransaction and WriteTransaction for details.

Lifetime

A ConstTransaction must be strictly outlived by its Environment.

'env is covariant: given two lifetimes 'x and 'y where 'x: 'y, a &ConstTransaction<'x> will implicitly coerce to &ConstTransaction<'y>.

fn convariance<'x, 'y>(db: &lmdb::ConstTransaction<'x>)
where 'x: 'y {
  let _db2: &lmdb::ConstTransaction<'y> = db;
}

Because of this property, if you need to hold onto an &lmdb::ConstTransaction and must explicitly name both lifetimes, it is usually best to use the same lifetime for both the reference and the parameter, eg &'x lmdb::ConstTransaction<'x>.

Implementations

impl<'env> ConstTransaction<'env>

pub fn access(&self) -> ConstAccessor<'_>

Returns an accessor used to manipulate data in this transaction.

Ownership

Unlike most other lmdb-zero APIs, accessors do not support shared ownership modes (e.g., where the accessor would hold on to a Rc<ConstTransaction>). If you need dynamically-managed lifetime, instead simply drop the accessor and get a new one the next time one is needed.

Panics

Panics if this function has already been called on this transaction and the returned value has not yet been dropped.

Example

let txn = lmdb::ReadTransaction::new(&env).unwrap();
// Get access the first time
let access = txn.access();

// You can't get the accessor again in the same scope, since this
// would create two references to the same logical memory and allow
// creating aliased mutable references and so forth.
let access2 = txn.access(); // PANIC!

pub fn cursor<'txn, 'db, DB>(&'txn self, db: DB) -> Result<Cursor<'txn, 'db>> where
    DB: Into<Supercow<'db, Database<'db>>>, 

Creates a new cursor scoped to this transaction, bound to the given database.

This method is functionally equivalent to the method on CreateCursor and exists for convenience and backwards-compatibility.

If you have an, e.g., Rc<ReadTransaction> and want to get a Cursor<'static,'db>, make sure you have the CreateCursor trait imported so that the needed alternate implementations of this method are available.

pub fn id(&self) -> usize

Returns the internal id of this transaction.

pub fn db_stat(&self, db: &Database<'_>) -> Result<Stat>

Retrieves statistics for a database.

pub fn db_flags(&self, db: &Database<'_>) -> Result<Flags>

Retrieve the DB flags for a database handle.

Trait Implementations

impl<'txn, 'env: 'txn> CreateCursor<'txn> for &'txn ConstTransaction<'env>

fn cursor<'db, DB>(&self, db: DB) -> Result<Cursor<'txn, 'db>> where
    DB: Into<Supercow<'db, Database<'db>>>, 

Create a cursor using self as the reference to the containing transaction and db as the database the cursor will read from and write into.

impl<'env> Debug for ConstTransaction<'env>

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

Formats the value using the given formatter.