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.
Creates a new Transaction owned by ev (which MUST NOT be 0).
Returns a pointer to the currently active subtransaction, or to this transaction is no subtransaction is active.
Clears this Transaction's error state (as set with setError()) and places it in Executing state. Used to support savepoints.
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().
Returns true only if this Transaction has either succeeded or failed, and false if it is still awaiting completion.
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.
This version creates a new Query based on text and enqueues it. Limitations as for the const char * variant above.
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.
Returns the error message associated with this Transaction. This value is meaningful only if the Transaction has failed().
Executes the queries enqueued so far.
Returns true only if this Transaction has failed, and false if it succeeded, or is in progress.
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.
Handles whatever needs to happen when a BEGIN or SAVEPOINT finishes; q is the begin query.
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.
Notifies the owner of this Transaction about a significant event.
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.
Returns a pointer to the parent of this Transaction, which will be 0 if this is not a subTransaction().
Unwinds whatever the subtransaction has done and restarts it.
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.
Sets this Transaction's Database handle to db.
This function is used by the Database when the BEGIN is processed.
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).
Sets this Transaction's state to s, which must be one of Inactive (if it has not yet been started), Executing, Completed, or Failed.
Returns the current state of this Transaction.
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.
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.
This web page based on source code belonging to The Archiveopteryx Developers. All rights reserved.