A transaction groups reads and writes across collections and modalities, and commits all of them or none. Writes take the transaction itself, while reads take a view of it, which also chooses whether the read registers its keys so the commit fails if another writer changed them since:
ustore_transaction_t transaction = NULL;
ustore_transaction_init(&(ustore_transaction_init_t){
.transaction = &transaction,
.database = database,
.outcome = &outcome,
});
ustore_blobs_write(&(ustore_blobs_write_t){.database = database, .outcome = &outcome, .transaction = transaction, /* ... */});
ustore_blobs_read(&(ustore_blobs_read_t){
.database = database, .outcome = &outcome,
.view = ustore_transaction_view(transaction, ustore_watch_keys_k), /* ... */});
ustore_transaction_commit(&(ustore_transaction_commit_t){
.database = database,
.outcome = &outcome,
.transaction = transaction,
});
ustore_transaction_free(transaction);ustore_transaction_init begins a new transaction into a NULL handle, left NULL on failure, and resets a transaction of the same database in place, keeping its handle whatever the outcome, so a reset that fails leaves it fit only to be freed or initialized again.
A failed commit keeps the contents of the transaction for a retry. ustore_transaction_rollback withdraws a stage, releasing whatever it claimed, while keeping the reads and writes, so the transaction can stage again or be reset through ustore_transaction_init. ustore_transaction_stage stages the transaction for a two-phase commit and can export its read_stamp, the ustore_stamp_t the transaction reads at and its commit validates against.
A commit can export its commit_stamp, its position in commit order, which every snapshot at or above it sees, and is never below the stage’s read_stamp.
ustore_transaction_tAn opaque handle to an optimistic transaction that groups operations across collections and modalities.typedef struct ustore_transaction_handle_t * ustore_transaction_t;It serves one call at a time, so a call on a transaction that serves an unfinished one finishes with ustore_status_contended_k, and holds its database open until ustore_transaction_free.
ustore_view_tAn opaque handle to what a read sees: the head of the database, a transaction or a snapshot.typedef struct ustore_view_handle_t * ustore_view_t;NULL is the head. Others come from ustore_transaction_view and ustore_snapshot_view, which tag the parent's pointer and allocate nothing, so a view needs no free and dies with its parent, which a cursor reading through it holds until the cursor is freed. A view names its parent, not a moment: after a commit, a transaction's view reads the transaction's next generation. Writes take a transaction instead, so nothing can write through a snapshot.
ustore_stamp_tA position in the order commits apply in, which grows with every commit: where a commit landed, or the newest commit a transaction or a snapshot reads.typedef uint64_t ustore_stamp_t;ustore_watch_tWhether a transaction records the keys a call reads or writes, to refuse its commit when another writer changes them first.enum ustore_watch_tustore_watch_keys_k | 0 | Records the keys, so a concurrent change to any of them fails the commit with a conflict. |
|---|---|---|
ustore_watch_none_k | 1 | Records nothing, so concurrent changes to these keys never fail the commit. |
char const * ustore_watch_name(ustore_watch_t watch);ustore_watch_t ustore_watch_from_name(ustore_bytes_view_t name);ustore_isolation_tHow the transactions of the in-memory engine see each other's writes.enum ustore_isolation_tustore_isolation_strict_serializable_k | 0 | Every transaction appears to run alone at one moment between its start and its commit. |
|---|---|---|
ustore_isolation_snapshot_k | 1 | Every transaction reads the state its start saw and conflicts only over what it writes. |
char const * ustore_isolation_name(ustore_isolation_t isolation);ustore_isolation_t ustore_isolation_from_name(ustore_bytes_view_t name);ustore_transaction_initBegins a transaction, or resets an existing one.void ustore_transaction_init(ustore_transaction_init_t *arguments);transactionustore_transaction_t * | In and out: a NULL handle here begins a new transaction, which the caller frees with ustore_transaction_free, written on success and left NULL on failure; a transaction of database is reset in place onto a fresh snapshot, dropping its reads and writes, and keeps its handle whatever the outcome, so after a failed reset it can only be freed or initialized again. | |
|---|---|---|
databaseustore_database_t | An open database. | |
executorustore_executor_t | Executor that runs the call, where NULL runs it on the calling thread. | |
outcomeustore_outcome_t * | Output for the outcome, final once its status leaves ustore_status_deferred_k. | |
completionustore_completion_t | Whether the call returns final, the default, or once submitted. |
ustore_status_contended_k The transaction reset serves another call, the executor's deferred table is full, or a callback blocks on the executor running it.ustore_status_uninitialized_k The database is NULL.ustore_status_read_only_k The database was opened read-only.ustore_status_unsupported_k The executor computes on a device, or the engine has no transactions, as LevelDB has none.ustore_status_invalid_argument_k The transaction output is NULL, or the transaction reset belongs to another database.ustore_transaction_viewNames a transaction as the view a read sees, without allocating.ustore_view_t ustore_transaction_view(
ustore_transaction_t transaction,
ustore_watch_t watch);transaction | in | A transaction, which the view dies with. |
|---|---|---|
watch | in | Whether reads through the view record their keys for conflicts. |
The view, or NULL, the head, for a NULL transaction.
ustore_transaction_stageStages a transaction as the first phase of a two-phase commit.void ustore_transaction_stage(ustore_transaction_stage_t *arguments);databaseustore_database_t | An open database. | |
|---|---|---|
executorustore_executor_t | Executor that runs the call, where NULL runs it on the calling thread. | |
outcomeustore_outcome_t * | Output for the outcome, final once its status leaves ustore_status_deferred_k. | |
completionustore_completion_t | Whether the call returns final, the default, or once submitted. | |
transactionustore_transaction_t | An initialized transaction. | |
read_stampustore_stamp_t * | Optional output for the stamp the transaction reads at, which its commit validates against; zeroed on failure. |
ustore_status_contended_k The transaction serves another call, the executor's deferred table is full, or a callback blocks on the executor running it.ustore_status_uninitialized_k The database or the transaction is NULL.ustore_status_read_only_k The database was opened read-only.ustore_status_unsupported_k The executor computes on a device, or the engine has no transactions, as LevelDB has none.ustore_status_invalid_argument_k A failed RocksDB stage left the transaction needing a reset.ustore_status_write_conflict_k Another commit changed a key this transaction wrote, or, on the NVMe engine, any key, range or prefix it watched or a collection it touched.ustore_status_read_conflict_k Another commit changed a key this transaction read, on the RAM and RocksDB engines.ustore_status_phantom_conflict_k Another commit changed a window this transaction walked, on the strictly serializable RAM engine.ustore_status_not_found_k A collection the transaction touched was dropped, on RocksDB.ustore_status_malformed_k A value outgrows what its NVMe collection admits.ustore_status_capacity_exhausted_k The strings outgrow one NVMe run file.ustore_transaction_commitCommits a transaction.void ustore_transaction_commit(ustore_transaction_commit_t *arguments);databaseustore_database_t | An open database. | |
|---|---|---|
executorustore_executor_t | Executor that runs the call, where NULL runs it on the calling thread. | |
outcomeustore_outcome_t * | Output for the outcome, final once its status leaves ustore_status_deferred_k. | |
completionustore_completion_t | Whether the call returns final, the default, or once submitted. | |
transactionustore_transaction_t | An initialized transaction, staged first when the caller did not. | |
commit_stampustore_stamp_t * | Optional output for the commit's position in commit order, visible to every snapshot at or above it; zeroed on failure. | |
durabilityustore_durability_t | How durable the writes are once the commit finishes. |
ustore_status_contended_k The transaction serves another call, the executor's deferred table is full, or a callback blocks on the executor running it.ustore_status_uninitialized_k The database or the transaction is NULL.ustore_status_read_only_k The database was opened read-only.ustore_status_unsupported_k The executor computes on a device, or the engine has no transactions, as LevelDB has none.ustore_status_invalid_argument_k The durability is unknown, or a failed RocksDB stage left the transaction needing a reset.ustore_status_write_conflict_k Another commit changed a key this transaction wrote, or, on the NVMe engine, any key, range or prefix it watched or a collection it touched.ustore_status_read_conflict_k Another commit changed a key this transaction read, on the RAM and RocksDB engines.ustore_status_phantom_conflict_k Another commit changed a window this transaction walked, on the strictly serializable RAM engine.ustore_status_not_found_k A collection the transaction touched was dropped, on RocksDB.ustore_status_malformed_k A value outgrows what its NVMe collection admits.ustore_status_capacity_exhausted_k The strings outgrow one NVMe run file.ustore_transaction_rollbackWithdraws a stage, releasing whatever it claimed, while keeping the reads and writes, so the transaction can stage again or be reset through ustore_transaction_init.void ustore_transaction_rollback(
ustore_transaction_rollback_t *arguments);databaseustore_database_t | An open database. | |
|---|---|---|
executorustore_executor_t | Executor that runs the call, where NULL runs it on the calling thread. | |
outcomeustore_outcome_t * | Output for the outcome, final once its status leaves ustore_status_deferred_k. | |
completionustore_completion_t | Whether the call returns final, the default, or once submitted. | |
transactionustore_transaction_t | A transaction, staged or not. |
ustore_status_contended_k The transaction serves another call, the executor's deferred table is full, or a callback blocks on the executor running it.ustore_status_uninitialized_k The database or the transaction is NULL.ustore_status_read_only_k The database was opened read-only.ustore_status_unsupported_k The executor computes on a device, or the engine has no transactions, as LevelDB has none.ustore_status_invalid_argument_k A failed RocksDB stage left the transaction needing a reset.ustore_transaction_freeWaits until every deferred call naming the transaction finishes, then resets it and frees its memory with every view of it once no cursor reads through it.void ustore_transaction_free(ustore_transaction_t transaction);transaction | inout | The transaction to be freed; NULL is safe. |
|---|