From e799a139472a76234ccbdedd5c423ced4c478a86 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Wed, 24 Aug 2011 15:08:42 +0200 Subject: Document transaction multiplexing --- NEWS | 4 +++ doc/manual.xhtml | 78 ++++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 72 insertions(+), 10 deletions(-) diff --git a/NEWS b/NEWS index e4d3370..82a89fb 100644 --- a/NEWS +++ b/NEWS @@ -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.

-

A transaction is started by calling the - database::begin() +

A transaction is started by calling either the + database::begin() or connection::begin() function. The returned transaction handle is stored in an instance of the odb::transaction class. You will need to include the <odb/transaction.hxx> header file to make this class available in your application. - The odb::transaction class has the following + For example:

+ + 
+#include <odb/transaction.hxx>
+
+transaction t (db.begin ())
+
+// Perform database operations.
+
+t.commit ();
+
+ +

The odb::transaction class has the following interface:

@@ -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 ();
   };
 }
@@ -2265,13 +2285,51 @@ namespace odb

The database() accessor returns the database this transaction is working on. Similarly, the connection() accessor returns the database connection this transaction is on - (Section 3.5, "Connections"). The - current() static function returns the currently active - transaction for this thread. If there is no active transaction, this - function throws the odb::not_in_transaction exception. - We can check whether there is a transaction in effect in + (Section 3.5, "Connections").

+ +

The static current() accessor returns the + currently active transaction for this thread. If there is no active + transaction, this function throws the odb::not_in_transaction + exception. We can check whether there is a transaction in effect in this thread using the has_current() static function.

+

The make_current argument in the transaction + constructor as well as the static current() modifier and + reset_current() function give us additional + control over the nomination of the currently active transaction. + If we pass false as the make_current + argument, then the newly created transaction will not + automatically be made the active transaction for this + thread. Later, we can use the static current() modifier + to set this transaction as the active transaction. + The reset_current() 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:

+ + 
+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 ();
+
+

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 reset_current() 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.

+ two or more sessions on the same thread.

We normally don't use the object cache interface directly. However, it could be useful in some cases, for example, to find out whether -- cgit v1.1