control global context (#141)

* add allow_global_context!

* add test for allow_global_context!

* add do block form of allow_global_context

* add GEOSContext and allow_global_context! docs

Author: jw3126

src/LibGEOS.jl

@@ -107,6 +107,20 @@ function geosjl_errorhandler(message::Ptr{UInt8}, userdata)
     end
 end
 
+"""
+
+    GEOSContext
+
+Every LibGEOS object needs to live somewhere in memory. Also many LibGEOS functions
+need scratch memory or caches to do their job.
+
+A `GEOSContext` governs such memory. Almost every function in LibGEOS accepts a `context`
+argument, that allows passing a context explicitly. If no context is passed, a global context is used.
+
+Using the global context is fine, as long as no multi threading is used. 
+If multi threading is used, the global context should be avoided and every operation should only 
+involve objects that live in the context passed to the operation.
+"""
 mutable struct GEOSContext
     ptr::Ptr{Cvoid}  # GEOSContextHandle_t
 
@@ -123,7 +137,7 @@ mutable struct GEOSContext
 end
 
 "Get a copy of a string from GEOS, freeing the GEOS managed memory."
-function string_copy_free(s::Cstring, context::Ptr{Cvoid} = _context.ptr)::String
+function string_copy_free(s::Cstring, context::Ptr{Cvoid} = get_global_context().ptr)::String
     copy = unsafe_string(s)
     GEOSFree_r(context, pointer(s))
     return copy
@@ -191,8 +205,50 @@ mutable struct WKBWriter
     end
 end
 
+const _GLOBAL_CONTEXT = Ref{GEOSContext}()
+const _GLOBAL_CONTEXT_ALLOWED = Ref(false)
+
+function get_global_context()::GEOSContext
+    if _GLOBAL_CONTEXT_ALLOWED[]
+        _GLOBAL_CONTEXT[]
+    else
+        msg = """
+        LibGEOS global context disallowed, a `GEOSContext` must be passed explicitly.
+        Alternatively you can allow the global context by calling:
+        `LibGEOS.allow_global_context!(true)`
+        """
+        error(msg)
+    end
+end
+
+"""
+
+    allow_global_context!(bool::Bool)
+
+Allow (bool=true) or disallow (bool=false) using the global LibGEOS context.
+
+
+    allow_global_context!(f, bool::Bool)
+
+Call `f` with global context usage allowed according to `bool`
+
+Generally this function should only be used as a debugging tool, mostly for multithreaded programs.
+See also [`GEOSContext`](@ref).
+"""
+function allow_global_context!(bool::Bool)
+    _GLOBAL_CONTEXT_ALLOWED[] = bool
+end
+
+function allow_global_context!(f, bool::Bool)
+    old = _GLOBAL_CONTEXT_ALLOWED[]
+    allow_global_context!(bool)
+    f()
+    allow_global_context!(old)
+end
+
 function __init__()
-    global _context = GEOSContext()
+    _GLOBAL_CONTEXT_ALLOWED[] = true
+    _GLOBAL_CONTEXT[] = GEOSContext()
 end
 
 include("geos_functions.jl")