Changes between Version 5 and Version 6 of rfc16_ogr_reentrancy

Timestamp:

Sep 19, 2007, 6:51:48 PM (17 years ago)

Author:

warmerdam

Comment:

Substantial update, added GetLayerClone().

rfc16_ogr_reentrancy

@@ -1 @@
-
 = RFC 16: OGR Thread Safety = 
 
@@ -25 +24 @@
 
 {{{
-#define OLCReentrant "Reentrant"
-#define ODsReentrant "Reentrant"
-#define ODsThreadSafe "Threadsafe"
+#define OLCReentrant    "Reentrant"
+#define ODsCLayerClones "LayerClones"
+#define ODsCReentrant   "Reentrant"
+#define ODsCThreadSafe  "Threadsafe"
 }}}
 
-Note that layers cannot be threadsafe as long as layer feature reading status is implicit in the layer object.  The default return value for all test values is FALSE, as is normal for the !TestCapability() method, but specific drivers can return TRUE after determining that the driver datasources or layers are in fact reentrant and/or threadsafe.
+Meaning:
+ * OLCReentrant: The layer class is reentrant.  Multiple threads can operate on distinct instances of this class - including different layers on a single datasource.
+ * ODsCReentrant: The datasource class is reentrant.  Multiple threads can operate on distinct instances of this class.
+ * ODsCThreadSafe: The datasource class is thread-safe.  Multiple threads can operate on a single instance of this class. 
+ * ODsCLayerClones: The OGRDataSource::!GetLayerClone() method is supported, and returns a layer instance with distinct state from the default layer returned by !GetLayer().
+
+Note that a single layer instance cannot be threadsafe as long as layer feature reading status is implicit in the layer object.  The default return value for all test values is FALSE, as is normal for the !TestCapability() method, but specific drivers can return TRUE after determining that the driver datasources or layers are in fact reentrant and/or threadsafe.
 
 == OGRSFDriverRegistrar ==
@@ -44 +50 @@
 This class has been modified to include an m_hMutex class data member which is a mutex used to ensure thread safe access to internal datastructures such as the layer list.  Classes derived from OGRDataSource that wish to implement threadsafe operation should use this mutex when exclusivity is required. 
 
+A new method is added to this class:
+
+{{{
+  OGRLayer *GetLayerClone( int i );
+}}}
+
+The default implementation of this method returns NULL.  If the ODsCLayerClones capability is true for the datasource, this method must return duplicates of the requested layer that have distinct feature reading state.  That is they can have their own spatial and attribute filter settings, and the internal feature iterator (for !GetNextFeature() and !ResetReading()) is distinct from other OGRLayer instances referencing the same underlying datasource layer.
+
+The intention of this method in the multi-threaded context is that different threads can have clones of a layer with distinct read state.  A sort of poor-mans threadsafety, even though in fact it is just reentrancy. 
+
+Layers return by !GetLayerClone() should be released with the OGRDataSource::!ReleaseResultSet() method, much like layers returned by ExecuteSQL(). 
+
 == ExecuteSQL() ==
 
-The default OGR implementation of OGRDataSource::ExecuteSQL() internally uses and modifies the layer state (feature iterators and filters) and as such is not appropriate to use on a datasource that is attempting to be threadsafe even though it is understood that individual layers are not threadsafe.  The proposed solution is to offer an OGRTS "dialect" (OGR Thread Safe) which actually opens a duplicate (readonly) datasource so that there will be distinct instances of the layers for the use of the resulset from ExecuteSQL().  This is very expensive in terms of file access and file handles consumed so it is not the default. The default dialect (NULL, "" or "OGR") will continue to use the layers from the current datasource despite the various side effects implied. 
+The default OGR implementation of OGRDataSource::ExecuteSQL() internally uses and modifies the layer state (feature iterators and filters) and as such is not appropriate to use on a datasource that is attempting to be threadsafe even though it is understood that individual layers are not threadsafe.  
+
+The proposed solution is that this code will be modified to use !GetLayerClone() if the datasource supports !GetLayerClone().
+
+== Testing ==
+
+A multi-threaded C++ test harnass will be implemented for read-only stress testing of datasources claiming to support reentrancy and threadsafety. 
+
+No testing of reentrancy and threadsafety will be incorporated into the regression test suite (gdalautotest) as it does not appear to be practical.
+
+Twenty hours is allocated for stress testing the updated drivers.
+
+== Implementation ==
+
+Frank Warmerdam will implement all the core features of this RFC for the  GDAL/OGR 1.5.0 release.  As well the Shapefile, Personal Geodatabase, ODBC and Oracle drivers will implement OLCReentrant, ODsCLayerClones, ODsCReentrant and ODsThreadSafe.  
 
 
-