Transactions

Data Structures

	Name
struct	hse_kvdb_txn Opaque structure, a pointer to which is a handle to a transaction within a KVDB.

Types

	Name
enum	hse_kvdb_txn_state { HSE_KVDB_TXN_INVALID = 0, HSE_KVDB_TXN_ACTIVE = 1, HSE_KVDB_TXN_COMMITTED = 2, HSE_KVDB_TXN_ABORTED = 3} Transaction state.

Functions

	Name
hse_err_t	hse_kvdb_txn_abort(struct hse_kvdb * kvdb, struct hse_kvdb_txn * txn) Abort/rollback transaction.
struct hse_kvdb_txn *	hse_kvdb_txn_alloc(struct hse_kvdb * kvdb) Allocate transaction object.
hse_err_t	hse_kvdb_txn_begin(struct hse_kvdb * kvdb, struct hse_kvdb_txn * txn) Initiate transaction.
hse_err_t	hse_kvdb_txn_commit(struct hse_kvdb * kvdb, struct hse_kvdb_txn * txn) Commit all the mutations of the referenced transaction.
void	hse_kvdb_txn_free(struct hse_kvdb * kvdb, struct hse_kvdb_txn * txn) Free transaction object.
enum hse_kvdb_txn_state	hse_kvdb_txn_state_get(struct hse_kvdb * kvdb, struct hse_kvdb_txn * txn) Retrieve the state of the referenced transaction.

Detailed Description

The HSE KVDB provides transactions with operations spanning KVSs within a single KVDB. These transactions have snapshot isolation (a specific form of MVCC) with the normal semantics (see "Concurrency Control and Recovery in Database Systems" by PA Bernstein).

One unusual aspect of the API as it relates to transactions is that the data object that is used to hold client-level transaction state is allocated separately from the transaction being initiated. As a result, the same object handle should be reused again and again.

In addition, there is very limited coupling between threading and transactions. A single thread may have many transactions in flight simultaneously. Also operations within a transaction can be performed by multiple threads. The latter mode of operation must currently restrict calls so that only one thread is actively performing an operation in the context of a particular transaction at any particular time.

The general lifecycle of a transaction is as follows:

                  +----------+
                  | INVALID  |
                  +----------+
                        |
                        v
                  +----------+
+---------------->|  ACTIVE  |<----------------+
|                 +----------+                 |
|  +-----------+    |      |     +----------+  |
+--| COMMITTED |<---+      +---->| ABORTED  |--+
   +-----------+                 +----------+

When a transaction is initially allocated, it starts in the INVALID state. When hse_kvdb_txn_begin() is called with transaction in the INVALID, COMMITTED, or ABORTED states, it moves to the ACTIVE state. It is an error to call the hse_kvdb_txn_begin() function on a transaction in the ACTIVE state. For a transaction in the ACTIVE state, only the functions hse_kvdb_txn_commit(), hse_kvdb_txn_abort(), or hse_kvdb_txn_free() may be called (with the last doing an abort prior to the free).

When a transaction becomes ACTIVE, it establishes an ephemeral snapshot view of the state of the KVDB. Any data mutations outside of the transaction's context after that point are not visible to the transaction. Similarly, any mutations performed within the context of the transaction are not visible outside of the transaction unless and until it is committed. All such mutations become visible atomically when the transaction commits.

Within a transaction whenever a write operation e.g., put, delete, etc., encounters a write conflict, that operation returns an error code of ECANCELED. The caller is then expected to re-try the operation in a new transaction, see Errors.

Types Documentation

enum hse_kvdb_txn_state

Enumerator	Value	Description
HSE_KVDB_TXN_INVALID	0	invalid state
HSE_KVDB_TXN_ACTIVE	1	active state
HSE_KVDB_TXN_COMMITTED	2	committed state
HSE_KVDB_TXN_ABORTED	3	aborted state

Transaction state.

Functions Documentation

function hse_kvdb_txn_abort

hse_err_t hse_kvdb_txn_abort(
    struct hse_kvdb * kvdb,
    struct hse_kvdb_txn * txn
)

Abort/rollback transaction.

Parameters:

kvdb KVDB handle from hse_kvdb_open().
txn KVDB transaction handle from hse_kvdb_txn_alloc().

Return: Error status.

Note: This function is thread safe with different transactions.

Warning: The call fails if the referenced transaction is not in the ACTIVE state.

Remark:

kvdb must not be NULL.
txn must not be NULL.

function hse_kvdb_txn_alloc

struct hse_kvdb_txn * hse_kvdb_txn_alloc(
    struct hse_kvdb * kvdb
)

Allocate transaction object.

Parameters:

kvdb KVDB handle from hse_kvdb_open().

Return: The allocated transaction structure.

Note: This function is thread safe.

Remark: kvdb must not be NULL.

This object can and should be re-used many times to avoid the overhead of allocation.

function hse_kvdb_txn_begin

hse_err_t hse_kvdb_txn_begin(
    struct hse_kvdb * kvdb,
    struct hse_kvdb_txn * txn
)

Initiate transaction.

Parameters:

kvdb KVDB handle from hse_kvdb_open().
txn KVDB transaction handle from hse_kvdb_txn_alloc().

Return: Error status.

Note: This function is thread safe with different transactions.

Warning: The call fails if the transaction handle refers to an ACTIVE transaction.

Remark:

kvdb must not be NULL.
txn must not be NULL.

function hse_kvdb_txn_commit

hse_err_t hse_kvdb_txn_commit(
    struct hse_kvdb * kvdb,
    struct hse_kvdb_txn * txn
)

Commit all the mutations of the referenced transaction.

Parameters:

kvdb KVDB handle from hse_kvdb_open().
txn KVDB transaction handle from hse_kvdb_txn_alloc().

Return: Error status

Note: This function is thread safe with different transactions.

Warning: The call fails if the referenced transaction is not in the ACTIVE state.

Remark:

kvdb must not be NULL.
txn must not be NULL.

function hse_kvdb_txn_free

void hse_kvdb_txn_free(
    struct hse_kvdb * kvdb,
    struct hse_kvdb_txn * txn
)

Free transaction object.

Parameters:

kvdb KVDB handle from hse_kvdb_open().
txn KVDB transaction handle.

Note:

If the transaction handle refers to an ACTIVE transaction, the transaction is aborted prior to being freed.
This function is thread safe with different transactions.

Warning: After invoking this function, calling any other transaction functions with this handle will result in undefined behavior.

Remark:

kvdb must not be NULL.
txn must not be NULL.

function hse_kvdb_txn_state_get

enum hse_kvdb_txn_state hse_kvdb_txn_state_get(
    struct hse_kvdb * kvdb,
    struct hse_kvdb_txn * txn
)

Retrieve the state of the referenced transaction.

Parameters:

kvdb KVDB handle from hse_kvdb_open().
txn KVDB transaction handle from hse_kvdb_txn_alloc().

Return: Transaction's state.

Remark:

kvdb must not be NULL.
txn must not be NULL.

This function is thread safe with different transactions.

Updated on 17 November 2022 at 15:10:57 CST