Group c_cursors

Public Types

Type	Name
typedef struct MDBX_cursor	MDBX_cursor Opaque structure for navigating through a table.
enum	MDBX_cursor_op Cursor operations This is the set of all operations for retrieving data using a cursor.

Public Functions

Type	Name
LIBMDBX_API int	mdbx_cursor_bind (MDBX_txn * txn, MDBX_cursor * cursor, MDBX_dbi dbi) Bind cursor to specified transaction and DBI-handle.
LIBMDBX_API void	mdbx_cursor_close (MDBX_cursor * cursor) Closes a cursor handle without returning error code.
LIBMDBX_API int	mdbx_cursor_close2 (MDBX_cursor * cursor) Closes a cursor handle with returning error code.
LIBMDBX_API int	mdbx_cursor_compare (const MDBX_cursor * left, const MDBX_cursor * right, bool ignore_multival) Compares the position of the cursors.
LIBMDBX_API int	mdbx_cursor_copy (const MDBX_cursor * src, MDBX_cursor * dest) Copy cursor position and state.
LIBMDBX_API MDBX_cursor *	mdbx_cursor_create (void * context) Create a cursor handle but not bind it to transaction nor DBI-handle.
LIBMDBX_API MDBX_dbi	mdbx_cursor_dbi (const MDBX_cursor * cursor) Return the cursor's table handle.
LIBMDBX_API int	mdbx_cursor_distance (const MDBX_cursor * first, const MDBX_cursor * last, intptr_t * distance, unsigned deepness) Calculates the distance between the cursors at the specified B-tree level.
LIBMDBX_API int	mdbx_cursor_distribute (const MDBX_cursor * first, const MDBX_cursor * last, MDBX_cursor ** array, intptr_t count, unsigned deepness) Distributes cursors for multithreaded range scanning.
LIBMDBX_API int	mdbx_cursor_eof (const MDBX_cursor * cursor) Determines whether the cursor is pointed to a key-value pair or not, i.e. was not positioned or points to the end of data.
LIBMDBX_API void *	mdbx_cursor_get_userctx (const MDBX_cursor * cursor) Get the application information associated with the MDBX_cursor .
LIBMDBX_API int	mdbx_cursor_on_first (const MDBX_cursor * cursor) Determines whether the cursor is pointed to the first key-value pair or not.
LIBMDBX_API int	mdbx_cursor_on_first_dup (const MDBX_cursor * cursor) Determines whether the cursor is on the first or single multi-value corresponding to the key.
LIBMDBX_API int	mdbx_cursor_on_last (const MDBX_cursor * cursor) Determines whether the cursor is pointed to the last key-value pair or not.
LIBMDBX_API int	mdbx_cursor_on_last_dup (const MDBX_cursor * cursor) Determines whether the cursor is on the last or single multi-value corresponding to the key.
LIBMDBX_API int	mdbx_cursor_open (MDBX_txn * txn, MDBX_dbi dbi, MDBX_cursor ** cursor) Create a cursor handle for the specified transaction and DBI handle.
LIBMDBX_API int	mdbx_cursor_renew (MDBX_txn * txn, MDBX_cursor * cursor) Renew a cursor handle for use within the given transaction.
LIBMDBX_API int	mdbx_cursor_reset (MDBX_cursor * cursor) Resets the cursor state.
LIBMDBX_API int	mdbx_cursor_scroll (MDBX_cursor * cursor, intptr_t amount, unsigned deepness) Scrolls the cursor to the specified number of positions at the specified B-tree level.
LIBMDBX_API int	mdbx_cursor_set_userctx (MDBX_cursor * cursor, void * ctx) Set application information associated with the cursor.
LIBMDBX_API MDBX_txn *	mdbx_cursor_txn (const MDBX_cursor * cursor) Return the cursor's transaction handle.
LIBMDBX_API int	mdbx_cursor_unbind (MDBX_cursor * cursor) Unbind cursor from a transaction.
int	mdbx_txn_release_all_cursors (const MDBX_txn * txn, bool unbind) Unbind or closes all cursors of a given transaction and of all its parent transactions if ones are.
LIBMDBX_API int	mdbx_txn_release_all_cursors_ex (const MDBX_txn * txn, bool unbind, size_t * count) Unbind or closes all cursors of a given transaction and of all its parent transactions if ones are.

Public Types Documentation

typedef MDBX_cursor

Opaque structure for navigating through a table.

typedef struct MDBX_cursor MDBX_cursor;

See also: mdbx_cursor_create()

See also: mdbx_cursor_bind()

See also: mdbx_cursor_close()

enum MDBX_cursor_op

Cursor operations This is the set of all operations for retrieving data using a cursor.

enum MDBX_cursor_op {
    MDBX_FIRST,
    MDBX_FIRST_DUP,
    MDBX_GET_BOTH,
    MDBX_GET_BOTH_RANGE,
    MDBX_GET_CURRENT,
    MDBX_GET_MULTIPLE,
    MDBX_LAST,
    MDBX_LAST_DUP,
    MDBX_NEXT,
    MDBX_NEXT_DUP,
    MDBX_NEXT_MULTIPLE,
    MDBX_NEXT_NODUP,
    MDBX_PREV,
    MDBX_PREV_DUP,
    MDBX_PREV_NODUP,
    MDBX_SET,
    MDBX_SET_KEY,
    MDBX_SET_RANGE,
    MDBX_PREV_MULTIPLE,
    MDBX_SET_LOWERBOUND,
    MDBX_SET_UPPERBOUND,
    MDBX_TO_KEY_LESSER_THAN,
    MDBX_TO_KEY_LESSER_OR_EQUAL,
    MDBX_TO_KEY_EQUAL,
    MDBX_TO_KEY_GREATER_OR_EQUAL,
    MDBX_TO_KEY_GREATER_THAN,
    MDBX_TO_EXACT_KEY_VALUE_LESSER_THAN,
    MDBX_TO_EXACT_KEY_VALUE_LESSER_OR_EQUAL,
    MDBX_TO_EXACT_KEY_VALUE_EQUAL,
    MDBX_TO_EXACT_KEY_VALUE_GREATER_OR_EQUAL,
    MDBX_TO_EXACT_KEY_VALUE_GREATER_THAN,
    MDBX_TO_PAIR_LESSER_THAN,
    MDBX_TO_PAIR_LESSER_OR_EQUAL,
    MDBX_TO_PAIR_EQUAL,
    MDBX_TO_PAIR_GREATER_OR_EQUAL,
    MDBX_TO_PAIR_GREATER_THAN,
    MDBX_SEEK_AND_GET_MULTIPLE
};

See also: mdbx_cursor_get()

Public Functions Documentation

function mdbx_cursor_bind

Bind cursor to specified transaction and DBI-handle.

LIBMDBX_API int mdbx_cursor_bind (
    MDBX_txn * txn,
    MDBX_cursor * cursor,
    MDBX_dbi dbi
)

Using of the mdbx_cursor_bind() is equivalent to calling mdbx_cursor_renew() but with specifying an arbitrary DBI-handle.

A cursor may be associated with a new transaction, and referencing a new or the same table handle as it was created with. This may be done whether the previous transaction is live or dead.

If the transaction is nested, then the cursor should not be used in its parent transaction. Otherwise it is no way to restore state if this nested transaction will be aborted, nor impossible to define the expected behavior.

Note:

In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
cursor A cursor handle returned by mdbx_cursor_create().

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL An invalid parameter was specified.

function mdbx_cursor_close

Closes a cursor handle without returning error code.

LIBMDBX_API void mdbx_cursor_close (
    MDBX_cursor * cursor
)

The cursor handle will be freed and must not be used again after this call, but its transaction may still be live.

This function returns void but panic in case of error. Use mdbx_cursor_close2() if you need to receive an error code instead of an app crash.

See also: mdbx_cursor_close2

Note:

In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters:

cursor A cursor handle returned by mdbx_cursor_open() or mdbx_cursor_create().

function mdbx_cursor_close2

Closes a cursor handle with returning error code.

LIBMDBX_API int mdbx_cursor_close2 (
    MDBX_cursor * cursor
)

The cursor handle will be freed and must not be used again after this call, but its transaction may still be live.

See also: mdbx_cursor_close

Note:

In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters:

cursor A cursor handle returned by mdbx_cursor_open() or mdbx_cursor_create().

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL An invalid parameter was specified.

function mdbx_cursor_compare

Compares the position of the cursors.

LIBMDBX_API int mdbx_cursor_compare (
    const MDBX_cursor * left,
    const MDBX_cursor * right,
    bool ignore_multival
)

This function is intended to compare the positions of two cursors associated with the same transaction and the same table (DBI descriptor). If the cursors are associated with different transactions, or with different tables, or one of them is not initialized, then the result of the comparison is undefined (the behavior may be changed in subsequent versions).

Parameters:

left A left cursor for comparing positions.
right A right cursor for comparing positions.
ignore_multival A boolean option that affects the result only when comparing cursors for tables with multi-values, i.e. with the MDBX_DUPSORT flag. In the case of true, cursor positions are compared only by keys, without taking into account positioning among multi-values. Otherwise, in the case of false, if the key positions match, the multi-value positions are also compared.

Return value:

A signed value in the semantics of the operator <=> (less than zero, zero, or greater than zero) as a result of comparing cursor positions.

function mdbx_cursor_copy

Copy cursor position and state.

LIBMDBX_API int mdbx_cursor_copy (
    const MDBX_cursor * src,
    MDBX_cursor * dest
)

Parameters:

src A source cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().
dest A destination cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().

Returns:

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

function mdbx_cursor_create

Create a cursor handle but not bind it to transaction nor DBI-handle.

LIBMDBX_API  MDBX_cursor * mdbx_cursor_create (
    void * context
)

A cursor cannot be used when its table handle is closed. Nor when its transaction has ended, except with mdbx_cursor_bind() and mdbx_cursor_renew(). Also it can be discarded with mdbx_cursor_close().

A cursor must be closed explicitly always, before or after its transaction ends. It can be reused with mdbx_cursor_bind() or mdbx_cursor_renew() before finally closing it.

Note:

In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters:

context A pointer to application context to be associated with created cursor and could be retrieved by mdbx_cursor_get_userctx() until cursor closed.

Returns:

Created cursor handle or NULL in case out of memory.

function mdbx_cursor_dbi

Return the cursor's table handle.

LIBMDBX_API  MDBX_dbi mdbx_cursor_dbi (
    const MDBX_cursor * cursor
)

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

function mdbx_cursor_distance

Calculates the distance between the cursors at the specified B-tree level.

LIBMDBX_API int mdbx_cursor_distance (
    const MDBX_cursor * first,
    const MDBX_cursor * last,
    intptr_t * distance,
    unsigned deepness
)

The value of the deepness parameter has a fundamental impact on the result since it limits the level of a B-tree, at which the difference between the cursor positions is calculated, where zero corresponds to the root of a B-tree and increases to a leaves. Lower deepness values allows to quickly get a rough result, avoiding reading the pages of a B-tree. Large enough deepness values allows to find out the exact number of elements between the cursors, but this will require reading all the leaf pages between ones. In order for the returned result to match the number of keys and values, the deepness must be at least the height of a B-tree, adding the height of nested B-trees for any kinds of "dupsort" tables. If in doubt, use a deliberately large value such as INT_MAX or just the 42.

Parameters:

first Cursor pointing to the first element or NULL to using the begin of a table. Either the "first" or the "last" can be NULL, but not both at once.
last Cursor pointing to the end of the range or NULL to using the end of a table. Either the "first" or the "last" can be NULL, but not both at once.
distance The address for storing the result calculated distance.
deepness Limits the level of a B-tree, at which the difference between the cursor positions is calculated, where zero corresponds to the root of a B-tree and increases to a leaves.

See also: mdbx_cursor_scroll()

See also: mdbx_cursor_distribute()

Returns:

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

Return value:

MDBX_ENODATA One or both of the given cursor(s) is not positioned to a data.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL An invalid parameter was specified.

function mdbx_cursor_distribute

Distributes cursors for multithreaded range scanning.

LIBMDBX_API int mdbx_cursor_distribute (
    const MDBX_cursor * first,
    const MDBX_cursor * last,
    MDBX_cursor ** array,
    intptr_t count,
    unsigned deepness
)

Places a given set of cursors as evenly as possible for subsequent scanning or parallel processing of data range by several threads. The function can accept cursors bound to different read transactions, provided that they use the same MVCC-snapshot of data.

The value of the deepness parameter has a fundamental effect on the result, since it determines the level of the B-tree at which the cursors distribution are performed, where zero corresponds to the root of the B-tree and increases to a leaves. In order for the performed cursor movement to match the number of keys and values, the deepness must be at least the height of a B-tree, adding the height of nested B-trees for any kinds of "dupsort" tables. If in doubt, use a deliberately large value such as INT_MAX or just the 42.

Parameters:

first Cursor pointing to the first element or NULL to using the begin of a table. Either the first or the last must not be NULL.
last Cursor pointing to the end of the range or NULL to using the end of a table. Either the first or the last must not be NULL.
array The pointer to an array of cursors for distribute over a given range.
count Number of element in the cursors array.
deepness Defines the level of a B-tree, at which the cursors distribution is performed, where zero corresponds to the root of a B-tree and increases to a leaves.

See also: mdbx_cursor_distance()

See also: mdbx_cursor_scroll()

Returns:

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

Return value:

MDBX_ENODATA The first or last cursor(s) is not positioned to a data.
MDBX_RESULT_TRUE The available positions in the specified range were not enough to distribute over all the cursors, some cursors remained unset and mdbx_cursor_eof() will return MDBX_RESULT_TRUE for ones.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL An invalid parameter was specified.

function mdbx_cursor_eof

Determines whether the cursor is pointed to a key-value pair or not, i.e. was not positioned or points to the end of data.

LIBMDBX_API int mdbx_cursor_eof (
    const MDBX_cursor * cursor
)

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

Returns:

A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return value:

MDBX_RESULT_TRUE No more data available or cursor not positioned
MDBX_RESULT_FALSE A data is available
OTHERWISE the error code

function mdbx_cursor_get_userctx

Get the application information associated with the MDBX_cursor .

LIBMDBX_API void * mdbx_cursor_get_userctx (
    const MDBX_cursor * cursor
)

See also: mdbx_cursor_set_userctx()

Parameters:

cursor An cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().

Returns:

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

function mdbx_cursor_on_first

Determines whether the cursor is pointed to the first key-value pair or not.

LIBMDBX_API int mdbx_cursor_on_first (
    const MDBX_cursor * cursor
)

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

Returns:

A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return value:

MDBX_RESULT_TRUE Cursor positioned to the first key-value pair
MDBX_RESULT_FALSE Cursor NOT positioned to the first key-value pair
OTHERWISE the error code

function mdbx_cursor_on_first_dup

Determines whether the cursor is on the first or single multi-value corresponding to the key.

LIBMDBX_API int mdbx_cursor_on_first_dup (
    const MDBX_cursor * cursor
)

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

Returns:

A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return value:

MDBX_RESULT_TRUE The cursor is positioned to the first or single multi-value corresponding to the key.
MDBX_RESULT_FALSE The cursor is NOT positioned to the first or single multi-value corresponding to the key.
OTHERWISE the error code

function mdbx_cursor_on_last

Determines whether the cursor is pointed to the last key-value pair or not.

LIBMDBX_API int mdbx_cursor_on_last (
    const MDBX_cursor * cursor
)

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

Returns:

A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return value:

MDBX_RESULT_TRUE Cursor positioned to the last key-value pair
MDBX_RESULT_FALSE Cursor NOT positioned to the last key-value pair
OTHERWISE the error code

function mdbx_cursor_on_last_dup

Determines whether the cursor is on the last or single multi-value corresponding to the key.

LIBMDBX_API int mdbx_cursor_on_last_dup (
    const MDBX_cursor * cursor
)

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

Returns:

A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return value:

MDBX_RESULT_TRUE The cursor is positioned to the last or single multi-value corresponding to the key.
MDBX_RESULT_FALSE The cursor is NOT positioned to the last or single multi-value corresponding to the key.
OTHERWISE the error code

function mdbx_cursor_open

Create a cursor handle for the specified transaction and DBI handle.

LIBMDBX_API int mdbx_cursor_open (
    MDBX_txn * txn,
    MDBX_dbi dbi,
    MDBX_cursor ** cursor
)

Using of the mdbx_cursor_open() is equivalent to calling mdbx_cursor_create() and then mdbx_cursor_bind() functions.

A cursor cannot be used when its table handle is closed. Nor when its transaction has ended, except with mdbx_cursor_bind() and mdbx_cursor_renew(). Also it can be discarded with mdbx_cursor_close().

A cursor must be closed explicitly always, before or after its transaction ends. It can be reused with mdbx_cursor_bind() or mdbx_cursor_renew() before finally closing it.

Note:

In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
cursor Address where the new MDBX_cursor handle will be stored.

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL An invalid parameter was specified.

function mdbx_cursor_renew

Renew a cursor handle for use within the given transaction.

LIBMDBX_API int mdbx_cursor_renew (
    MDBX_txn * txn,
    MDBX_cursor * cursor
)

A cursor may be associated with a new transaction whether the previous transaction is running or finished.

Using of the mdbx_cursor_renew() is equivalent to calling mdbx_cursor_bind() with the DBI-handle that previously the cursor was used with.

Note:

In contrast to LMDB, the MDBX allow any cursor to be re-used by using mdbx_cursor_renew(), to avoid unnecessary malloc/free overhead until it freed by mdbx_cursor_close().

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
cursor A cursor handle returned by mdbx_cursor_open().

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL An invalid parameter was specified.
MDBX_BAD_DBI The cursor was not bound to a DBI-handle or such a handle became invalid.

function mdbx_cursor_reset

Resets the cursor state.

LIBMDBX_API int mdbx_cursor_reset (
    MDBX_cursor * cursor
)

As a result of the reset, the cursor becomes unpositioned and does not allow relative positioning operations, getting or changing data until cursor is set to a position independent of the current one. This allows to stop further operations without first positioning the cursor.

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

Returns:

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

function mdbx_cursor_scroll

Scrolls the cursor to the specified number of positions at the specified B-tree level.

LIBMDBX_API int mdbx_cursor_scroll (
    MDBX_cursor * cursor,
    intptr_t amount,
    unsigned deepness
)

The value of the deepness parameter has a fundamental effect on the result, since it determines the level of the B-tree at which the cursor movement steps are performed, where zero corresponds to the root of the B-tree and increases to a leaves. In order for the performed cursor movement to match the number of keys and values, the deepness must be at least the height of a B-tree, adding the height of nested B-trees for any kinds of "dupsort" tables. If in doubt, use a deliberately large value such as INT_MAX or just the 42.

Parameters:

cursor The cursor handle to scroll.
amount The number of logical steps by which the cursor will be moved at the specified level of a b-tree. A positive value corresponds to moving forward in the order of keys and values, to the end of a table, and a negative value means moving in the backward order.
deepness Defines the level of a B-tree, at which the cursor movement steps are performed, where zero corresponds to the root of a B-tree and increases to a leaves.

See also: mdbx_cursor_distance()

See also: mdbx_cursor_distribute()

Returns:

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

Return value:

MDBX_ENODATA Given cursor is not positioned to a data.
MDBX_NOTFOUND The end of the data was reached before the cursor moved by the requested number of steps.
MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL An invalid parameter was specified.

function mdbx_cursor_set_userctx

Set application information associated with the cursor.

LIBMDBX_API int mdbx_cursor_set_userctx (
    MDBX_cursor * cursor,
    void * ctx
)

See also: mdbx_cursor_get_userctx()

Parameters:

cursor An cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().
ctx An arbitrary pointer for whatever the application needs.

Returns:

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

function mdbx_cursor_txn

Return the cursor's transaction handle.

LIBMDBX_API  MDBX_txn * mdbx_cursor_txn (
    const MDBX_cursor * cursor
)

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

function mdbx_cursor_unbind

Unbind cursor from a transaction.

LIBMDBX_API int mdbx_cursor_unbind (
    MDBX_cursor * cursor
)

Unbinded cursor is disassociated with any transactions but still holds the original DBI-handle internally. Thus it could be renewed with any running transaction or closed.

If the transaction is nested, then the cursor should not be used in its parent transaction. Otherwise it is no way to restore state if this nested transaction will be aborted, nor impossible to define the expected behavior.

See also: mdbx_cursor_renew()

See also: mdbx_cursor_bind()

See also: mdbx_cursor_close()

See also: mdbx_cursor_reset()

Note:

In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().

Returns:

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

function mdbx_txn_release_all_cursors

Unbind or closes all cursors of a given transaction and of all its parent transactions if ones are.

inline int mdbx_txn_release_all_cursors (
    const MDBX_txn * txn,
    bool unbind
)

Unbinds either closes all cursors associated (opened, renewed or binded) with the given transaction in a bulk with minimal overhead.

See also: mdbx_cursor_unbind()

See also: mdbx_cursor_close()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
unbind If non-zero, unbinds cursors and leaves ones reusable. Otherwise close and dispose cursors.

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_BAD_TXN Given transaction is invalid or has a child/nested transaction transaction.

function mdbx_txn_release_all_cursors_ex

Unbind or closes all cursors of a given transaction and of all its parent transactions if ones are.

LIBMDBX_API int mdbx_txn_release_all_cursors_ex (
    const MDBX_txn * txn,
    bool unbind,
    size_t * count
)

Unbinds either closes all cursors associated (opened, renewed or binded) with the given transaction in a bulk with minimal overhead.

See also: mdbx_cursor_unbind()

See also: mdbx_cursor_close()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
unbind If non-zero, unbinds cursors and leaves ones reusable. Otherwise close and dispose cursors.
count An optional pointer to return the number of cursors processed by the requested operation.

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_BAD_TXN Given transaction is invalid or has a child/nested transaction transaction.