txn handle & its lifecycle

[sidnt]

a transaction handle in lmdb is eventually a data object in the program runtime. a region of memory.

a transaction handle is discarded via either mdb_txn_abort or mdb_txn_commit. which is a good usecase for brackets. #design

lifecycle tldr; create - use - destroy

a txn handle is created within an environment.

can >1 txn handles be created within an env? #faq seems like. as there can be many RO transactions active in an environment.

---

transactions are always required, as they provide a consistent and isolated view of the data.

The library is fully thread-aware and supports concurrent read/write access from multiple processes and threads.

[sidnt]

mdb_txn_begin creates a transaction handle for use within the environment.

The transaction handle may be discarded using mdb_txn_abort() or mdb_txn_commit().

mdb_txn_begin(env handle, parent txn if any, txn flags): txn handle

[sidnt]

Transactions, Rollbacks, etc. . To actually get anything done, a transaction must be committed using mdb_txn_commit(). Alternatively, all of a transaction's operations can be discarded using mdb_txn_abort(). In a read-only transaction, any cursors will not automatically be freed. In a read-write transaction, all cursors will be freed and must not be used again. . For read-only transactions, obviously there is nothing to commit to storage. The transaction still must eventually be aborted to close any database handle(s) opened in it, or committed to keep the database handles around for reuse in new transactions. . In addition, as long as a transaction is open, a consistent view of the database is kept alive, which requires storage. A read-only transaction that no longer requires this consistent view should be terminated (committed or aborted) when the view is no longer needed (but see below for an optimization). . There can be multiple simultaneously active read-only transactions but only one that can write. Once a single read-write transaction is opened, all further attempts to begin one will block until the first one is committed or aborted. This has no effect on read-only transactions, however, and they may continue to be opened at any time. .

Once a single read-write transaction is opened, all further attempts to begin one will block until the first one is committed or aborted.

[sidnt]

anywhere it's written in source code to create an RW txn handle, be cautious around that code. once an RW txn handle is created, creation of the rest will be blocked (if locking is enabled on the env)

so an RW txn handle should be bracketed, creation bracketed around a genuine need to update a keyset, and a guaranteed disposal after the transaction.

if it fails, as a first cut, decide on the retry in the domain land.

[sidnt]

an RW txn lifecycle

• get an env handle
• with it, create an RW txn handle, txn0
• the dbi handles that txn0 aims for, might / might not, be already open
• for dbis that aren't open yet, but needed nevertheless, open them
• all required dbis are open now
• mdb_get/put/del directly, using txn0 handle and pre-existing dbi handles
• release the txn handle. either:
  • commit txn handle txn0 to propagate the changes.
  • abort to discard the changes. aborting will close the dbi handles(!)

    If the transaction is aborted the handle will be closed automatically. ref

[sidnt]

... a read-only Txn. It only sees data that existed at Txn creation time. ref