DB_TXN(3)

NAME
db_txn - transaction management functions

SYNOPSIS
#include <db.h>
#include <db_lock.h>
int
txn_create(const char *path, mode_t mode, u_int maxtxns, u_int flags);
TXNMGR *
txn_open(const char *path, DBT *logp, LOCK_TABLE_T *lockp,
int (*recover)(DBT *lsn, DBT *log_entry, int isundo));
TXN *
txn_begin(TXNMGR *txnp);
int
txn_commit(TXN *tid);
int
txn_prepare(TXN *tid);
int
txn_abort(TXN *tid);
int
txn_close(TXNMGR *txnp);
int
txn_unlink(const char *path, int force);

DESCRIPTION
specific details of the transaction support.

Db_txn is the library interface that provides transaction semantics. Full transaction support is provided by a collection of modules that provide well defined interfaces to the services required for transaction processing. These services are recovery (see db_log(3)), concurrency control (see db_lock(3)), and the management of shared data (see db_mpool(3)). Transaction semantics can be applied to the access methods described in db(3) through function call parameters.

The model intended for transactional use (and that is used by the access methods) is that write-ahead logging is provided by db_log(3) to record both before- and after-image logging. Locking follows a two-phase protocol and is implemented by db_lock(3).

Any necessary, associated log and lock regions are created as well (see db_log(3) and db_lock(3)).

The maxtxns argument specifies the maximum number of simultaneous transactions that are supported. This bounds the size of backing files and is used to derive limits for the size of the lock region and logfiles. When there are more than maxtxns concurrent transactions, calls to txn_begin may fail.

Default locking and logging protocols are provided only if the backing files exist. If the backing files do not exist, the flags parameter must indicate both a logging mode and locking mode specified by or'ing together at most one flag from each of the TXN_LOCK and TXN_LOG classes as follows:

TXN_LOCK_2PL
    Use two-phase locking.

TXN_LOCK_OPTIMISTIC
    Use optimistic locking (not currently implemented).

TXN_LOG_REDO
    Provide redo-only logging (not currently implemented).

TXN_LOG_UNDO
    Provide undo-only logging (not currently implemented).

TXN_LOG_UNDOREDO
    Provide undo/redo write-ahead logging.

[transaction region txn]

The recover argument specifies a function that is called by txn_abort during transaction abort. This function takes three arguments:

lsn A log sequence number (LSN).

log_entry
    A log record.

isundo
    An undo flag set to 0 if the operation is a redo and set to 1 if the operation an undo.

As discussed in the db_log (3) manual page, the application is responsible for providing any necessary structure to the log record. For example, the application must understand what part of the log record is an operation code, what part is redo information, and what part is undo information.

The txn_begin function creates a new transaction in the designated transaction manager, returning a pointer to a TXN that uniquely identifies it.

The txn_commit function ends the transaction specified by the tid argument. Any locks held by the transaction are released. If logging is enabled, a commit log record is written and flushed to disk.

The txn_abort function causes an abnormal termination of the transaction. If logging is enabled, the log is played backwards and any recovery operations are initiated through the recover function specified to txn_open. After recovery is completed, all locks held by the transaction are released.

The txn_close function detaches a process from the transaction environment specified by the TXNMGR pointer. All mapped regions are unmapped and any allocated resources are freed. Any uncommitted transactions are aborted.

The txn_prepare function initiates the beginning of a two phase commit. In a distributed transaction, the prepare directive should be issued to all participating transaction managers. Each manager must take whatever action is necessary to guarantee that a future call to txn_commit on the specified tid will succeed.

SYSTEM INTEGRATION
This model can be applied to data bases other than the provided access methods. For example, consider an application that provides transaction semantics to data stored in regular files accessed using the read(2) and write(2) system calls. The operations for which transaction protection is desired are bracketed by calls to txn_begin and txn_commit.

Before data are referenced, a call is made to the lock manager, db_lock, for a lock of the appropriate type (e.g. read) on the object being locked. The object might be a page in the file, a byte, a range of bytes, or some key. Before a write is performed, the application makes a call to the log manager, db_log, to record enough information to redo the operation in case of failure after commit and to undo the operation in case of abort. After the log message is written, the write system calls are issued. After all requests are issued, the application calls txn_commit. When txn_commit returns, the caller is guaranteed that all necessary log writes have been written to disk.

At any time, the application may call txn_abort, which will result in the appropriate calls to the recover routine to restore the ``database'' to a consistent pre-transaction state. (The recover routine must be able to either reapply or undo the update depending on the context, for each different type of log record.)

If the application should crash, the recovery process uses the db_log interface to read the log and call the recover routine to restore the database to a consistent state.

The txn_prepare function provides the core functionality to implement distributed transactions, but it does not actually manage the notification of distributed transaction managers. The caller is responsible for issuing txn_prepare calls to all sites participating in the transaction. If all responses are positive, the caller can issue a txn_commit. If any of the responses are negative, the caller should issue a txn_abort. In general, the txn_prepare call requires that the transaction log be flushed to disk.

The structure of the transaction support allows application designers to trade off performance and protection. Since DB manages many structures in shared memory, its information is subject to corruption by applications when the library is linked directly with the application. For this reason, DB is designed to allow compilation into a separate server process that may be accessed via a socket interface. In this way DB's data structures are protected from application code, but communication overhead is increased. When applications are trusted, DB may be compiled directly into the application for increased performance.

ERRORS
The txn_create function may fail and set errno for any of the errors specified for the library functions open(2), write(2), malloc(3), lock_create(3), and log_create(3).

The txn_open function may fail and set errno to any of the errors specified for the library functions open(2), write(2), malloc(3), lock_open(3), and log_open(3).

The txn_begin function may fail and set errno to ENOSPC indicating that the maximum number of concurrent transactions has been reached.

The txn_commit function may fail and set errno to EINVAL indicating that the transaction was aborted.

The txn_close function may fail and set errno to any of the errors specified for the library functions close(2), read(2), write(2), free(3), fsync(2), lock_close(3) or log_close(3).

The txn_unlink function may fail and set errno to any of the errors specified for the library functions unlink(2), lock_unlink(3), and log_unlink(3), or the following:

[EBUSY]
    The transaction region was in use and the force flag was not set.

SEE ALSO
db_btree(3), db_hash(3), db_lock(3), db_log(3), db_mpool(3), db_open(3), db_recno(3)

LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.

BUGS
The maxtxns parameter is a kluge, and should be deleted in favor of dynamically expanding the transaction region.