ss_m::transaction(SSM)

Shore Programmer's Manual - 18 September 95

NAME

transaction, begin_xct, commit_xct, abort_xct, chain_xct, save_work, rollback_work, tid_to_xct, xct_to_tid, state_xct \- Class ss_m Methods for Transaction Management

SYNOPSIS

#include <sm_vas.h>  // which includes sm.h

static rc_t                 begin_xct(
    long                        timeout = WAIT_SPECIFIED_BY_THREAD);
static rc_t                 begin_xct(
    tid_t&                      tid,
    long                        timeout = WAIT_SPECIFIED_BY_THREAD);
static rc_t                 commit_xct(
    bool                        lazy = false);
static rc_t                 abort_xct()
static rc_t                 chain_xct(
    bool                        lazy = false);  
static rc_t                 save_work(sm_save_point_t& sp);
static rc_t                 rollback_work(
    const sm_save_point_t&      sp);
static xct_state_t          state_xct(const xct_t*);

static xct_t*               tid_to_xct(const tid_t& tid);
static const tid_t&         xct_to_tid(const xct_t*);

DESCRIPTION

The above class ss_m methods all deal with transaction management. See the transaction section of the SSM interface document for more information.

TRANSACTION METHODS

begin_xct(timeout)

begin_xct(tid, timeout)

: The begin_xct method begins a new transaction and associates the current thread with the transaction. The tid returns the transaction ID of the new transaction. The timeout parameter specifies the default amount of time the current thread should block when waiting to obtain a lock on behalf of the transaction. There are three commonly used values for this parameter:
WAIT_FOREVER: This value indicates that the thread should block for up to an unlimited amount of time when waiting for a lock.
WAIT_IMMEDIATE: This value indicates that the thread should not block for any locks.
WAIT_SPECIFIED_BY_THREAD: This value indicates that the amount of time to block should be based on the thread's lock timeout setting. See smthread_t(ssm) for more details.
: Using the default, WAIT_SPECIFIED_BY_THREAD, is usually appropriate as the default for the thread is WAIT_FOREVER.
: Note:Nested transactions are not supported. Therefore, it is an error to call begin_xct while the current thread is already associated with a transaction.

commit_xct(lazy)

: The commit_xct method commits the transaction associated with the current thread. If commit_xct returns successfully, all changes made by the transaction are guaranteed to be persistent, even if the server should crash. All locks held by the transaction are released. When the lazy parameter is set the true, the the transaction commit log record is not actually written to the disk. The transaction's changes (on volumes) are not persistent until the commit log record is written to the disk. Therefore, if a crash should occur immediately after a "lazy" commit, the transaction would be rolled back. However, if any subsequent log record makes it to disk, then the commit record will also be on disk. In addition, all lazy commit log records will be written to the disk every 30 seconds.

abort_xct()

: The abort_xct method rolls back all changes (on volumes) made by the transaction and ends the transaction.

chain_xct(lazy)

: The chain_xct method commits the current transaction and begins another one just as begin_xct would do. In addition, all lock held by the current transaction are transfered to the new transaction. The lazy parameter functions as it does for commit_xct.

save_work()

: The save_work method marks a "save point" and fills the sp parameter with information about it.

rollback_work()

: The rollback_work method uses the log to roll back all changes (on volumes) made since the save point indicated by the sp parameter. No locks are released.

state_xct()

: The state_xct method returns the current state of the transaction pointed to by xct. The transaction pointer for the current threads is available via smthread_t::xct. See smthread_t(ssm) . for more information

TRANSACTION ID METHODS

Transactions are identified by a transaction ID, tid_t. Internal to the SM, there is also a transaction structure, xct_t, holding information about the transaction. So, a pointer to an xct_t can also be used to identify a transaction. Other SM interfaces, including smthread_t(ssm) use xct_t pointers to avoid the transaction from tid_t.

tid_to_xct()

: The tid_to_xct methods converts a transaction ID in to an xct_t pointer.

xct_to_tid()

: The xct_to_tid method converts a xct_t* to a transaction ID.

ERRORS

EXAMPLES

ToDo.

VERSION

This manual page applies to Version 0.9.3 (Beta) of theShore software.

SPONSORSHIP

The Shore project is sponsored by the Advanced Research Project Agency, ARPA order number 018 (formerly 8230), monitored by the U.S. Army Research Laboratory under contract DAAB07-91-C-Q518.