Peta::LMDB::Txn#

📦 std

A transaction: everything read from or written to an LMDB environment happens in one.

$env->begin starts a write transaction, $env->begin(MDB_RDONLY) a read one. A read transaction sees the data as it was when it began, never waits and never blocks a writer. A write transaction sees its own writes; nothing it writes is visible elsewhere until commit makes all of it durable at once, and abort - or the transaction going out of scope - discards all of it. There is one write transaction at a time across all processes using the file.

Keys and values are byte strings: a string with characters over 255 croaks Wide character. In a database opened with MDB_INTEGERKEY the keys are unsigned integers, and with MDB_DUPSORT|MDB_INTEGERDUP the values.

Synopsis#

my $txn = $env->begin;
my $db  = $txn->open_db('users', MDB_CREATE);
$txn->put($db, alice => 'admin');
print $txn->get($db, 'alice'), "\n";    # admin
$txn->commit;

Edge cases#

  • After commit or abort the transaction is over: using it croaks Peta::LMDB: the transaction has ended.

  • While a child transaction (begin on a transaction) is live, using its parent croaks the transaction has a live child transaction.

Functions#

Reading and writing#

get#

Look up a key; the value, or undef when the key is not stored.

get_view#

Look up a key and make a variable the value itself, without copying it: for large values read once.

put#

Store a value under a key.

del#

Delete a key - in an MDB_DUPSORT database all its values - or, with a value, just that one value: $txn->del($db, $key), $txn->del($db, $key, $value). True when something was deleted, false when there was nothing to delete.

cursor#

Open a cursor on a database: $txn->cursor($db), a Peta::LMDB::Cursor that walks the keys in order. It ends with the transaction; a read transaction’s cursor can be moved to another read transaction with renew.

Databases#

open_db#

Open a database of the environment, for this and later transactions.

stat#

A database’s statistics, as a hash reference: entries (the number of items), depth, branch_pages, leaf_pages, overflow_pages, psize.

drop#

Empty a database: $txn->drop($db). $txn->drop($db, 1) deletes the database itself, after which its handle is no longer valid.

db_flags#

The MDB_* flags a database was created with, as a number to test with &.

cmp#

Compare two keys as the database orders them - by its set_compare sub, or LMDB’s order for its flags: -1, 0 or 1, as cmp returns.

dcmp#

Compare two values as an MDB_DUPSORT database orders a key’s values - by its set_dupsort sub, or LMDB’s order: -1, 0 or 1.

Ending a transaction#

commit#

Make the transaction’s writes durable and visible, and end it. A failure croaks; the transaction is over either way. Committing a read transaction ends it, keeping the databases it opened.

abort#

Discard the transaction’s writes and end it. Ending a transaction that has already ended does nothing. A transaction that goes out of scope is aborted.

reset#

Let a read transaction’s snapshot go, keeping the transaction for renew: cheaper than ending and beginning, for a reader that pauses. A write transaction croaks reset needs a read transaction.

renew#

Give a reset read transaction a fresh snapshot of the data as it is now.

Nesting#

begin#

Start a child transaction inside a write transaction: $txn->begin. Its writes join the parent’s at its commit, or vanish at its abort, while the parent’s other writes stand. The parent cannot be used until the child ends. A read transaction cannot have children.

Information#

id#

The transaction’s ID: for a write transaction its own, for a read one the ID of the commit its snapshot shows.

env#

The transaction’s environment, a Peta::LMDB::Env.