Group c_transactions

Public Types

Type	Name
typedef struct MDBX_txn	MDBX_txn Opaque structure for a transaction handle.
enum	MDBX_txn_flags_t

Public Functions

Type	Name
int	mdbx_txn_abort (MDBX_txn * txn) Abandons all the operations of the transaction instead of saving ones.
LIBMDBX_API int	mdbx_txn_abort_ex (MDBX_txn * txn, MDBX_commit_latency * latency) Abandons all the operations of the transaction instead of saving ones with collecting latencies information.
LIBMDBX_API int	mdbx_txn_amend (MDBX_txn * read_txn, MDBX_txn ptr_write_txn, MDBX_txn_flags_t** flags, void * context) Starts a writing transaction to amending data in the MVCC-snapshot used by the read-only transaction.
int	mdbx_txn_begin (MDBX_env * env, MDBX_txn * parent, MDBX_txn_flags_t flags, MDBX_txn ** txn) Create a transaction for use with the environment.
LIBMDBX_API int	mdbx_txn_begin_ex (MDBX_env * env, MDBX_txn * parent, MDBX_txn_flags_t flags, MDBX_txn ** txn, void * context) Create a transaction with a user provided context pointer for use with the environment.
LIBMDBX_API int	mdbx_txn_break (MDBX_txn * txn) Marks transaction as broken to prevent further operations.
LIBMDBX_API int	mdbx_txn_checkpoint (MDBX_txn * txn, MDBX_txn_flags_t weakening_durability, MDBX_commit_latency * latency) Commits all the operations of the transaction and immediately starts next without releasing any locks.
LIBMDBX_API int	mdbx_txn_clone (const MDBX_txn * origin, MDBX_txn ** in_out_clone, void * context) Starts a read-only clone of a given transaction.
int	mdbx_txn_commit (MDBX_txn * txn) Commits all the operations of the transaction into the database.
LIBMDBX_API int	mdbx_txn_commit_embark_read (MDBX_txn ptxn, MDBX_commit_latency** * latency) Commits all the operations of the transaction and immediately starts read transaction before release locks.
LIBMDBX_API int	mdbx_txn_commit_ex (MDBX_txn * txn, MDBX_commit_latency * latency) Commits all changes of the transaction into a database with collecting latencies information.
LIBMDBX_API MDBX_env *	mdbx_txn_env (const MDBX_txn * txn) Returns the transaction's MDBX_env .
LIBMDBX_API MDBX_txn_flags_t	mdbx_txn_flags (const MDBX_txn * txn) Return the transaction's flags.
LIBMDBX_API void *	mdbx_txn_get_userctx (const MDBX_txn * txn) Returns an application information (a context pointer) associated with the transaction.
LIBMDBX_API int	mdbx_txn_park (MDBX_txn * txn, bool autounpark) Puts the reading transaction in a "parked" state.
LIBMDBX_API int	mdbx_txn_refresh (MDBX_txn * txn) Refresh a read-only transaction for a recent data.
LIBMDBX_API int	mdbx_txn_renew (MDBX_txn * txn) Renew a read-only transaction.
LIBMDBX_API int	mdbx_txn_reset (MDBX_txn * txn) Reset a read-only transaction.
LIBMDBX_API int	mdbx_txn_rollback (MDBX_txn * txn) Rolls back all uncommitted changes within the write transaction and keeps it running.
LIBMDBX_API int	mdbx_txn_set_userctx (MDBX_txn * txn, void * ctx) Sets application information associated (a context pointer) with the transaction.
LIBMDBX_API int	mdbx_txn_unpark (MDBX_txn * txn, bool restart_if_ousted) Unparks a previously parked reading transaction.

Public Types Documentation

typedef MDBX_txn

Opaque structure for a transaction handle.

typedef struct MDBX_txn MDBX_txn;

All table operations require a transaction handle. Transactions may be read-only or read-write.

See also: mdbx_txn_begin()

See also: mdbx_txn_commit()

See also: mdbx_txn_abort()

enum MDBX_txn_flags_t

enum MDBX_txn_flags_t {
    MDBX_TXN_READWRITE = 0,
    MDBX_TXN_RDONLY = MDBX_RDONLY,
    MDBX_TXN_RDONLY_PREPARE = MDBX_RDONLY | MDBX_NOMEMINIT,
    MDBX_TXN_TRY = UINT32_C(0x10000000),
    MDBX_TXN_NOWEAKING = 0,
    MDBX_TXN_NOMETASYNC = MDBX_NOMETASYNC,
    MDBX_TXN_NOSYNC = MDBX_SAFE_NOSYNC,
    MDBX_TXN_INVALID = INT32_MIN,
    MDBX_TXN_FINISHED = 0x01,
    MDBX_TXN_ERROR = 0x02,
    MDBX_TXN_DIRTY = 0x04,
    MDBX_TXN_SPILLS = 0x08,
    MDBX_TXN_HAS_CHILD = 0x10,
    MDBX_TXN_PARKED = 0x20,
    MDBX_TXN_AUTOUNPARK = 0x40,
    MDBX_TXN_OUSTED = 0x80,
    MDBX_TXN_BLOCKED = MDBX_TXN_FINISHED | MDBX_TXN_ERROR | MDBX_TXN_HAS_CHILD | MDBX_TXN_PARKED
};

Transaction flags

See also: mdbx_txn_begin()

See also: mdbx_txn_flags()

Public Functions Documentation

function mdbx_txn_abort

Abandons all the operations of the transaction instead of saving ones.

inline int mdbx_txn_abort (
    MDBX_txn * txn
)

The transaction handle is freed. It and its cursors must not be used again after this call, except with mdbx_cursor_renew() and mdbx_cursor_close().

If the current thread is not eligible to manage the transaction then the MDBX_THREAD_MISMATCH error will returned. Otherwise the transaction will be aborted and its handle is freed. Thus, a result other than MDBX_THREAD_MISMATCH means that the transaction is terminated: * Resources are released; * Transaction handle is invalid; * Cursor(s) associated with transaction must not be used, except with mdbx_cursor_renew() and mdbx_cursor_close(). Such cursor(s) must be closed explicitly by mdbx_cursor_close() before or after transaction abort, either can be reused with mdbx_cursor_renew() until it will be explicitly closed by mdbx_cursor_close().

See also: mdbx_txn_abort_ex()

See also: mdbx_txn_amend()

See also: mdbx_txn_checkpoint()

See also: mdbx_txn_commit()

See also: mdbx_txn_refresh()

See also: mdbx_txn_reset()

See also: mdbx_txn_rollback()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Transaction is already finished or never began.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.

function mdbx_txn_abort_ex

Abandons all the operations of the transaction instead of saving ones with collecting latencies information.

LIBMDBX_API int mdbx_txn_abort_ex (
    MDBX_txn * txn,
    MDBX_commit_latency * latency
)

See also: mdbx_txn_abort()

See also: mdbx_txn_refresh()

See also: mdbx_txn_reset()

See also: mdbx_txn_commit_ex()

See also: mdbx_txn_checkpoint()

See also: mdbx_txn_rollback()

See also: mdbx_txn_amend()

Warning:

This function may be changed in future releases.

function mdbx_txn_amend

Starts a writing transaction to amending data in the MVCC-snapshot used by the read-only transaction.

LIBMDBX_API int mdbx_txn_amend (
    MDBX_txn * read_txn,
    MDBX_txn ** ptr_write_txn,
    MDBX_txn_flags_t flags,
    void * context
)

The function tries to start a writing transaction to amend the snapshot of a data associated with a given reading transaction. However, such an operation is not possible if at least one writing transaction has been committed after the start of the specified read-only transaction. In this case, no action is performed and the MDBX_RESULT_TRUE code is returned.

If successful, the handle of the new writing transaction is returned, and the previous reading transaction is finished. With this if MDBX_TXN_RDONLY_PREPARE is present in the flags, the handle of the previous reading transaction will be preserved for subsequent reuse via mdbx_txn_renew(), otherwise it will be released and will become unavailable.

Note:

In future versions of libmdbx, it is planned to implement the transfer of the cursors state from a finished transaction to a new one that is being launched. The relevance of such an opportunity is currently being studied, please contact the developers if you need such.

See also: mdbx_txn_checkpoint()

See also: mdbx_txn_rollback()

See also: mdbx_txn_commit_ex()

See also: mdbx_txn_refresh()

See also: mdbx_txn_begin_ex()

Parameters:

read_txn A read-only transaction handle returned by mdbx_txn_begin().
ptr_write_txn A pointer for returning the MDBX_txn handle of newly started writing transaction.
flags Special options for new write transaction. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here:
MDBX_TXN_RDONLY_PREPARE. Do not release the source read-only transaction, but preserve it handle to be reused by mdbx_txn_renew().
MDBX_TXN_TRY. Do not block when starting a write transaction.
MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC. Do not sync data to disk corresponding to MDBX_NOMETASYNC or MDBX_SAFE_NOSYNC description.

See also: SYNC MODES

Parameters:

context A pointer to application context to be associated with created transaction and could be retrieved by mdbx_txn_get_userctx() until transaction finished.

Returns:

A non-zero error value on failure and 0 on success, some possibilities are:

Return value:

MDBX_RESULT_TRUE A more recent MVCC-snapshot has been committed after reading transaction was started and data cannot be amended based on the desired data snapshot, no actions have been performed.
MDBX_TXN_OVERLAPPING The current thread is already executing a write transaction.
MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Unexpected or wrong transaction state.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.

Warning:

This function may be changed in future releases.

function mdbx_txn_begin

Create a transaction for use with the environment.

inline int mdbx_txn_begin (
    MDBX_env * env,
    MDBX_txn * parent,
    MDBX_txn_flags_t flags,
    MDBX_txn ** txn
)

The transaction handle may be discarded using mdbx_txn_abort() or mdbx_txn_commit().

See also: mdbx_txn_begin_ex()

Note:

A transaction and its cursors must only be used by a single thread, and a thread may only have a single transaction at a time unless the MDBX_NOSTICKYTHREADS is used.

Note:

Cursors may not span transactions.

Parameters:

env An environment handle returned by mdbx_env_create().
parent If this parameter is non-NULL, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level. A parent transaction and its cursors may not issue any other operations than mdbx_txn_commit and mdbx_txn_abort() while it has active child transactions.
flags Special options for this transaction. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here:
MDBX_RDONLY This transaction will not perform any write operations.
MDBX_TXN_TRY Do not block when starting a write transaction.
MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC. Do not sync data to disk corresponding to MDBX_NOMETASYNC or MDBX_SAFE_NOSYNC description.

See also: SYNC MODES

Parameters:

txn Address where the new MDBX_txn handle will be stored.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_UNABLE_EXTEND_MAPSIZE Another process wrote data beyond this MDBX_env's mapsize and this environment map must be resized as well. See mdbx_env_set_mapsize().
MDBX_READERS_FULL A read-only transaction was requested and the reader lock table is full. See mdbx_env_set_maxreaders().
MDBX_ENOMEM Out of memory.
MDBX_BUSY The write transaction is already started by the current thread.

function mdbx_txn_begin_ex

Create a transaction with a user provided context pointer for use with the environment.

LIBMDBX_API int mdbx_txn_begin_ex (
    MDBX_env * env,
    MDBX_txn * parent,
    MDBX_txn_flags_t flags,
    MDBX_txn ** txn,
    void * context
)

The transaction handle may be discarded using mdbx_txn_abort() or mdbx_txn_commit().

See also: mdbx_txn_begin()

Note:

A transaction and its cursors must only be used by a single thread, and a thread may only have a single transaction at a time unless the MDBX_NOSTICKYTHREADS is used.

Note:

Cursors may not span transactions.

Parameters:

env An environment handle returned by mdbx_env_create().
parent If this parameter is non-NULL, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level. A parent transaction and its cursors may not issue any other operations than mdbx_txn_commit and mdbx_txn_abort() while it has active child transactions.
flags Special options for this transaction. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here:
MDBX_TXN_RDONLY This transaction will not perform any write operations.
MDBX_TXN_TRY Do not block when starting a write transaction.
MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC. Do not sync data to disk corresponding to MDBX_NOMETASYNC or MDBX_SAFE_NOSYNC description.

See also: SYNC MODES

Parameters:

txn Address where the new MDBX_txn handle will be stored.
context A pointer to application context to be associated with created transaction and could be retrieved by mdbx_txn_get_userctx() until transaction finished.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_UNABLE_EXTEND_MAPSIZE Another process wrote data beyond this MDBX_env's mapsize and this environment map must be resized as well. See mdbx_env_set_mapsize().
MDBX_READERS_FULL A read-only transaction was requested and the reader lock table is full. See mdbx_env_set_maxreaders().
MDBX_ENOMEM Out of memory.
MDBX_BUSY The write transaction is already started by the current thread.

function mdbx_txn_break

Marks transaction as broken to prevent further operations.

LIBMDBX_API int mdbx_txn_break (
    MDBX_txn * txn
)

Function keeps the transaction handle and corresponding locks, but makes impossible to perform any operations within a broken transaction. Broken transaction must then be aborted explicitly later.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().

See also: mdbx_txn_abort()

See also: mdbx_txn_reset()

See also: mdbx_txn_commit()

Returns:

A non-zero error value on failure and 0 on success.

function mdbx_txn_checkpoint

Commits all the operations of the transaction and immediately starts next without releasing any locks.

LIBMDBX_API int mdbx_txn_checkpoint (
    MDBX_txn * txn,
    MDBX_txn_flags_t weakening_durability,
    MDBX_commit_latency * latency
)

The function's actions are similar to the sequence of calls mdbx_txn_commit_ex() and then mdbx_txn_begin(MDBX_TXN_READWRITE) if the first one is successful, but without releasing the locks, which ensures that there are no other changes after the current changes are committed and the transaction begins.

See also: mdbx_txn_amend()

See also: mdbx_txn_commit_ex()

See also: mdbx_txn_refresh()

See also: mdbx_txn_begin()

See also: mdbx_txn_rollback()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
weakening_durability Additional flags to weaken durability for committing changes.
latency An optional pointer for getting information of latencies during the commit stages.

Returns:

A non-zero error value on failure and 0 on success, some possibilities are:

Return value:

MDBX_RESULT_TRUE The transaction does not contain any changes to commit, no actions have been performed.
MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Unexpected or wrong transaction state.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL or weakening_durability is invalid.

Warning:

This function may be changed in future releases.

function mdbx_txn_clone

Starts a read-only clone of a given transaction.

LIBMDBX_API int mdbx_txn_clone (
    const MDBX_txn * origin,
    MDBX_txn ** in_out_clone,
    void * context
)

Note:

Cloning read-only transactions without MDBX_NOSTICKYTHREADS mode is pointless and is not allowed.

Cloning a read-only transaction generates a transaction reading the same MVCC snapshot of the database. However, cloning a read-write transaction is also explicitly allowed and generates a read transaction that reads the original MVCC-snapshot of the database without uncommitted changes. This feature is a specialized tool for implementing database compactification, data transformation, replication and other specific scenarios.

In the non- MDBX_NOSTICKYTHREADS operation mode, the cloned transaction becomes binded to the current thread. At the same time, it is clearly assumed that the origin transaction is linked to another thread.

Warning:

It is required to ensure that the original transaction is not used, much less interrupted or restarted by another thread, until this function done.

When cloning read-only transactions, the parking state of original is preserved and inherited by cloned transaction. Cursors and other objects associated with the original transaction are not affected and are not copied into the cloned transaction.

The function provides for both the creation of a new transaction handle and the reuse of a transaction previously stopped by mdbx_txn_reset().

Note:

Cloning of a write transactions with pending changes (aka dirtied) is prohibited to avoid confusion.

Parameters:

origin An transaction handle returned by mdbx_txn_begin_ex() or mdbx_txn_begin().
in_out_clone Address of the MDBX_txn handle that wants to be reused, or where to store the handle of the new transaction. The handle passed by the pointer must be initialized at the input anycase. If the pointed handle at input is NULL, then a new transaction will be created and returned there, otherwise it must be a valid handle of read-only transaction for reuse.
context A pointer to application context to be associated with started transaction and could be retrieved by mdbx_txn_get_userctx() until transaction finished. Just use NULL if doubt.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_EINVAL An invalid parameter was specified, i.e. the in_out_clone is NULL.
MDBX_BAD_TXN Origin transaction is already finished or never began, or handle referenced by in_out_clone is invalid or not a read-only transaction. Cloning of a write transactions with pending changes (aka dirtied) is also prohibited to avoid confusion.
MDBX_EBADSIGN Origin transaction object or reference by in_out_clone, has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_OUSTED Cloned was outed immediately for the sake of recycling old MVCC snapshots.
MDBX_MVCC_RETARDED The MVCC snapshot used by origin transaction was bygone.
MDBX_READERS_FULL A read-only transaction was requested and the reader lock table is full. See mdbx_env_set_maxreaders().
MDBX_ENOMEM Out of memory during creating new transaction.

function mdbx_txn_commit

Commits all the operations of the transaction into the database.

inline int mdbx_txn_commit (
    MDBX_txn * txn
)

See also: mdbx_txn_checkpoint()

See also: mdbx_txn_rollback()

See also: mdbx_txn_commit_ex()

See also: mdbx_txn_refresh()

See also: mdbx_txn_begin_ex()

See also: mdbx_txn_abort()

See also: mdbx_txn_abort_ex() If the current thread is not eligible to manage the transaction then the MDBX_THREAD_MISMATCH error will returned. Otherwise the transaction will be committed and its handle is freed. If the transaction cannot be committed, it will be aborted with the corresponding error returned.

Thus, a result other than MDBX_THREAD_MISMATCH means that the transaction is terminated: * Resources are released; * Transaction handle is invalid; * Cursor(s) associated with transaction must not be used, except with mdbx_cursor_renew() and mdbx_cursor_close(). Such cursor(s) must be closed explicitly by mdbx_cursor_close() before or after transaction commit, either can be reused with mdbx_cursor_renew() until it will be explicitly closed by mdbx_cursor_close().

Parameters:

txn A transaction handle returned by mdbx_txn_begin().

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_RESULT_TRUE Transaction was aborted since it should be aborted due to previous errors, either no changes were made during the transaction, and the build time option MDBX_NOSUCCESS_PURE_COMMIT was enabled.
MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Transaction is already finished or never began.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.
MDBX_ENOSPC No more disk space.
MDBX_EIO An error occurred during the flushing/writing data to a storage medium/disk.
MDBX_ENOMEM Out of memory.

function mdbx_txn_commit_embark_read

Commits all the operations of the transaction and immediately starts read transaction before release locks.

LIBMDBX_API int mdbx_txn_commit_embark_read (
    MDBX_txn ** ptxn,
    MDBX_commit_latency * latency
)

The function's actions are similar to the sequence of calls mdbx_txn_commit_ex() and then mdbx_txn_begin(MDBX_TXN_RDONLY) if the first one is successful, but before release the locks, which ensures that there are no other changes after the current changes are committed and the read transaction begins.

Note:

In future versions of libmdbx, it is planned to implement the transfer of the cursors state from a finished transaction to a new one that is being launched. The relevance of such an opportunity is currently being studied, please contact the developers if you need such.

See also: mdbx_txn_amend()

See also: mdbx_txn_checkpoint()

See also: mdbx_txn_commit_ex()

See also: mdbx_txn_refresh()

See also: mdbx_txn_begin()

Parameters:

ptxn A pointer to the transaction handle returned by mdbx_txn_begin().
latency An optional pointer for getting information of latencies during the commit stages.

Returns:

A non-zero error value on failure and 0 on success, some possibilities are:

Return value:

MDBX_RESULT_TRUE The transaction does not contain any changes to commit, no actions have been performed.
MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Unexpected or wrong transaction state.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.

Warning:

This function may be changed in future releases.

function mdbx_txn_commit_ex

Commits all changes of the transaction into a database with collecting latencies information.

LIBMDBX_API int mdbx_txn_commit_ex (
    MDBX_txn * txn,
    MDBX_commit_latency * latency
)

See also: mdbx_txn_checkpoint()

See also: mdbx_txn_commit_ex()

See also: mdbx_txn_refresh()

See also: mdbx_txn_begin_ex()

See also: mdbx_txn_abort()

See also: mdbx_txn_abort_ex()

See also: mdbx_txn_rollback() If the current thread is not eligible to manage the transaction then the MDBX_THREAD_MISMATCH error will returned. Otherwise the transaction will be committed and its handle is freed. If the transaction cannot be committed, it will be aborted with the corresponding error returned.

Thus, a result other than MDBX_THREAD_MISMATCH means that the transaction is terminated: * Resources are released; * Transaction handle is invalid; * Cursor(s) associated with transaction must not be used, except with mdbx_cursor_renew() and mdbx_cursor_close(). Such cursor(s) must be closed explicitly by mdbx_cursor_close() before or after transaction commit, either can be reused with mdbx_cursor_renew() until it will be explicitly closed by mdbx_cursor_close().

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
latency An optional pointer for getting information of latencies during the commit stages.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_RESULT_TRUE Transaction was aborted since it should be aborted due to previous errors, either no changes were made during the transaction, and the build time option MDBX_NOSUCCESS_PURE_COMMIT was enabled.
MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Transaction is already finished or never began.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.
MDBX_ENOSPC No more disk space.
MDBX_EIO An error occurred during the flushing/writing data to a storage medium/disk.
MDBX_ENOMEM Out of memory.

Warning:

This function may be changed in future releases.

function mdbx_txn_env

Returns the transaction's MDBX_env .

LIBMDBX_API  MDBX_env * mdbx_txn_env (
    const MDBX_txn * txn
)

Parameters:

txn A transaction handle returned by mdbx_txn_begin()

function mdbx_txn_flags

Return the transaction's flags.

LIBMDBX_API  MDBX_txn_flags_t mdbx_txn_flags (
    const MDBX_txn * txn
)

This returns the flags, including internal, associated with this transaction.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().

Returns:

A transaction flags, valid if input is an valid transaction, otherwise MDBX_TXN_INVALID.

function mdbx_txn_get_userctx

Returns an application information (a context pointer) associated with the transaction.

LIBMDBX_API void * mdbx_txn_get_userctx (
    const MDBX_txn * txn
)

See also: mdbx_txn_set_userctx()

Parameters:

txn An transaction handle returned by mdbx_txn_begin_ex() or mdbx_txn_begin().

Returns:

The pointer which was passed via the context parameter of mdbx_txn_begin_ex() or set by mdbx_txn_set_userctx(), or NULL if something wrong.

function mdbx_txn_park

Puts the reading transaction in a "parked" state.

LIBMDBX_API int mdbx_txn_park (
    MDBX_txn * txn,
    bool autounpark
)

Running read transactions do not allow recycling old MVCC snapshots of data, starting with the oldest used/readable version and all subsequent ones. A parked transaction can be ousted by a write transaction if it interferes with the recycling of garbage (old MVCC snapshots of data). But if no such ousting occurs, then restoring (restoring to a working state and continuing execution) of the reading transaction will be significantly cheaper. Thus, parking transactions allows you to prevent the negative consequences associated with stopping garbage recycling, while keeping overhead costs at a minimum.

To continue execution (reading and/or using data), the parked transaction must be restored using mdbx_txn_unpark(). For ease of use and to prevent unnecessary API calls, using the autounpark parameter, automatic "un-parking" is provided when using a parked transaction in API functions involving data reading.

Warning:

Before restoring/un-parking a transaction, regardless of the autounpark argument, it is forbidden to dereference pointers received earlier when reading data within a parked transaction, since the MVCC-snapshot in which this data is placed is not retained and can be recycled at any time.

A parked transaction without "un-parking" can be aborted, reset, or restarted at any time by using mdbx_txn_abort(), mdbx_txn_reset(), and mdbx_txn_renew(), respectively.

See also: mdbx_txn_unpark()

See also: mdbx_txn_flags()

See also: mdbx_env_set_hsr()

See also: Long-lived read transactions

Parameters:

txn A read transaction started by mdbx_txn_begin().
autounpark Allows you to enable automatic un-parking/restoring of a transaction when calling API functions that involve reading data.

Returns:

A non-zero error value on failure and 0 on success.

function mdbx_txn_refresh

Refresh a read-only transaction for a recent data.

LIBMDBX_API int mdbx_txn_refresh (
    MDBX_txn * txn
)

See also: mdbx_txn_renew()

See also: mdbx_txn_amend()

See also: mdbx_txn_checkpoint()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().

Returns:

A non-zero error value on failure and 0 on success, some possibilities are:

Return value:

MDBX_RESULT_TRUE The transaction is already reading the most recent version of the data, no actions have been performed.
MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Unexpected or wrong transaction state.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.

function mdbx_txn_renew

Renew a read-only transaction.

LIBMDBX_API int mdbx_txn_renew (
    MDBX_txn * txn
)

This acquires a new reader lock for a transaction handle that had been released by mdbx_txn_reset(). It must be called before a reset transaction may be used again.

See also: mdbx_txn_refresh()

See also: mdbx_txn_amend()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Unexpected or wrong transaction state.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.

function mdbx_txn_reset

Reset a read-only transaction.

LIBMDBX_API int mdbx_txn_reset (
    MDBX_txn * txn
)

Abort the read-only transaction like mdbx_txn_abort(), but keep the transaction handle. Therefore mdbx_txn_renew() may reuse the handle. This saves allocation overhead if the process will start a new read-only transaction soon, and also locking overhead if MDBX_NOSTICKYTHREADS is in use. The reader table lock is released, but the table slot stays tied to its thread or MDBX_txn. Use mdbx_txn_abort() to discard a reset handle, and to free its lock table slot if MDBX_NOSTICKYTHREADS is in use.

Cursors opened within the transaction must not be used again after this call, except with mdbx_cursor_renew() and mdbx_cursor_close().

Reader locks generally don't interfere with writers, but they keep old versions of database pages allocated. Thus they prevent the old pages from being reused when writers commit new data, and so under heavy load the database size may grow much more rapidly than otherwise.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Transaction is already finished or never began.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.

function mdbx_txn_rollback

Rolls back all uncommitted changes within the write transaction and keeps it running.

LIBMDBX_API int mdbx_txn_rollback (
    MDBX_txn * txn
)

Aborts and then restarts the transaction, rolling back all uncommitted changes. If the current thread is not eligible to manage the transaction then the MDBX_THREAD_MISMATCH error will returned.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().

Returns:

A non-zero error value on failure and 0 on success, some possibilities are:

Return value:

MDBX_RESULT_TRUE A more recent MVCC-snapshot has been committed after reading transaction was started and data cannot be amended based on the desired data snapshot, no actions have been performed.
MDBX_TXN_OVERLAPPING The current thread is already executing a write transaction.
MDBX_PANIC A fatal error occurred earlier and the environment must be shut down.
MDBX_BAD_TXN Unexpected or wrong transaction state.
MDBX_EBADSIGN Transaction object has invalid signature, e.g. transaction was already terminated or memory was corrupted.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Transaction handle is NULL.

Warning:

This function may be changed in future releases.

function mdbx_txn_set_userctx

Sets application information associated (a context pointer) with the transaction.

LIBMDBX_API int mdbx_txn_set_userctx (
    MDBX_txn * txn,
    void * ctx
)

See also: mdbx_txn_get_userctx()

Parameters:

txn An transaction handle returned by mdbx_txn_begin_ex() or mdbx_txn_begin().
ctx An arbitrary pointer for whatever the application needs.

Returns:

A non-zero error value on failure and 0 on success.

function mdbx_txn_unpark

Unparks a previously parked reading transaction.

LIBMDBX_API int mdbx_txn_unpark (
    MDBX_txn * txn,
    bool restart_if_ousted
)

The function tries to restore a previously parked transaction. If a parked transaction has been ousted in order to recycle old MVCC snapshots, then depending on the restart_if_ousted argument, it is restarted in the same way as mdbx_txn_renew(), either the transaction is reset and the error code MDBX_OUSTED is returned.

See also: mdbx_txn_park()

See also: mdbx_txn_flags()

See also: Long-lived read transactions

Parameters:

txn A read transaction started by mdbx_txn_begin() and then parked by mdbx_txn_park.
restart_if_ousted Allows you to immediately restart a transaction if it has been ousted.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_SUCCESS The parked transaction was successfully restored, or it was not parked.
MDBX_OUSTED The reading transaction was ousted by the writing transaction in order to recycle old MVCC-snapshots, and the restart_if_ousted argument was set to false. The transaction is reset to a similar state after calling mdbx_txn_reset(), but the instance (handle) is not released and can be reused using mdbx_txn_renew(), either released using mdbx_txn_abort().
MDBX_RESULT_TRUE The reading transaction was ousted but has now been restarted to read recent MVCC-snapshot, since restart_if_ousted was set to true.
MDBX_BAD_TXN The transaction has already been finished either it has not been started, or it is not a reading transaction.