.\" Copyright (c) 1994, 1995 .\" The President and Fellows of Harvard University. All rights reserved. .\" Copyright (c) 1994, 1995 .\" Margo I. Selzer. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)db_txn.3 8.8 (Harvard) 8/1/95 .\" .TH DB_TXN 3 "August 1, 1995" .UC 7 .SH NAME db_txn \- transaction management functions .SH SYNOPSIS .nf .ft B #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, .ti +5 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); .ft R .fi .SH DESCRIPTION .so db.so specific details of the transaction support. .PP .I 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 .IR db_log (3)), concurrency control (see .IR db_lock (3)), and the management of shared data (see .IR db_mpool (3)). Transaction semantics can be applied to the access methods described in .IR db (3) through function call parameters. .PP The model intended for transactional use (and that is used by the access methods) is that write-ahead logging is provided by .IR db_log (3) to record both before- and after-image logging. Locking follows a two-phase protocol and is implemented by .IR db_lock (3). .PP .CR "transaction region" txn Any necessary, associated log and lock regions are created as well (see .IR db_log (3) and .IR db_lock (3)). .PP The .I 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 .I maxtxns concurrent transactions, calls to .I txn_begin may fail. .PP Default locking and logging protocols are provided only if the backing files exist. If the backing files do not exist, the .I flags parameter must indicate both a logging mode and locking mode specified by .IR or 'ing together at most one flag from each of the TXN_LOCK and TXN_LOG classes as follows: .TP 5 TXN_LOCK_2PL Use two-phase locking. .TP 5 TXN_LOCK_OPTIMISTIC Use optimistic locking (not currently implemented). .TP 5 TXN_LOG_REDO Provide redo-only logging (not currently implemented). .TP 5 TXN_LOG_UNDO Provide undo-only logging (not currently implemented). .TP 5 TXN_LOG_UNDOREDO Provide undo/redo write-ahead logging. .PP .RT txn_create .PP .OP "transaction region" txn .PP The .I recover argument specifies a function that is called by .I txn_abort during transaction abort. This function takes three arguments: .TP 5 lsn A log sequence number (LSN). .TP 5 log_entry A log record. .TP 5 isundo An undo flag set to 0 if the operation is a redo and set to 1 if the operation an undo. .PP As discussed in the .I 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. .PP The .I txn_begin function creates a new transaction in the designated transaction manager, returning a pointer to a TXN that uniquely identifies it. .PP The .I txn_commit function ends the transaction specified by the .I tid argument. Any locks held by the transaction are released. If logging is enabled, a commit log record is written and flushed to disk. .PP The .I 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 .I recover function specified to .IR txn_open . After recovery is completed, all locks held by the transaction are released. .PP The .I 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. .PP .UN "transaction region" txn .PP The .I 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 .I txn_commit on the specified .I tid will succeed. .SH "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 .IR read (2) and .IR write (2) system calls. The operations for which transaction protection is desired are bracketed by calls to .I txn_begin and .IR txn_commit . .PP Before data are referenced, a call is made to the lock manager, .IR 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, .IR 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 .IR txn_commit . When .I txn_commit returns, the caller is guaranteed that all necessary log writes have been written to disk. .PP At any time, the application may call .IR txn_abort , which will result in the appropriate calls to the .I 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.) .PP If the application should crash, the recovery process uses the .I db_log interface to read the log and call the .I recover routine to restore the database to a consistent state. .PP The .I 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 .I txn_prepare calls to all sites participating in the transaction. If all responses are positive, the caller can issue a .IR txn_commit . If any of the responses are negative, the caller should issue a .IR txn_abort . In general, the .I txn_prepare call requires that the transaction log be flushed to disk. .PP 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. .SH ERRORS The .I txn_create function may fail and set .I errno for any of the errors specified for the library functions .IR open (2), .IR write (2), .IR malloc (3), .IR lock_create (3), and .IR log_create (3). .PP The .I txn_open function may fail and set .I errno to any of the errors specified for the library functions .IR open (2), .IR write (2), .IR malloc (3), .IR lock_open (3), and .IR log_open (3). .PP The .I txn_begin function may fail and set .I errno to ENOSPC indicating that the maximum number of concurrent transactions has been reached. .PP The .I txn_commit function may fail and set .I errno to EINVAL indicating that the transaction was aborted. .PP The .I txn_close function may fail and set .I errno to any of the errors specified for the library functions .IR close (2), .IR read (2), .IR write (2), .IR free (3), .IR fsync (2), .IR lock_close (3) or .IR log_close (3). .PP The .I txn_unlink function may fail and set .I errno to any of the errors specified for the library functions .IR unlink (2), .IR lock_unlink (3), and .IR log_unlink (3), or the following: .TP 5 [EBUSY] The transaction region was in use and the force flag was not set. .SH "SEE ALSO" .IR db_btree (3), .IR db_hash (3), .IR db_lock (3), .IR db_log (3), .IR db_mpool (3), .IR db_open (3), .IR db_recno (3) .sp .IR "LIBTP: Portable, Modular Transactions for UNIX" , Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. .SH BUGS The .I maxtxns parameter is a kluge, and should be deleted in favor of dynamically expanding the transaction region.