Distributed Transactions: Two-Phase Commit
[Transactions, Locking and Logging]

Collaboration diagram for Distributed Transactions: Two-Phase Commit:

---

Detailed Description

The storage manager contains support for externally-coordinated transactions that use two-phase-commit with presumed abort. The server must provide the coordination and the coordinator is assumed to have its own stable storage, and it is assumed to recover from failures in a "short time", the precise meaning of which is given below. A prepared transaction, like an active transaction, consumes log space and holds locks. Even if a prepared transaction does not hold locks needed by other transactions, it consumes resources in a way that can interfere with other transactions. If a prepared transaction remains in the system for a long time while other transactions are running, eventually the storage manager needs the log space used (reserved) by the prepared transaction. A coordinator must resolve its prepared transactions before the storage manager effectively runs out of log space for other transactions in the system. The amount of time involved is a function of the size of the log and of the demands of the other transactions in the system.

For the purpose of this discussion, the portion of a global transaction that involves a single Shore Storage Manager transaction is called a thread of the global transaction.

A Shore transaction participates as a thread of a global transaction as follows:

• Start a storage-manager transaction with ss_m::begin_xct.
• Acquire a global transaction identifier from the coordinator.
• Indicate to the storage manager that this transaction is a thread of a global transaction, and associate the global transaction identifier with this thread by calling ss_m::enter_2pc.
• Associate a coordinator with the transaction for recovery purposes, by calling ss_m::set_coordinator.
• Prepare the thread of the transaction and get the storage manager's vote with ss_m::prepare_xct. It is an error to commit a global transaction thread without first preparing it. It is an error to do anything else in a transaction after it is prepared, except to end the transaction or retry the prepare (to get the vote again).
• Convey the vote to the coordinator, and determine the transaction's fate from the coordinator.
• End the thread with ss_m::commit_xct or ss_m::abort_xct.

The storage manager logs the minimal information required to effect a vote of the transaction threads that are storage manager transactions, and to recover such in-doubt transactions after restart. Thus, after a crash/restart, the server may query the storage manager about in-doubt (prepared) transactions with ss_m::query_prepared_xct, which tells the caller the number and global transaction IDs associated with prepared transactions. Using this, the server contacts the coordinator and resumes the voting. The server may find the local transaction IDs and use ss_m::tid_to_xct to attach these transactions and to resolve them.

Commit and abort of read-only transactions are the same, as these transactions have no log entries. Preparing read-only transactions causes them to commit/abort and the vote returned is vote_readonly. Once this vote is communicated to the coordinator and the coordinator records it on stable storage, there is no need to involve this thread in any further processing. For this reason, read-only transactions do not appear as prepared transactions at recovery time.

Functions
static rc_t	ss_m::enter_2pc (const gtid_t &gtid)
	Make the attached transaction a thread of a distributed transaction.
static rc_t	ss_m::set_coordinator (const server_handle_t &h)
	Assign a coordinator handle to this distributed transaction.
static rc_t	ss_m::prepare_xct (sm_stats_info_t *&stats, vote_t &vote)
	Prepare a thread of a distributed transaction.
static rc_t	ss_m::prepare_xct (vote_t &vote)
	Prepare a thread of a distributed transaction.
static rc_t	ss_m::force_vote_readonly ()
	Force the transaction to vote "read-only" in a two-phase commit.
static rc_t	ss_m::recover_2pc (const gtid_t &gtid, bool mayblock, tid_t &local)
	Given a global transaction id, find the local prepared transaction associated with it.
static rc_t	ss_m::query_prepared_xct (int &numtids)
	Return the number of prepared transactions.
static rc_t	ss_m::query_prepared_xct (int numtids, gtid_t l[])
	Return the global transaction IDs of in-doubt transactions.

---

Function Documentation

static rc_t ss_m::enter_2pc

(

const gtid_t &

gtid

)

[static, inherited]

Make the attached transaction a thread of a distributed transaction.

Parameters:

[in]

gtid

Global transaction ID to associate with this transaction. This will be logged when the transaction is prepared.

Note:

This can be called at most once for a given transaction. The transaction must be attached to the calling thread. No other threads may be attached to the transaction.

static rc_t ss_m::set_coordinator

(

const server_handle_t &

h

)

[static, inherited]

Assign a coordinator handle to this distributed transaction.

Parameters:

[in]

h

Handle of the coordinator. Not interpreted by the storage manager.

The storage manager associates this server handle with the transaction so that when the transaction is prepared, this information is written to the log. Upon recovery, if this transaction is still in doubt, the value-added server can query the storage manager for in-doubt transactions, get their server handles, and resolve the transactions. See query_prepared_xct and recover_2pc.

static rc_t ss_m::prepare_xct	(	sm_stats_info_t *&	stats,
		vote_t &	vote
	)			[static, inherited]

Prepare a thread of a distributed transaction.

Parameters:

[in]	stats	Pointer to an allocated statistics-holding structure.
[out]	vote	This thread's vote.

The storage manager will prepare the attached transaction (a thread of a distributed transaction) for commit. If this transaction has performed no logged updates, the vote returned will be vote_readonly. If this transaction can commit, the vote returned will be vote_commit. If an error occurs during the prepare, the vote will be vote_abort.

If the transaction is being instrumented, the statistics-holding structure will be returned to the caller, and the caller is responsible for its deallocation.

static rc_t ss_m::prepare_xct

(

vote_t &

vote

)

[static, inherited]

Prepare a thread of a distributed transaction.

Parameters:

[out]

vote

This thread's vote. See w_base_t::vote_t.

The storage manager will prepare the attached transaction (a thread of a distributed transaction) for commit. If this transaction has performed no logged updates, the vote returned will be vote_readonly. If this transaction can commit, the vote returned will be vote_commit. If an error occurs during the prepare, the vote will be vote_abort.

static rc_t ss_m::force_vote_readonly

(

)

[static, inherited]

Force the transaction to vote "read-only" in a two-phase commit.

This will override the storage manager's determination of whether this thread of a distributed transaction is read-only, which is based on whether the local transaction thread logged anything. This method may be useful if the local transaction rolled back to a savepoint. See w_base_t::vote_t.

static rc_t ss_m::recover_2pc	(	const gtid_t &	gtid,
		bool	mayblock,
		tid_t &	local
	)			[static, inherited]

Given a global transaction id, find the local prepared transaction associated with it.

Parameters:

[in]	gtid	A global transaction ID (an opaque quantity to the storage manager).
[in]	mayblock	Not used.
[out]	local	Return the transaction ID of the prepared SM transaction.

Searches the transaction list for a prepared transaction with the given global transaction id. If found, it returns a reference to the local transaction. The transaction is attached to the running thread before it is returned.

static rc_t ss_m::query_prepared_xct

(

int &

numtids

)

[static, inherited]

Return the number of prepared transactions.

Parameters:

[out]

numtids

The number of in-doubt transactions.

Used by a server at start-up, after recovery, to find out if there are any in-doubt transactions. If so, the server must use the second form of query_prepared_xct to find the global transaction IDs of these in-doubt transactions.

static rc_t ss_m::query_prepared_xct	(	int	numtids,
		gtid_t	l[]
	)			[static, inherited]

Return the global transaction IDs of in-doubt transactions.

Parameters:

[in]	numtids	The number of global transaction ids in the list.
[in]	l	The caller-provided list into which to write the global transaction-ids.

Used by a server at start-up, after recovery, to find out the global transaction IDs of the prepared transactions. The storage manager fills in the first numtids entries of the pre-allocated list. The server may have first called the first form of query_prepared_xct to find out how many such transactions there are after recovery.

Attention:

Read-only transactions do not appear as in-doubt transactions. Because they did not generate any log records, they will not be "discovered" by analysis. The server must determine that any thread of a global transaction that does not appear to be in doubt was a read-only thread or it never prepared and thus has been aborted. Read-only transactions that were prepared would have voted read-only, and if the coordinator recorded that vote on stable storage, it should not be concerned with these transaction threads any further. If the coordinator does not have this information recorded, the transaction thread could have been an aborted non-read-only transaction, so the coordinator must, in this case, presume that the thread aborted and thus make the global transaction abort.

---