Changes between Version 2 and Version 3 of RFC3


Ignore:
Timestamp:
Oct 17, 2008, 11:48:53 AM (16 years ago)
Author:
cthibert
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • RFC3

    v2 v3  
    1717In 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.
    1818
     19The intent will be to altogether replace the existing functions with the _r functions in a future release, making the thread safe versions the only supported functions.
     20
     21=== Example Prototypes ===
     22Here are examples of what some of the new function prototypes would be.
     23
     24{{{
     25extern void GEOS_DLL initGEOS_r(GEOSConextHandle_t *handle,
     26                                 GEOSMessageHandler notice_function,
     27                                 GEOSMessageHandler error_function);
     28extern void GEOS_DLL finishGEOS_r(GEOSContextHandle_t *handle);
     29
     30
     31extern GEOSGeometry GEOS_DLL *GEOSGeom_createPoint_r(GEOSContextHandle_t *handle,
     32                                                      GEOSCoordSequence* s);
     33extern GEOSGeometry GEOS_DLL *GEOSGeom_createLinearRing_r(GEOSContextHandle_t *handle,
     34                                                      GEOSCoordSequence* s);
     35extern GEOSGeometry GEOS_DLL *GEOSGeom_createLineString_r(GEOSContextHandle_t *handle,
     36                                                      GEOSCoordSequence* s);
     37}}}
     38
     39For comparison, here are the same functions as they exist now.
     40
     41{{{
     42extern void GEOS_DLL initGEOS(GEOSMessageHandler notice_function,
     43        GEOSMessageHandler error_function);
     44extern void GEOS_DLL finishGEOS(void);
     45
     46extern GEOSGeometry GEOS_DLL *GEOSGeom_createPoint(GEOSCoordSequence* s);
     47extern GEOSGeometry GEOS_DLL *GEOSGeom_createLinearRing(GEOSCoordSequence* s);
     48extern GEOSGeometry GEOS_DLL *GEOSGeom_createLineString(GEOSCoordSequence* s);
     49}}}
     50
    1951== Limitations ==
    2052This 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.