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.
COPYRIGHT
Copyright (c) 1994, 1995 Computer Sciences Department, University of Wisconsin -- Madison. All Rights Reserved.SEE ALSO
lock(ssm)
,
smthread_t(ssm)
,
intro(ssm)
,