diff options
author | Boris Kolpackov <boris@codesynthesis.com> | 2011-08-24 15:08:42 +0200 |
---|---|---|
committer | Boris Kolpackov <boris@codesynthesis.com> | 2011-08-24 15:08:42 +0200 |
commit | e799a139472a76234ccbdedd5c423ced4c478a86 (patch) | |
tree | 15ec0d20ee2e208b4f62830bfb4697adbb728a74 | |
parent | 3db36c0572cb244cd9f4b03650837cfb1ed31b15 (diff) |
Document transaction multiplexing
-rw-r--r-- | NEWS | 4 | ||||
-rw-r--r-- | doc/manual.xhtml | 78 |
2 files changed, 72 insertions, 10 deletions
@@ -45,6 +45,10 @@ Version 1.6.0 native statements outside of a transaction. For more information, refer to Section 3.5, "Connections" in the ODB manual. + * Support for multiplexing several transaction on the same thread. For + more information, refer to Section 3.4, "Transactions" in the ODB + manual. + Version 1.5.0 * Support for the PostgreSQL database. The provided connection factories diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 225ce91..4c0686e 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -2214,13 +2214,25 @@ namespace odb now on the only way to alter this state is to execute and commit another transaction.</p> - <p>A transaction is started by calling the - <code>database::begin()</code> + <p>A transaction is started by calling either the + <code>database::begin()</code> or <code>connection::begin()</code> function. The returned transaction handle is stored in an instance of the <code>odb::transaction</code> class. You will need to include the <code><odb/transaction.hxx></code> header file to make this class available in your application. - The <code>odb::transaction</code> class has the following + For example:</p> + + <pre class="c++"> +#include <odb/transaction.hxx> + +transaction t (db.begin ()) + +// Perform database operations. + +t.commit (); + </pre> + + <p>The <code>odb::transaction</code> class has the following interface:</p> <pre class="c++"> @@ -2232,6 +2244,8 @@ namespace odb typedef odb::database database_type; typedef odb::connection connection_type; + transaction (transaction_impl*, bool make_current = true) + void commit (); @@ -2244,11 +2258,17 @@ namespace odb connection_type& connection (); + static bool + has_current (); + static transaction& current (); + static void + current (transaction&); + static bool - has_current (); + reset_current (); }; } </pre> @@ -2265,13 +2285,51 @@ namespace odb <p>The <code>database()</code> accessor returns the database this transaction is working on. Similarly, the <code>connection()</code> accessor returns the database connection this transaction is on - (<a href="#3.5">Section 3.5, "Connections"</a>). The - <code>current()</code> static function returns the currently active - transaction for this thread. If there is no active transaction, this - function throws the <code>odb::not_in_transaction</code> exception. - We can check whether there is a transaction in effect in + (<a href="#3.5">Section 3.5, "Connections"</a>).</p> + + <p>The static <code>current()</code> accessor returns the + currently active transaction for this thread. If there is no active + transaction, this function throws the <code>odb::not_in_transaction</code> + exception. We can check whether there is a transaction in effect in this thread using the <code>has_current()</code> static function.</p> + <p>The <code>make_current</code> argument in the <code>transaction</code> + constructor as well as the static <code>current()</code> modifier and + <code>reset_current()</code> function give us additional + control over the nomination of the currently active transaction. + If we pass <code>false</code> as the <code>make_current</code> + argument, then the newly created transaction will not + automatically be made the active transaction for this + thread. Later, we can use the static <code>current()</code> modifier + to set this transaction as the active transaction. + The <code>reset_current()</code> static function clears the + currently active transaction. Together, these mechanisms + allow for more advanced use cases, such as multiplexing + two or more transactions on the same thread. For example:</p> + + <pre class="c++"> +transaction t1 (db1.begin ()); // Active transaction. +transaction t2 (db2.begin (), false); // Not active. + +// Perform database operations on db1. + +transaction::current (t2); // Deactivate t1, activate t2. + +// Perform database operations on db2. + +transaction::current (t1); // Switch back to t1. + +// Perform some more database operations on db1. + +t1.commit (); + +transaction::current (t2); // Switch to t2. + +// Perform some more database operations on db2. + +t2.commit (); + </pre> + <p>Note that in the above discussion of atomicity, consistency, isolation, and durability, all of those guarantees only apply to the object's state in the database as opposed to the object's @@ -5871,7 +5929,7 @@ namespace odb current session for this thread. The <code>reset_current()</code> static function clears the current session. These two functions allow for more advanced use cases, such as multiplexing - between two or more sessions in the same thread.</p> + two or more sessions on the same thread.</p> <p>We normally don't use the object cache interface directly. However, it could be useful in some cases, for example, to find out whether |