Classes
class	xct_t
	A transaction. Internal to the storage manager.This class may be used in a limited way for the handling of out-of-log-space conditions. More...

Functions
static rc_t	ss_m::begin_xct (int timeout=timeout_t::WAIT_SPECIFIED_BY_THREAD)
	Begin a transaction. More...

static rc_t	ss_m::begin_xct (sm_stats_t *stats, int timeout=timeout_t::WAIT_SPECIFIED_BY_THREAD)
	Begin an instrumented transaction. More...

static rc_t	ss_m::begin_xct (tid_t &tid, int timeout=timeout_t::WAIT_SPECIFIED_BY_THREAD)
	Begin a transaction and return the transaction id. More...

static rc_t	ss_m::begin_sys_xct (bool single_log_sys_xct=false, sm_stats_t *stats=nullptr, int timeout=timeout_t::WAIT_SPECIFIED_BY_THREAD)
	Being a new system transaction which might be a nested transaction. More...

static rc_t	ss_m::commit_xct (bool lazy=false, lsn_t *plastlsn=nullptr)
	Commit a transaction. More...

static rc_t	ss_m::commit_xct (sm_stats_t &stats, bool lazy=false, lsn_t plastlsn=nullptr)
	Commit an instrumented transaction and get its statistics. More...

static rc_t	ss_m::commit_sys_xct ()
	Commit a system transaction, which doesn't cause log sync. More...

static rc_t	ss_m::chain_xct (sm_stats_t *&stats, bool lazy=false)
	Commit an instrumented transaction and start a new one. More...

static rc_t	ss_m::chain_xct (bool lazy=false)
	Commit a transaction and start a new one, inheriting locks. More...

static rc_t	ss_m::commit_xct_group (xct_t *list[], int listlen)
	Commit a group of transactions. More...

static rc_t	ss_m::abort_xct (sm_stats_t *&stats)
	Abort an instrumented transaction and get its statistics. More...

static rc_t	ss_m::abort_xct ()
	Abort a transaction. More...

static uint32_t	ss_m::num_active_xcts ()
	Return the number of transactions in active state. More...

static void	ss_m::attach_xct (xct_t *x)
	Attach the given transaction to the currently-running smthread_t. More...

static void	ss_m::detach_xct ()
	Detach any attached from the currently-running smthread_t. More...

static xct_t *	ss_m::tid_to_xct (const tid_t &tid)
	Get the transaction structure for a given a transaction id. More...

static tid_t	ss_m::xct_to_tid (const xct_t *x)
	Get the transaction ID for a given a transaction structure. More...

static xct_state_t	ss_m::state_xct (const xct_t *x)
	Get the transaction state for a given transaction (structure). More...

static rc_t	ss_m::gather_xct_stats (sm_stats_t &stats, bool reset=false)
	Get a copy of the statistics from an attached instrumented transaction. More...

Detailed Description

All storage manager operations on data must be done within the scope of a transaction (ss_m::begin_xct, ss_m::commit_xct, ss_m::abort_xct, ss_m::chain_xct).

A very few storage manager operations, such as formatting a volume, are called outside the scope of a transaction and the storage manager begins its own transaction to do the work.

Operations that fail return an error indication and the storage manager assumes that the server will thereafter abort the transaction in which the error occurred, when abort is indicated. Abort is indicated when eUSERABORT or eDEADLOCK is returned and when the erver chooses to abort rather than to work around the problem (whatever it might be, such as eRETRY).

The storage manager does not enforce the aborting of any erroneous transactions except, possibly, those that are in danger of running out of log space. (This is done with the destructor of the prologue used on each call to the storage manager, see next paragraph).

It is always the server's responsibility to abort. When the storage manager encounters a eLOGSPACEWARN condition (the log hasn't enough space at this moment to abort the running transaction, assuming a 1:1 ration of rollback-logging overhead to forward-processing logging overhead), it does one of two things:

passes the error code eLOGSPACEWARN up the call stack back to the server if the storage manager was constructed with no log-space-warning callback argument (see LOG_WARN_CALLBACK_FUNC, ss_m::ss_m).
tries to abort a transaction before passing an error code back up the call stack to the server. Choosing a victim transaction to abort is done by the server in its log-space-warning callback function (passed in on ss_m::ss_m, q.v. Only if that callback function returns a non-null victim transaction and returns eUSERABORT does the storage manager abort that victim before returning eUSERABORT up the call stack. Any other error code returned by the callback function is just returned up the call stack.

Locks

The storage manager automatically acquires the necessary locks when the data are read or written. The locks thus acquired are normally released at the end of a transaction, thus, by default, transactions are two-phase and well-formed (degree 3).

Distributed Transactions

Storage manager transactions may be used as "threads" (to overload this term) of distributed transactions. Coordination of 2-phase commit must be done externally, but the storage manager supports preparing the (local) transaction "thread" for two-phase commit, and it will log the necessary data for recovering in-doubt transactions.

Threads and Transactions

Transactions are not tied to storage manager threads (smthread_t, not to be confused with a local "thread" of a distributed transaction) in any way other than that a transaction must be attached to a thread while any storage manager work is being done on behalf of that transaction. This is how the storage manager knows which transaction is to acquire the locks and latches, etc. But a thread can attach and detach from transactions at will, so work may be performed by different threads each time the storage manager is called on behalf of a given transaction; this allows the server to keep a pool of threads to perform work and allows them to perform work on behalf of any active transaction.

Warning: While there are limited circumstances in which multiple threads can be attached to the same transaction concurrently and perform storage manager operations on behalf of that transaction concurrently, which is a hold-over from the original storage manager, this functionality will be deprecated soon. The reason for this being removed is that it is extremely difficult to handle errors internally when multiple threads are attached to a transaction because partial rollback is impossible in the absence of multiple log streams for a transaction.

Under no circumstances may a thread attach to more than one transaction at a time.

Exotica

The storage manager also provides

partial rollback (ss_m::save_work and ss_m::rollback_work), which undoes actions but does not release locks,
transaction chaining (ss_m::chain_xct), which commits, but retains locks and gives them to a new transaction,
lock release (ss_m::unlock), allowing less-than-3-degree transactions.

To reduce the cost (particularly in logging) of loading databases, the storage manager provides for unlogged loading of stores. See SSMSTORE.

All work performed on behalf of a transaction must occur while that transaction is "attached" to the thread that performs the work. Creating a transaction attaches it to the thread that creates the transaction. The thread may detach from the transaction and attach to another. Multiple threads may attach to a single transaction and do work in certain circumstances. See SSMMULTIXCT

Function Documentation

§ abort_xct() [1/2]

rc_t ss_m::abort_xct ( sm_stats_t *& stats )

static

Abort an instrumented transaction and get its statistics.

Parameters

[out] stats Get a copy of the statistics for this transaction.

Abort the attached transaction and detach it, destroy it.

§ abort_xct() [2/2]

rc_t ss_m::abort_xct ( )

static

Abort a transaction.

Abort the attached transaction and detach it, destroy it.

§ attach_xct()

static void ss_m::attach_xct ( xct_t * x )

inlinestatic

Attach the given transaction to the currently-running smthread_t.

It is assumed that the currently running thread is an smthread_t.

§ begin_sys_xct()

rc_t ss_m::begin_sys_xct	(	bool	single_log_sys_xct = `false`,
		sm_stats_t *	stats = `nullptr`,
		int	timeout = `timeout_t::WAIT_SPECIFIED_BY_THREAD`
	)

static

Being a new system transaction which might be a nested transaction.

System transactions do no logical changes but do physical changes like page split, key push-ups and page deletion. This method starts a new system transaction, if the current thread already has a transaction, inside the current transaction.

Parameters

[in]	single_log_sys_xct	whether this transaction will have at most one xlog entry
[in]	stats	Pointer to an allocated statistics-holding structure.
[in]	timeout	Optional, controls blocking behavior.

§ begin_xct() [1/3]

rc_t ss_m::begin_xct ( int timeout = timeout_t::WAIT_SPECIFIED_BY_THREAD )

static

Begin a transaction.

Parameters

[in] timeout Optional, controls blocking behavior.

Start a new transaction and "attach" it to this thread. No running transaction may be attached to this thread.

Storage manager methods that must block (e.g., to acquire a lock) will use the timeout given. The default timeout is the one associated with this thread.

See also: int

§ begin_xct() [2/3]

rc_t ss_m::begin_xct	(	sm_stats_t *	stats,
		int	timeout = `timeout_t::WAIT_SPECIFIED_BY_THREAD`
	)

static

Begin an instrumented transaction.

Parameters

[in]	stats	Pointer to an allocated statistics-holding structure.
[in]	timeout	Optional, controls blocking behavior.

No running transaction may be already attached to this thread. A new transaction is started and attached to the running thread.

The transaction will be instrumented. This structure is updated by the storage manager whenever a thread detaches from this transaction. The activity recorded during the time the thread is attached to the transcation will be stored in the per-transaction statistics.

Attention: It is the client's responsibility to delete the statistics-holding structure.

Storage manager methods that must block (e.g., to acquire a lock) will use the timeout given. The default timeout is the one associated with this thread.

See also: int

§ begin_xct() [3/3]

rc_t ss_m::begin_xct	(	tid_t &	tid,
		int	timeout = `timeout_t::WAIT_SPECIFIED_BY_THREAD`
	)

static

Begin a transaction and return the transaction id.

Parameters

[out]	tid	Transaction id of new transaction.
[in]	timeout	Optional, controls blocking behavior.

No running transaction may be attached to this thread.

Storage manager methods that must block (e.g., to acquire a lock) will use the timeout given. The default timeout is the one associated with this thread.

See also: int

§ chain_xct() [1/2]

rc_t ss_m::chain_xct	(	sm_stats_t *&	stats,
		bool	lazy = `false`
	)

static

Commit an instrumented transaction and start a new one.

Parameters

[out]	stats	Get a copy of the statistics for the first transaction.
[in]	lazy	Optional, controls flushing of log.

Commit the attached transaction and detach it, destroy it. Start a new transaction and attach it to this thread.

Note: The new transaction inherits the locks of the old transaction.

If lazy is true, the log is not synced. This means that recovery of this transaction might not be possible.

§ chain_xct() [2/2]

rc_t ss_m::chain_xct ( bool lazy = false )

static

Commit a transaction and start a new one, inheriting locks.

Parameters

[in] lazy Optional, controls flushing of log.

Commit the attached transaction and detach it, destroy it. Start a new transaction and attach it to this thread.

Note: The new transaction inherits the locks of the old transaction.

If lazy is true, the log is not synced. This means that recovery of the committed transaction might not be possible.

§ commit_sys_xct()

rc_t ss_m::commit_sys_xct ( )

static

Commit a system transaction, which doesn't cause log sync.

This function is a synonym of commit_xct(lazy=true).

§ commit_xct() [1/2]

rc_t ss_m::commit_xct	(	bool	lazy = `false`,
		lsn_t *	plastlsn = `nullptr`
	)

static

Commit a transaction.

Parameters

[in]	lazy	Optional, controls flushing of log.
[out]	plastlsn	If non-null, this is a pointer to a log sequence number into which the storage manager writes the that of the last log record inserted for this transaction.

Commit the attached transaction and detach it, destroy it. If lazy is true, the log is not synced. This means that recovery of this transaction might not be possible.

§ commit_xct() [2/2]

rc_t ss_m::commit_xct	(	sm_stats_t *&	stats,
		bool	lazy = `false`,
		lsn_t *	plastlsn = `nullptr`
	)

static

Commit an instrumented transaction and get its statistics.

Parameters

[out]	stats	Get a copy of the statistics for this transaction.
[in]	lazy	Optional, controls flushing of log.
[out]	plastlsn	If non-null, this is a pointer to a log sequence number into which the storage manager writes the that of the last log record inserted for this transaction.

Commit the attached transaction and detach it, destroy it. If lazy is true, the log is not synced. This means that recovery of this transaction might not be possible.

§ commit_xct_group()

static rc_t ss_m::commit_xct_group	(	xct_t *	list[],
		int	listlen
	)

static

Commit a group of transactions.

Parameters

[in]	list	List of pointers to transactions to commit.
[in]	listlen	Number of transactions in the list.

Commit each transaction in the list as an all-or-none affair. Any transaction that is attached to the thread will be detached before anything is done.

The purpose of this method is to allow multiple transactions to commit together with a single log record. No voting takes place. The entire list of transaction identifiers must fit in a single log record. If it does not, a descriptive error will be returned and no transaction will be committed. In this case, the server has the option to singly commit each transaction.

If any other error occurs during one of the commits, the error will be returned to the caller and none of the transactions will be committed; they must be aborted thereafter.

This is not intended to be used with transactions that are participating in two-phase commit, but if one of the transactions is participating in two-phase commit, they all must be and they all must be prepared.

Chaining and lazy commit are not offered with this form of commit. If a transaction in the list is instrumented, its statistics resources will be deleted upon successful commit.

Note: By taking a list of transaction pointers, this avoids a the tid_to_xct lookup for each transaction, but the server must regard the transaction pointers as invalid after this method returns. The transactions, once committed, do not exist anymore. If an error is returned, the server has to re-verify the transaction pointers by using ss_m::tid_to_xct from a separate list of transaction ids to determine which transactions are extant.

§ detach_xct()

static void ss_m::detach_xct ( )

inlinestatic

Detach any attached from the currently-running smthread_t.

Sever the connection between the running thread and the transaction. This allow the running thread to attach a different transaction and to perform work in its behalf.

§ gather_xct_stats()

rc_t ss_m::gather_xct_stats	(	sm_stats_t &	stats,
		bool	reset = `false`
	)

static

Get a copy of the statistics from an attached instrumented transaction.

skip

Parameters

[out]	stats	Returns a copy of the statistics for this transaction.
[in]	reset	If true, the statistics for this transaction will be zeroed.

§ num_active_xcts()

uint32_t ss_m::num_active_xcts ( )

static

Return the number of transactions in active state.

While this is thread-safe, the moment a value is returned, it could be out of date. Useful only for debugging.

§ state_xct()

ss_m::xct_state_t ss_m::state_xct ( const xct_t * x )

static

Get the transaction state for a given transaction (structure).

Parameters

[in] x Pointer to transaction structure.

Returns the state of the transaction (active, prepared). It is hard to get the state of an aborted or committed transaction, since their structures no longer exist.

§ tid_to_xct()

xct_t * ss_m::tid_to_xct ( const tid_t & tid )

static

Get the transaction structure for a given a transaction id.

Parameters

[in] tid Transaction ID.

Return a pointer to the storage manager's transaction structure. Can be used with detach_xct and attach_xct.

§ xct_to_tid()

tid_t ss_m::xct_to_tid ( const xct_t * x )

static

Get the transaction ID for a given a transaction structure.

Parameters

[in] x Pointer to transaction structure.

Return the transaction ID for the given transaction.

Classes

Functions

Detailed Description

Locks

Distributed Transactions

Threads and Transactions

Exotica

Function Documentation

§ abort_xct() [1/2]

§ abort_xct() [2/2]

§ attach_xct()

§ begin_sys_xct()

§ begin_xct() [1/3]

§ begin_xct() [2/3]

§ begin_xct() [3/3]

§ chain_xct() [1/2]

§ chain_xct() [2/2]

§ commit_sys_xct()

§ commit_xct() [1/2]

§ commit_xct() [2/2]

§ commit_xct_group()

§ detach_xct()

§ gather_xct_stats()

§ num_active_xcts()

§ state_xct()

§ tid_to_xct()

§ xct_to_tid()