Typedefs
typedef struct MDBX_txn	MDBX_txn
	Opaque structure for a transaction handle. More...

Enumerations
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_NOMETASYNC = MDBX_NOMETASYNC, MDBX_TXN_NOSYNC = MDBX_SAFE_NOSYNC }

Functions
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. More...

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. More...

LIBMDBX_API int	mdbx_txn_set_userctx (MDBX_txn txn, void ctx)
	Sets application information associated (a context pointer) with the transaction. More...

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API void *	mdbx_txn_get_userctx (const MDBX_txn *txn)
	Returns an application information (a context pointer) associated with the transaction. More...

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_env *	mdbx_txn_env (const MDBX_txn *txn)
	Returns the transaction's MDBX_env. More...

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int	mdbx_txn_flags (const MDBX_txn *txn)
	Return the transaction's flags. More...

int	mdbx_txn_commit (MDBX_txn *txn)
	Commit all the operations of a transaction into the database. More...

LIBMDBX_API int	mdbx_txn_abort (MDBX_txn *txn)
	Abandon all the operations of the transaction instead of saving them. More...

LIBMDBX_API int	mdbx_txn_break (MDBX_txn *txn)
	Marks transaction as broken. More...

LIBMDBX_API int	mdbx_txn_reset (MDBX_txn *txn)
	Reset a read-only transaction. More...

LIBMDBX_API int	mdbx_txn_renew (MDBX_txn *txn)
	Renew a read-only transaction. More...

Detailed Description

Typedef Documentation

◆ MDBX_txn

typedef struct MDBX_txn MDBX_txn

Opaque structure for a transaction handle.

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

See also: mdbx_txn_begin(); mdbx_txn_commit(); mdbx_txn_abort()

Enumeration Type Documentation

◆ MDBX_txn_flags_t

enum MDBX_txn_flags_t

Transaction flags

See also: mdbx_txn_begin(); mdbx_txn_flags()

Enumerator
MDBX_TXN_READWRITE	Start read-write transaction. Only one write transaction may be active at a time. Writes are fully serialized, which guarantees that writers can never deadlock.
MDBX_TXN_RDONLY	Start read-only transaction. There can be multiple read-only transactions simultaneously that do not block each other and a write transactions.
MDBX_TXN_RDONLY_PREPARE	Prepare but not start read-only transaction. Transaction will not be started immediately, but created transaction handle will be ready for use with mdbx_txn_renew(). This flag allows to preallocate memory and assign a reader slot, thus avoiding these operations at the next start of the transaction.
MDBX_TXN_TRY	Do not block when starting a write transaction.
MDBX_TXN_NOMETASYNC	Exactly the same as MDBX_NOMETASYNC, but for this transaction only
MDBX_TXN_NOSYNC	Exactly the same as MDBX_SAFE_NOSYNC, but for this transaction only

Function Documentation

◆ mdbx_txn_abort()

LIBMDBX_API int mdbx_txn_abort ( MDBX_txn * txn )

Abandon all the operations of the transaction instead of saving them.

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().

Parameters

[in] 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 values

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_txn_begin()

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

inline

Create a transaction for use with the environment.

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. If MDBX_NOTLS is in use, this does not apply to read-only transactions.; Cursors may not span transactions.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	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.
[in]	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

[out] 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 values

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.

◆ mdbx_txn_begin_ex()

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.

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. If MDBX_NOTLS is in use, this does not apply to read-only transactions.; Cursors may not span transactions.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	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.
[in]	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

[out]	txn	Address where the new MDBX_txn handle will be stored.
[in]	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 values

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.

◆ mdbx_txn_break()

LIBMDBX_API int mdbx_txn_break ( MDBX_txn * txn )

Marks transaction as broken.

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

[in] txn A transaction handle returned by mdbx_txn_begin().

See also: mdbx_txn_abort(); mdbx_txn_reset(); mdbx_txn_commit()

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

◆ mdbx_txn_commit()

int mdbx_txn_commit ( MDBX_txn * txn )

inline

Commit all the operations of a transaction into the database.

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

[in] 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 values

MDBX_RESULT_TRUE	Transaction was aborted since it should be aborted due to previous errors.
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	A system-level I/O error occurred.
MDBX_ENOMEM	Out of memory.

◆ mdbx_txn_env()

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_env* mdbx_txn_env ( const MDBX_txn * txn )

Returns the transaction's MDBX_env.

Parameters

[in] txn A transaction handle returned by mdbx_txn_begin()

◆ mdbx_txn_flags()

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_txn_flags ( const MDBX_txn * txn )

Return the transaction's flags.

This returns the flags associated with this transaction.

Parameters

[in] txn A transaction handle returned by mdbx_txn_begin().

Returns: A transaction flags, valid if input is an valid transaction, otherwise -1.

◆ mdbx_txn_get_userctx()

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API void* mdbx_txn_get_userctx ( const MDBX_txn * txn )

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

See also: mdbx_txn_set_userctx()

Parameters

[in] 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.

◆ mdbx_txn_renew()

LIBMDBX_API int mdbx_txn_renew ( MDBX_txn * txn )

Renew a read-only transaction.

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.

Parameters

[in] 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 values

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_txn_reset()

LIBMDBX_API int mdbx_txn_reset ( MDBX_txn * txn )

Reset a read-only transaction.

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_NOTLS 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_NOTLS 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

[in] 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 values

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_txn_set_userctx()

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

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

See also: mdbx_txn_get_userctx()

Parameters

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

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

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MDBX_txn

Enumeration Type Documentation

◆ MDBX_txn_flags_t

Function Documentation

◆ mdbx_txn_abort()

◆ mdbx_txn_begin()

◆ mdbx_txn_begin_ex()

◆ mdbx_txn_break()

◆ mdbx_txn_commit()

◆ mdbx_txn_env()

◆ mdbx_txn_flags()

◆ mdbx_txn_get_userctx()

◆ mdbx_txn_renew()

◆ mdbx_txn_reset()

◆ mdbx_txn_set_userctx()