NAME
sqlbox_trans_deferred,
sqlbox_trans_exclusive,
sqlbox_trans_immediate —
begin a database transaction
LIBRARY
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).