svn commit: r1592253 - /jena/site/trunk/content/documentation/tdb/tdb_transactions.mdtext

[an...@apache.org]

Author: andy
Date: Sat May  3 17:23:42 2014
New Revision: 1592253

URL: http://svn.apache.org/r1592253
Log:
Improve multithreaded use documentation.

Modified:
    jena/site/trunk/content/documentation/tdb/tdb_transactions.mdtext

Modified: jena/site/trunk/content/documentation/tdb/tdb_transactions.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/tdb/tdb_transactions.mdtext?rev=1592253&r1=1592252&r2=1592253&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/tdb/tdb_transactions.mdtext (original)
+++ jena/site/trunk/content/documentation/tdb/tdb_transactions.mdtext Sat May  3 17:23:42 2014
@@ -116,7 +116,6 @@ These are used for SPARQL queries, SPARQ
 actions that modify the data.  Beware that large `model.read` 
 operations consume large amounts of temporary space.
 
-
 The general pattern is:
 
      dataset.begin(ReadWrite.WRITE) ;
@@ -173,10 +172,34 @@ dataset.
 
 ## Multi-threaded use
 
-Each dataset object has one transaction active at a time. 
+Each dataset object has one transaction active at a time per thread. 
+A dataset object can be used by different threads, with independent transactions.
+
 The usual idiom within multi-threaded applications is to have 
 one dataset per thread, and so there is one transaction per thread.
 
+Either:
+
+     // Create a dataset and keep it globally.
+     Dataset dataset = TDBFactory.createDataset(location) ;
+
+Thread 1:
+
+     dataset.begin(ReadWrite.WRITE) ;
+     try {
+       ...
+       dataset.commit() ;
+     } finally { dataset.end() ; }
+
+Thread 2:
+
+     dataset.begin(ReadWrite.READ) ;
+     try {
+       ...
+     } finally { dataset.end() ; }
+
+or create a dataset object on the thread (the case above is preferred):
+
 Thread 1:
 
      Dataset dataset = TDBFactory.createDataset(location) ;
@@ -197,11 +220,6 @@ Thread 2:
 Each thread has a separate `dataset` object; these safely share the 
 same storage but have independent transactions.
 
-While it is possible to share a transaction between multiple
-threads, this is not encouraged.  Applications needing to do so must
-ensure that only one thread starts the transaction, via a `Dataset` object,
-and that all threads are acting "multiple reader OR single writer". 
-
 ## Multi JVM
 
 Multiple applications, running in multiple JVMs, using the same