[jena-site] 01/01: JENA-957: Revise doc for concurrency - model only

[an...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

andy pushed a commit to branch jena957
in repository https://gitbox.apache.org/repos/asf/jena-site.git

commit 926133311723c19c944b9356260c6f0674ddf913
Author: Andy Seaborne <an...@apache.org>
AuthorDate: Sat Apr 17 18:19:33 2021 +0100

    JENA-957: Revise doc for concurrency - model only
---
 source/documentation/notes/concurrency-howto.md | 63 ++++---------------------
 1 file changed, 10 insertions(+), 53 deletions(-)

diff --git a/source/documentation/notes/concurrency-howto.md b/source/documentation/notes/concurrency-howto.md
index 2d36908..e44f053 100644
--- a/source/documentation/notes/concurrency-howto.md
+++ b/source/documentation/notes/concurrency-howto.md
@@ -2,6 +2,14 @@
 title: Concurrent access to Models
 ---
 
+<i>
+All datasets provide transactions. 
+This is the preferred way to
+handle concurrenct access to data.
+</i>
+<br/>
+<br/>
+
 Applications need to be aware of the concurrency issues in access
 Jena models. API operations are not thread safe by default. Thread
 safety would simple ensure that the model data-structures remained
@@ -29,13 +37,8 @@ There are two main cases:
 -   Multiple applications accessing the same persistent model
     (typically, a database).
 
-Transactions are provided by persistent models: see
-the [TDB documentation](/documentation/tdb/tdb_transactions.html)
-and the [SDB documentation](/documentation/sdb/index.html)
-and for details.
-
 This note describes the support for same-JVM, multi-threaded
-applications.
+applications using in-emmeory Jena Models.
 
 ## Locks
 
@@ -62,51 +65,5 @@ be other application threads reading the model concurrently.
 
 Care must be taken with iterators: unless otherwise stated, all
 iterators must be assumed to be iterating over the data-structures
-in the model or graph implementation itself.  It is not possible to
+in the model or graph implementation itself. It is not possible to
 safely pass these out of critical sections.
-
-## SPARQL Query
-
-SPARQL query results are iterators and no different from other
-iterators in Jena for concurrency purposes. The default query
-engine does not give thread safety and the normal requirements on
-an application to ensure MRSW access in the presence of iterators
-applies. Note that Jena's query mechanism is itself multi-threaded.
-If the application is single threaded, no extra work is necessary.
-If the application is multi-threaded, queries should be executed
-with a read lock.
-
-Outline:
-
-      Model model = ... ;
-      String queryString = " .... " ;
-      Query query = QueryFactory.create(queryString) ;
-      model.enterCriticalSection(Lock.READ) ;
-      try {
-        try(QueryExecution qexec = QueryExecutionFactory.create(query, model)) {
-            ResultSet results = qexec.execSelect() ;
-            for ( ; results.hasNext() ; )
-            {
-                QuerySolution soln = results.nextSolution() ;
-                RDFNode x = soln.get("..var name..") ;
-            }
-        }
-      } finally { model.leaveCriticalSection() ; }
-
-Updates to the model should not be performed inside the read-only
-section. For database-backed models, the application can use a
-transaction. For in-memory models, the application should collect
-the changes together during the query processing then making all
-the changes holding a write lock.
-
-Jena Locks do not provide lock promotion - an application can not
-start a "write" critical section while holding a "read" lock
-because this can lead to deadlock.
-
-## Compatibility
-
-The actually interface is called `Lock` and has implementations
-including `LockMRSW`.
-
-For compatibility with previous versions of Jena, there is a class
-`ModelLock`.