= RFC 3: Thread Safe CAPI = == Summary == The current CAPI in GEOS is not thread safe. The error handling and initialization/finalization process specifically can cause problems. == Definitions == (As defined by Frank Warmerdam in http://trac.osgeo.org/gdal/wiki/rfc16_ogr_reentrancy) '''Reentrant:''' A reentrant function can be called simultaneously by multiple threads provided that each invocation of the function references unique data. '''Thread-safe:''' A thread-safe function can be called simultaneously by multiple threads when each invocation references shared data. All access to the shared data is serialized. == Objective == Allow the GEOS CAPI to be thread safe. == Implementation == In order to implement the thread safe API, the current API will be copied and all static variables will be placed into a 'handle.' This handle will be initialized on the initGeos call. Once initialized it will be passed to all subsequent GEOS functions, allowing each thread to have it's own copy of the data. This will not affect the current API as it will be provided in addition to the old API. In order to prevent maintenance issues the OLD API will be changed to call the NEW API with a global handle. The handle (GEOSContextHandle_t) will be an opaque type to allow exentensions without recompilation being required. Function names in the new API will be updated with an _r, as is the familiar C standard for reentrant/thread safe versions. Current GEOS functions that do not make reference to the context handle will not be changed. == Limitations == This change will focus on making a thread safe version of the API. Other extensions to the context handle have been suggested, e.g. Access to other geometry factories, overriding memory allocators. These extensions are beyond the current scope of this design, but this design will be implemented to allow such extensions in the future. == Testing == An example test executable will be provided that shows the current problem. It is copied from the existing CAPI test tool. Once the thread safe API is created the test tool will be updated to the new interface which will address the former problems.