Struct Txn 

pub struct Txn {
    batch: WriteBatch,
    engine: Arc<Engine>,
}

Atomic write batch spanning one or more column families from one database.

Every queued map must belong to the captured engine because column family identifiers are interpreted within that database. Dropping an unexecuted transaction leaves the database unchanged.

Fields

batch: WriteBatch

engine: Arc<Engine>

Implementations

impl Txn

pub fn new(engine: &Arc<Engine>) -> Self

Creates an empty transaction for one database engine.

Operations can be appended through the typed or raw queueing methods. The transaction remains inert until Txn::execute consumes it.

impl Txn

pub fn with_capacity_bytes(engine: &Arc<Engine>, capacity_bytes: usize) -> Self

Creates an empty transaction with reserved batch capacity.

capacity_bytes reserves storage for the serialized RocksDB batch representation. The reservation affects allocation only and does not queue an operation.

impl Txn

pub fn insert<I, K, V>(map: &Map, items: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: AsRef<[u8]>, V: AsRef<[u8]>,

Queues raw key and value pairs for one map from a single pass.

The database codec is not applied, and the write batch copies each supplied byte sequence. Empty input produces an empty transaction whose execution is a no-op.

impl Txn

pub fn insert_slice<K, V>(map: &Map, items: &[(K, V)]) -> Self

where K: AsRef<[u8]>, V: AsRef<[u8]>,

Queues a raw slice for one map with a precomputed capacity estimate.

The estimate includes payload lengths and worst-case record overhead before the items are copied into the write batch. Empty input produces an empty transaction.

impl Txn

pub fn insert_each<'a, I, K, V>(items: I) -> Self

where I: IntoIterator<Item = (&'a Map, K, V)>, K: AsRef<[u8]>, V: AsRef<[u8]>,

Queues raw entries across maps from a nonempty single pass.

The first item selects the database engine, and every subsequent map must belong to that same engine. The database codec is not applied to keys or values.

Panics

Panics when items is empty or when any map belongs to a different database engine.

impl Txn

pub fn insert_each_slice<K, V>(items: &[(&Map, K, V)]) -> Self

where K: AsRef<[u8]>, V: AsRef<[u8]>,

Queues a nonempty raw slice across maps with a capacity estimate.

The first item selects the database engine, and every map must belong to that same engine. The database codec is not applied to keys or values.

Panics

Panics when items is empty or when any map belongs to a different database engine.

impl Txn

pub fn put_each<'a, I, K, V>(items: I) -> Self

where I: IntoIterator<Item = (&'a Map, K, V)>, K: Serialize + Debug, V: Serialize,

Serializes and queues entries across maps from a nonempty pass.

The first item selects the database engine, and every map must belong to that same engine. All keys and values are encoded with the database record codec before being copied into the batch.

Panics

Panics when items is empty, a map belongs to another database engine, or serialization of a key or value fails.

impl Txn

pub fn put<K, V>(&mut self, map: &Map, key: K, val: V)

where K: Serialize + Debug, V: Serialize,

Serializes and queues one insertion.

The key and value use the database record codec, and the operation remains pending until Txn::execute. The map must belong to the transaction’s database engine.

Panics

Panics when the map belongs to another database engine or serialization of the key or value fails.

impl Txn

pub fn put_raw<K, V>(&mut self, map: &Map, key: K, val: V)

where K: Serialize + Debug, V: AsRef<[u8]>,

Serializes the key and queues one raw-value insertion.

The key uses the database record codec, while the value bytes are copied unchanged into the batch. The operation remains pending until Txn::execute, and the map must belong to the transaction’s database engine.

Panics

Panics when the map belongs to another database engine or serialization of the key fails.

impl Txn

pub fn raw_put<K, V>(&mut self, map: &Map, key: K, val: V)

where K: AsRef<[u8]>, V: Serialize,

Queues one raw-key insertion after serializing the value.

The key bytes are copied unchanged into the batch, while the value uses the database record codec. The operation remains pending until Txn::execute, and the map must belong to the transaction’s database engine.

Panics

Panics when the map belongs to another database engine or serialization of the value fails.

impl Txn

pub fn del<K>(&mut self, map: &Map, key: K)

where K: Serialize + Debug,

Serializes and queues one deletion.

The key uses the database record codec, and the operation remains pending until Txn::execute. The map must belong to the transaction’s database engine.

Panics

Panics when the map belongs to another database engine or serialization of the key fails.

impl Txn

pub fn del_raw<K>(&mut self, map: &Map, key: K)

where K: AsRef<[u8]>,

Queues one deletion for an already serialized key.

The key bytes are copied into the write batch without invoking the database codec. The map must belong to the transaction’s database engine.

Panics

Panics when the map belongs to another database engine.

impl Txn

pub fn execute(self)

Commits the batch atomically, flushes unless corked, and notifies matching watchers.

An empty transaction returns without touching the engine. For a nonempty batch, notifications occur only after the write and any required flush succeed.

Panics

Panics when RocksDB rejects the batch write or when the required database flush fails.

impl Txn

fn notify(&self)

Notifies watchers after a successful commit for queued keys that resolve to catalog maps.

Keys are parsed lazily from the batch representation and consumed in queue order. Operations without a live map in the engine’s startup catalog are skipped.

impl Txn

pub fn keys(&self) -> impl Iterator<Item = (Arc<Map>, &[u8])> + '_

Iterate queued put and delete keys in insertion order.

The iterator borrows keys directly from the serialized write batch without materializing a container. Keys whose column families are outside the startup map catalog are omitted.

Panics

Iteration panics if a record has an unsupported operation tag, is truncated, or contains a varint whose fifth byte retains its continuation bit.

impl Txn

pub fn len(&self) -> usize

Returns the number of operations queued in the batch.

Both insertions and deletions count as one operation. Inspecting the count does not execute the transaction.

impl Txn

pub fn is_empty(&self) -> bool

Reports whether the batch contains no queued operations.

A newly created or cleared transaction is empty. Executing an empty transaction performs no database work.

impl Txn

pub fn size_in_bytes(&self) -> usize

Returns the encoded size of the RocksDB write batch in bytes.

The size includes batch metadata and queued record data. Inspecting it does not execute the transaction.

impl Txn

pub fn clear(&mut self)

Removes every queued operation from the transaction.

The captured database engine remains attached, so the transaction can be populated again. Executing it before another operation is queued is a no-op.

impl Txn

pub fn insert_raw<K, V>(&mut self, map: &Map, key: K, val: V)

where K: AsRef<[u8]>, V: AsRef<[u8]>,

Queue one unencoded key and value after enforcing map ownership.

Both byte sequences are copied into the write batch without invoking the database codec. The operation remains pending until Txn::execute.

Panics

Panics when the map belongs to another database engine.

impl Txn

fn assert_map(&self, map: &Map)

Verifies that a map belongs to the transaction’s database engine.

RocksDB identifies column families numerically within one database, so accepting a foreign map could target a same-numbered column family in the captured engine.

Panics

Panics when map belongs to a different database engine.

Trait Implementations

impl<'a, K> Extend<(&'a Map, K)> for Txn

where K: AsRef<[u8]>,

Extends this transaction with raw-key deletions across maps.

Each tuple queues its raw key through Txn::del_raw. Every map must belong to the transaction’s database engine.

Panics

Panics when any map belongs to another database engine.

fn extend<I>(&mut self, items: I)

where I: IntoIterator<Item = (&'a Map, K)>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, K, V> Extend<(&'a Map, K, V)> for Txn

where K: AsRef<[u8]>, V: AsRef<[u8]>,

Extends this transaction with raw insertions across maps.

Each tuple queues its raw key and value through Txn::insert_raw. Use Txn::put_each when the keys and values need serialization. Every map must belong to the transaction’s database engine.

Panics

Panics when any map belongs to another database engine.

fn extend<I>(&mut self, items: I)

where I: IntoIterator<Item = (&'a Map, K, V)>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.