From cb34a6251a08f78d749fb62b1554b43a877d39d1 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Thu, 26 Apr 2012 16:45:23 +0200
Subject: Add database::reset()

---
 NEWS             |  4 ++++
 doc/manual.xhtml | 35 +++++++++++++++++++++++++++++++++--
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index 61dd006..da2d3ed 100644
--- a/NEWS
+++ b/NEWS
@@ -58,6 +58,10 @@ Version 1.9.0
     where all the objects were session-enabled, simply add --generate-session
     to your ODB compiler command line.
 
+  * New function, transaction::reset(), allows the reuse of the same
+    transaction instance to complete several database transactions. For more
+    information, refer to Section 3.4, "Transactions" in the ODB manual.
+
 Version 1.8.0
 
   * Support for the Microsoft SQL Server database. The provided connection
diff --git a/doc/manual.xhtml b/doc/manual.xhtml
index 766844f..a969f7f 100644
--- a/doc/manual.xhtml
+++ b/doc/manual.xhtml
@@ -2590,7 +2590,10 @@ namespace odb
     typedef odb::database database_type;
     typedef odb::connection connection_type;
 
-    transaction (transaction_impl*, bool make_current = true)
+    transaction (transaction_impl*, bool make_current = true);
+
+    void
+    reset (transaction_impl*, bool make_current = true);
 
     void
     commit ();
@@ -2622,7 +2625,7 @@ namespace odb
   <p>The <code>commit()</code> function commits a transaction and
      <code>rollback()</code> rolls it back. Unless the transaction
      has been <em>finalized</em>, that is, explicitly committed or rolled
-     back, the destructor of the <code>odb::transaction</code> class will
+     back, the destructor of the <code>transaction</code> class will
      automatically roll it back when the transaction instance goes
      out of scope. If we try to commit or roll back a finalized
      transaction, the <code>odb::transaction_already_finalized</code>
@@ -2676,6 +2679,34 @@ transaction::current (t2);            // Switch to t2.
 t2.commit ();
   </pre>
 
+  <p>The <code>reset()</code> modifier allows us to reuse the same
+     <code>transaction</code> instance to complete several database
+     transactions. Similar to the destructor, <code>reset()</code>
+     will roll the current transaction back if it hasn't been finalized.
+     Here is how we can use this function to commit the current transaction
+     and start a new one every time a certain number of database operations
+     has been performed:</p>
+
+  <pre class="c++">
+transaction t (db.begin ());
+
+for (size_t i (0); i &lt; n; ++i)
+{
+  // Perform a database operation, such as persist an object.
+
+  // Commit the current transaction and start a new one after
+  // every 100 operations.
+  //
+  if (i % 100 == 0)
+  {
+    t.commit ();
+    t.reset (db.begin ());
+  }
+}
+
+t.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
-- 
cgit v1.1