Class Transaction.

This class manages a single database transaction.

A Transaction accepts a series of queries via enqueue(), and sends them to the server when execute() is called. It ends when commit() or rollback() is called. Its state() indicates its progress.

A Transaction commandeers a database handle when you ask it to execute its queries, and keeps it until commit() or rollback(). If you give it a database handle using setDatabase(), it'll use that instead of asking for one.

The Transaction can also provide subtransactions; these are implemented using SAVEPOINT, RELEASE SAVEPOINT for commit() and ROLLBACK TO SAVEPOINT for restart() and rollback.

When you call subTransaction(), you get a new Transaction which isn't yet active. The subtransaction becomes active when you execute() or commit() it. Becoming active, in this context, means that it enqueues a "savepoint" in its parent, and when that completes, the subtransaction is active. The parent becomes active again when the subtransaction finishes, with commit() ("release savepoint") or rollback() ("rollback so savepoint; release savepoint").

It's possible to use a Transaction for any combination of subtransactions and queries. A Query enqueued in the parent waits until any active subtransaction finishes. Similarly, if you execute() one subtransaction while another is active, the new subtransaction will wait. The parent executes its queries in the order submitted, including the "savepoint" queries that activate a subtransaction.

Transaction::Transaction( EventHandler * ev )

Creates a new Transaction owned by ev (which MUST NOT be 0).

Transaction * Transaction::activeSubTransaction()

Returns a pointer to the currently active subtransaction, or to this transaction is no subtransaction is active.

void Transaction::clearError()

Clears this Transaction's error state (as set with setError()) and places it in Executing state. Used to support savepoints.

void Transaction::commit()

Issues a COMMIT to complete the Transaction (after sending any queries that were already enqueued). The owner is notified when the Transaction completes.

For a failed() Transaction, commit() is equivalent to rollback().

bool Transaction::done() const

Returns true only if this Transaction has either succeeded or failed, and false if it is still awaiting completion.

void Transaction::enqueue( Query * q )

Enqueues the query q within this Transaction, to be sent to the server only after execute() is called. The BEGIN is automatically enqueued before the first query in a Transaction.

void Transaction::enqueue( const EString & text )

This version creates a new Query based on text and enqueues it. Limitations as for the const char * variant above.

void Transaction::enqueue( const char * text )

This version creates a new Query based on text and enqueues it. It does not give the caller a chance to set the query's owner or to bind parameters, so it's most useful for things like DDL.

EString Transaction::error() const

Returns the error message associated with this Transaction. This value is meaningful only if the Transaction has failed().

void Transaction::execute()

Executes the queries enqueued so far.

bool Transaction::failed() const

Returns true only if this Transaction has failed, and false if it succeeded, or is in progress.

Query * Transaction::failedQuery() const

Returns a pointer to the first Query in this transaction that failed. The return value is meaningful only if the transaction has failed, and 0 otherwise.

The return value may also be 0 if the Transaction has been forcibly rolled back by the Postgres class because of a timeout (such as the caller forgetting to ever commit() the Transaction).

This function is useful in composing error messages.

void Transaction::finalizeBegin( Query * q )

Handles whatever needs to happen when a BEGIN or SAVEPOINT finishes; q is the begin query.

void Transaction::finalizeTransaction( Query * q )

This private function handles whatever needs to happen when a transaction finishes; q is the finishing query (typically commit, rollback or release savepoint). There are three cases:

If the commit/rollback works, we restart the parent.

If a subtransaction is rolled back and the rollback fails, we're in real trouble.

If a subtransaction should commit and the release savepoint fails, we roll the subtransaction back and should eventually hand over to the parent transaction.

void Transaction::notify()

Notifies the owner of this Transaction about a significant event.

EventHandler * Transaction::owner() const

Returns a pointer to the owner of this query, as specified to the constructor. Transactions MUST have owners, so this function may not return 0. There is an exception: If the owner is severely buggy, notify() may set the owner to 0 to avoid segfaults.

Transaction * Transaction::parent() const

Returns a pointer to the parent of this Transaction, which will be 0 if this is not a subTransaction().

void Transaction::restart()

Unwinds whatever the subtransaction has done and restarts it.

void Transaction::rollback()

Issues a ROLLBACK to abandon the Transaction, and fails any queries that still haven't been sent to the server. The owner is notified of completion.

void Transaction::setDatabase( Database * db )

Sets this Transaction's Database handle to db.

This function is used by the Database when the BEGIN is processed.

void Transaction::setError( Query * query, const EString & s )

Sets this Transaction's state() to Failed, and records the error message s. The first query that failed is recorded, and is returned by failedQuery() (but query may be 0 if the failure was not specific to a query within the transaction).

void Transaction::setState( State s )

Sets this Transaction's state to s, which must be one of Inactive (if it has not yet been started), Executing, Completed, or Failed.

State Transaction::state() const

Returns the current state of this Transaction.

Transaction * Transaction::subTransaction( EventHandler * ev )

Returns a pointer to a new Transaction that is subordinate to the current one, but which can be independently committed or rolled back.

The returned subtransaction isn't active yet; if you call execute() or commit() on it, it will attempt to take over its parent's Database and do its work. If you don't call execute() on the subtransaction before commit() on the parent, then the subtransaction cannot be used.

The subtransaction will notify ev when it succeeds or fails.

List< Query > * Transaction::submittedQueries()

Removes all queries that can be sent to the server from the front of the queue and returns them. May change activeSubTransaction() as a side effect, if the last query starts a subtransaction.

The returned pointer is never null, but the list may be empty.