Skip to content
RU

Class mdbx::txn

ClassList > mdbx > txn

Unmanaged database transaction. More...

  • #include <mdbx.h++>

Inherited by the following classes: mdbx::txn_managed

Public Types

Type Name
typedef ::MDBX_cache_result_t cache_result
An alias for MDBX_cache_result_t , i.e. the cached lookup result.
typedef ::MDBX_cache_status_t cache_status
An alias for MDBX_cache_status_t , i.e. the cache lookup status.
typedef ::MDBX_canary canary
An alias for MDBX_canary .
typedef ::MDBX_gc_info_t gc_info
An alias for MDBX_gc_info_t , i.e. the garbage collection info.
typedef ::MDBX_txn_info info
An alias for MDBX_txn_info .
typedef ::MDBX_stat map_stat
An alias for MDBX_stat , i.e. the table statistics.

Public Functions

Type Name
void append (map_handle map, const pair & kv, bool multivalue_order_preserved=true)
Appends a key-value pair, provided that the ascending order is preserved.
bool clear_map (const char * name, bool throw_if_absent=false)
Clear key-value map by name.
bool clear_map (const slice & name, bool throw_if_absent=false)
Clear key-value map by name.
bool clear_map (const ::std::string_view & name, bool throw_if_absent=false)
Clear key-value map by name.
void copy (const wchar_t * destination, bool compactify, bool force_dynamic_size=false)
Copy an MVCC-snapshot of the database to the destination path.
void copy (const ::std::wstring & destination, bool compactify, bool force_dynamic_size=false)
Copy an MVCC-snapshot of the database to the destination path.
map_handle create_map (const ::std::string_view & name, const ::mdbx::key_mode key_mode=::mdbx::key_mode::usual, const ::mdbx::value_mode value_mode=::mdbx::value_mode::single)
Create new or open existing key-value map.
bool drop_map (const char * name, bool throw_if_absent=false)
Drops key-value map using name.
bool drop_map (const slice & name, bool throw_if_absent=false)
Drop key-value map.
bool drop_map (const ::std::string_view & name, bool throw_if_absent=false)
Drop key-value map.
const MDBX_txn * handle () noexcept const
Returns the underlying C handle (read-only).
MDBX_txn * handle () noexcept
Returns the underlying C handle.
void insert (map_handle map, const pair & kv)
Inserts a new key-value pair; fails if the key already exists.
bool is_dirty (const slice & item) const
Checks whether the given slice is on a dirty page.
bool is_readonly () const
Checks whether the transaction is read-only.
bool is_readwrite () const
Checks whether the transaction is read-write.
map_handle open_map (const ::std::string_view & name, const ::mdbx::key_mode key_mode=::mdbx::key_mode::usual, const ::mdbx::value_mode value_mode=::mdbx::value_mode::single) const
Open existing key-value map.
map_handle open_map_accede (const ::std::string_view & name) const
Open existing key-value map.
constexpr operator MDBX_txn * () noexcept
Returns the underlying C handle.
constexpr operator const MDBX_txn * () noexcept const
Returns the underlying C handle (read-only).
txn & operator= (const txn &) noexcept
Copy assignment operator.
txn & operator= (txn_managed &&) = delete
void put (map_handle map, const pair & kv, put_mode mode)
Stores a key-value pair in the given mode.
size_t put_multiple_samelength (map_handle map, const slice & key, const VALUE * values_array, size_t values_count, put_mode mode, bool allow_partial=false)
Stores a bunch of same-length multi-values for the given key.
void put_multiple_samelength (map_handle map, const slice & key, const ::std::vector< VALUE > & vector, put_mode mode)
Stores a bunch of same-length multi-values for the given key.
bool rename_map (const char * old_name, const char * new_name, bool throw_if_absent=false)
Переименовывает таблицу ключ-значение.
bool rename_map (const ::std::string & old_name, const ::std::string & new_name, bool throw_if_absent=false)
Переименовывает таблицу ключ-значение.
bool rename_map (const slice & old_name, const slice & new_name, bool throw_if_absent=false)
Переименовывает таблицу ключ-значение.
void rename_map (map_handle map, const ::std::string_view & new_name)
Переименовывает таблицу ключ-значение.
bool rename_map (const ::std::string_view & old_name, const ::std::string_view & new_name, bool throw_if_absent=false)
Переименовывает таблицу ключ-значение.
size_t size_current () const
Returns current write transaction size (i.e. summary volume of dirty pages) in bytes.
size_t size_max () const
Returns maximal write transaction size (i.e. limit for summary volume of dirty pages) in bytes.
txn_managed start_nested ()
Start nested write transaction.
txn_managed start_nested (bool readonly)
Start nested transaction.
value_result try_insert (map_handle map, const pair & kv)
Tries to insert a new key-value pair without throwing on a duplicate.
constexpr txn () noexcept
Constructs an empty (null) transaction.
txn (const txn &) noexcept
Copy constructor.
txn (txn_managed &&) = delete
size_t unbind_all_cursors () const
Unbind all cursors.
void upsert (map_handle map, const pair & kv)
Inserts or updates the value for the given key.

Protected Attributes

Type Name
MDBX_txn * handle_ = {nullptr}
The underlying C transaction handle, null for an empty instance.

Detailed Description

Like other unmanaged classes, txn allows copying and assignment for handles as a values, but does not manage nor destroys the represented underlying object from the own class destructor.

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

Public Types Documentation

typedef cache_result

An alias for MDBX_cache_result_t , i.e. the cached lookup result.

using mdbx::txn::cache_result = ::MDBX_cache_result_t;

typedef cache_status

An alias for MDBX_cache_status_t , i.e. the cache lookup status.

using mdbx::txn::cache_status = ::MDBX_cache_status_t;

typedef canary

An alias for MDBX_canary .

using mdbx::txn::canary = ::MDBX_canary;

typedef gc_info

An alias for MDBX_gc_info_t , i.e. the garbage collection info.

using mdbx::txn::gc_info = ::MDBX_gc_info_t;

typedef info

An alias for MDBX_txn_info .

using mdbx::txn::info = ::MDBX_txn_info;

typedef map_stat

An alias for MDBX_stat , i.e. the table statistics.

using mdbx::txn::map_stat = ::MDBX_stat;

Public Functions Documentation

function append

Appends a key-value pair, provided that the ascending order is preserved. 

inline void mdbx::txn::append (
    map_handle map,
    const pair & kv,
    bool multivalue_order_preserved=true
)

Parameters:

  • map The table (map) handle.
  • kv The key-value pair to append.
  • multivalue_order_preserved The same rules apply to the nested multi-value tree.

function clear_map [1/3]

Clear key-value map by name. 

bool mdbx::txn::clear_map (
    const char * name,
    bool throw_if_absent=false
)

Parameters:

  • name The table name.
  • throw_if_absent Throw mdbx::not_found if the table does not exist.

Returns:

True if the key-value map existed and was cleared, either false if the key-value map did not exist and there is nothing to clear.

function clear_map [2/3]

Clear key-value map by name. 

bool mdbx::txn::clear_map (
    const slice & name,
    bool throw_if_absent=false
)

Parameters:

  • name The table name.
  • throw_if_absent Throw mdbx::not_found if the table does not exist.

Returns:

True if the key-value map existed and was cleared, either false if the key-value map did not exist and there is nothing to clear.

function clear_map [3/3]

Clear key-value map by name. 

inline bool mdbx::txn::clear_map (
    const ::std::string_view & name,
    bool throw_if_absent=false
)

Parameters:

  • name The table name.
  • throw_if_absent Throw mdbx::not_found if the table does not exist.

Returns:

True if the key-value map existed and was cleared, either false if the key-value map did not exist and there is nothing to clear.

function copy [1/2]

Copy an MVCC-snapshot of the database to the destination path. 

inline void mdbx::txn::copy (
    const wchar_t * destination,
    bool compactify,
    bool force_dynamic_size=false
)

Copies the consistent state as seen by this transaction, see mdbx_txn_copy2pathname().

See also: env::copy()

Parameters:

  • destination The destination argument.
  • compactify The compactify argument.
  • force_dynamic_size The force_dynamic_size argument.

function copy [2/2]

Copy an MVCC-snapshot of the database to the destination path. 

inline void mdbx::txn::copy (
    const ::std::wstring & destination,
    bool compactify,
    bool force_dynamic_size=false
)

Copies the consistent state as seen by this transaction, see mdbx_txn_copy2pathname().

See also: env::copy()

Parameters:

  • destination The destination argument.
  • compactify The compactify argument.
  • force_dynamic_size The force_dynamic_size argument.

function create_map

Create new or open existing key-value map. 

inline map_handle mdbx::txn::create_map (
    const ::std::string_view & name,
    const ::mdbx::key_mode key_mode=::mdbx::key_mode::usual,
    const ::mdbx::value_mode value_mode=::mdbx::value_mode::single
)

Parameters:

Returns:

The table (map) handle.

function drop_map [1/3]

Drops key-value map using name. 

bool mdbx::txn::drop_map (
    const char * name,
    bool throw_if_absent=false
)

Returns:

True if the key-value map existed and was deleted, either false if the key-value map did not exist and there is nothing to delete.

Parameters:

  • name The table name.
  • throw_if_absent The throw_if_absent argument.

function drop_map [2/3]

Drop key-value map. 

bool mdbx::txn::drop_map (
    const slice & name,
    bool throw_if_absent=false
)

Returns:

True if the key-value map existed and was deleted, either false if the key-value map did not exist and there is nothing to delete.

Parameters:

  • name The table name.
  • throw_if_absent The throw_if_absent argument.

function drop_map [3/3]

Drop key-value map. 

inline bool mdbx::txn::drop_map (
    const ::std::string_view & name,
    bool throw_if_absent=false
)

Returns:

True if the key-value map existed and was deleted, either false if the key-value map did not exist and there is nothing to delete.

Parameters:

  • name The table name.
  • throw_if_absent The throw_if_absent argument.

function handle [1/2]

Returns the underlying C handle (read-only). 

inline const MDBX_txn * mdbx::txn::handle () noexcept const

Returns:

The constant pointer to the MDBX_txn object.

function handle [2/2]

Returns the underlying C handle. 

inline MDBX_txn * mdbx::txn::handle () noexcept

Returns:

The mutable pointer to the MDBX_txn object.

function insert

Inserts a new key-value pair; fails if the key already exists. 

inline void mdbx::txn::insert (
    map_handle map,
    const pair & kv
)

Parameters:

  • map The table (map) handle.
  • kv The key-value pair to insert.

function is_dirty

Checks whether the given slice is on a dirty page. 

inline bool mdbx::txn::is_dirty (
    const slice & item
) const

Parameters:

  • item The item argument.

Returns:

true on success, false otherwise.

function is_readonly

Checks whether the transaction is read-only. 

inline bool mdbx::txn::is_readonly () const

Returns:

true if the transaction is read-only.

function is_readwrite

Checks whether the transaction is read-write. 

inline bool mdbx::txn::is_readwrite () const

Returns:

true if the transaction is read-write.

function open_map

Open existing key-value map. 

inline map_handle mdbx::txn::open_map (
    const ::std::string_view & name,
    const ::mdbx::key_mode key_mode=::mdbx::key_mode::usual,
    const ::mdbx::value_mode value_mode=::mdbx::value_mode::single
) const

Parameters:

Returns:

The table (map) handle.

function open_map_accede

Open existing key-value map. 

inline map_handle mdbx::txn::open_map_accede (
    const ::std::string_view & name
) const

Parameters:

  • name The table name.

Returns:

The table (map) handle.

function operator MDBX_txn *

Returns the underlying C handle. 

inline constexpr mdbx::txn::operator MDBX_txn * () noexcept

Returns:

The mutable pointer to the MDBX_txn object.

function operator const MDBX_txn *

Returns the underlying C handle (read-only). 

inline constexpr mdbx::txn::operator const MDBX_txn * () noexcept const

Returns:

The constant pointer to the MDBX_txn object.

function operator=

Copy assignment operator. 

txn & mdbx::txn::operator= (
    const txn &
) noexcept

Returns:

A reference to this instance.

function operator=

txn & mdbx::txn::operator= (
    txn_managed &&
) = delete

function put

Stores a key-value pair in the given mode. 

inline void mdbx::txn::put (
    map_handle map,
    const pair & kv,
    put_mode mode
)

Parameters:

  • map The table (map) handle.
  • kv The key-value pair.
  • mode The put_mode (insert/upsert/update).

function put_multiple_samelength [1/2]

Stores a bunch of same-length multi-values for the given key. 

template<typename VALUE>
inline size_t mdbx::txn::put_multiple_samelength (
    map_handle map,
    const slice & key,
    const VALUE * values_array,
    size_t values_count,
    put_mode mode,
    bool allow_partial=false
)

Parameters:

  • map The table (map) handle.
  • key The key of the multi-value hive.
  • values_array The array of standard-layout values.
  • values_count The number of values in the array.
  • mode The put_mode.
  • allow_partial Allow a partial store when some values are rejected.

Returns:

The number of stored values.

function put_multiple_samelength [2/2]

Stores a bunch of same-length multi-values for the given key. 

template<typename VALUE>
inline void mdbx::txn::put_multiple_samelength (
    map_handle map,
    const slice & key,
    const ::std::vector< VALUE > & vector,
    put_mode mode
)

Parameters:

  • map The table (map) handle.
  • key The key of the multi-value hive.
  • vector The vector of standard-layout values.
  • mode The put_mode.

function rename_map [1/5]

Переименовывает таблицу ключ-значение. 

bool mdbx::txn::rename_map (
    const char * old_name,
    const char * new_name,
    bool throw_if_absent=false
)

Returns:

True если таблица существует и была переименована, либо false в случае отсутствия исходной таблицы.

Parameters:

  • old_name The old_name argument.
  • new_name The new table name.
  • throw_if_absent The throw_if_absent argument.

function rename_map [2/5]

Переименовывает таблицу ключ-значение. 

bool mdbx::txn::rename_map (
    const ::std::string & old_name,
    const ::std::string & new_name,
    bool throw_if_absent=false
)

Returns:

True если таблица существует и была переименована, либо false в случае отсутствия исходной таблицы.

Parameters:

  • old_name The old_name argument.
  • new_name The new table name.
  • throw_if_absent The throw_if_absent argument.

function rename_map [3/5]

Переименовывает таблицу ключ-значение. 

bool mdbx::txn::rename_map (
    const slice & old_name,
    const slice & new_name,
    bool throw_if_absent=false
)

Returns:

True если таблица существует и была переименована, либо false в случае отсутствия исходной таблицы.

Parameters:

  • old_name The old_name argument.
  • new_name The new table name.
  • throw_if_absent The throw_if_absent argument.

function rename_map [4/5]

Переименовывает таблицу ключ-значение. 

inline void mdbx::txn::rename_map (
    map_handle map,
    const ::std::string_view & new_name
)

Parameters:

  • map The table (map) handle.
  • new_name The new table name.

function rename_map [5/5]

Переименовывает таблицу ключ-значение. 

inline bool mdbx::txn::rename_map (
    const ::std::string_view & old_name,
    const ::std::string_view & new_name,
    bool throw_if_absent=false
)

Returns:

True если таблица существует и была переименована, либо false в случае отсутствия исходной таблицы.

Parameters:

  • old_name The old_name argument.
  • new_name The new table name.
  • throw_if_absent The throw_if_absent argument.

function size_current

Returns current write transaction size (i.e. summary volume of dirty pages) in bytes. 

inline size_t mdbx::txn::size_current () const

Returns:

The current transaction size in bytes.

function size_max

Returns maximal write transaction size (i.e. limit for summary volume of dirty pages) in bytes. 

inline size_t mdbx::txn::size_max () const

Returns:

The maximum transaction size in bytes.

function start_nested [1/2]

Start nested write transaction. 

txn_managed mdbx::txn::start_nested ()

Returns:

The managed nested write transaction.

function start_nested [2/2]

Start nested transaction. 

txn_managed mdbx::txn::start_nested (
    bool readonly
)

Parameters:

  • readonly Open a read-only transaction.

Returns:

The managed transaction instance.

function try_insert

Tries to insert a new key-value pair without throwing on a duplicate. 

inline value_result mdbx::txn::try_insert (
    map_handle map,
    const pair & kv
)

Parameters:

  • map The table (map) handle.
  • kv The key-value pair to insert.

Returns:

The value_result with the success flag.

function txn [1/3]

Constructs an empty (null) transaction. 

constexpr mdbx::txn::txn () noexcept

function txn [2/3]

Copy constructor. 

mdbx::txn::txn (
    const txn &
) noexcept

function txn [3/3]

mdbx::txn::txn (
    txn_managed &&
) = delete

function unbind_all_cursors

Unbind all cursors. 

inline size_t mdbx::txn::unbind_all_cursors () const

Unbinds (detaches) every live cursor of the transaction, the underlying C objects stay allocated and owned. A cursor_managed wrapper, however, is not informed about the unbind: it still holds the same C handle, so any subsequent cursor operation (seeking, moving, reading the current entry, etc.) fails with MDBX_EBADSIGN or MDBX_EINVAL at the next C API call. There is no way to detect the detached state from the wrapper side except observing those errors. To keep using a cursor after this call, re-bind it explicitly via cursor::bind() / cursor::renew() (the cursor's unbind() makes the detachment explicit and is the recommended way to invalidate a wrapper you intend to re-use) (issue #146).

Returns:

The number of unbound cursors.

function upsert

Inserts or updates the value for the given key. 

inline void mdbx::txn::upsert (
    map_handle map,
    const pair & kv
)

Parameters:

  • map The table (map) handle.
  • kv The key-value pair to store.

Protected Attributes Documentation

variable handle_

The underlying C transaction handle, null for an empty instance. 

MDBX_txn* mdbx::txn::handle_;

Friends Documentation

friend operator!=

inline bool mdbx::txn::operator!= (
    const txn & a,
    const txn & b
) noexcept

friend operator==

inline bool mdbx::txn::operator== (
    const txn & a,
    const txn & b
) noexcept

The documentation for this class was generated from the following file mdbx.h++