SQLBOX_TRANS_IMMEDIATE(3)

NAME
sqlbox_trans_deferred, sqlbox_trans_exclusive, sqlbox_trans_immediate - begin a database transaction

LIBRARY
sqlbox

SYNOPSIS
#include <stdint.h>
#include <sqlbox.h>
int
sqlbox_trans_deferred(struct sqlbox *box, size_t srcid, size_t id);
int
sqlbox_trans_exclusive(struct sqlbox *box, size_t srcid, size_t id);
int
sqlbox_trans_immediate(struct sqlbox *box, size_t srcid, size_t id);

DESCRIPTION
The sqlbox_trans_deferred(), sqlbox_trans_exclusive(), and sqlbox_trans_immediate() functions begin a transaction identified as non-zero id on source srcid as returned by sqlbox_open(3). If srcid is zero, the last-opened database is used.

These functions differ in transaction semantics: sqlbox_trans_deferred() opens a shared reader transaction on the first read operation and a single writer on the first write, sqlbox_trans_exclusive() opens a single writer without other readers immediately, and sqlbox_trans_immediate() opens a single writer with possibly other readers immediately.

When in doubt of which kind of transaction to use, sqlbox_trans_immediate() is the simplest and most commonly-used. sqlbox_trans_exclusive() has the highest performance hit (by locking the entire database) and sqlbox_trans_deferred() has complex behaviour.

Transactions may not be nested (of any type) on any single database source. It is an error to sqlbox_close(3) a database without first rolling back or committing open transactions.

  SQLite3 Implementation
Runs sqlite3_exec(3) using the COMMIT or ROLLBACK statements with the type depending on the invocation. Randomly backs off on return of SQLITE_BUSY, SQLITE_LOCKED, or SQLITE_PROTOCOL, and returns failure on anything else other than SQLITE_OK.

RETURN VALUES
Returns zero if communication with box fails. Otherwise, returns non-zero.

If opening the transaction fails (nested, source not found, database errors, id or srcid are zero), subsequent box access will fail. Use sqlbox_ping(3) to check explicitly.

If these functions fail, box is no longer accessible beyond sqlbox_ping(3) and sqlbox_free(3).

SEE ALSO
sqlbox_open(3), sqlbox_ping(3)