Clarify thread safety docs, rename JANSSON_THREAD_SAFE

doc/apiref.rst

@@ -58,7 +58,7 @@ the library:
       /* Code specific to version 1.3 and above */
       #endif
 
-``JANSSON_THREAD_SAFE``
+``JANSSON_THREAD_SAFE_REFCOUNT``
   If this value is defined all read-only operations and reference counting in
   Jansson are thread safe.  This value is not defined for versions older than
   ``2.11`` or when the compiler does not provide built-in atomic functions.

doc/portability.rst

@@ -7,19 +7,31 @@ Portability
 Thread safety
 -------------
 
-Jansson is thread safe and has no mutable global state. The only
-exceptions are the hash function seed and memory allocation functions,
-see below.
+Jansson as a library is thread safe and has no mutable global state.
+The only exceptions are the hash function seed and memory allocation
+functions, see below.
 
-There's no locking performed inside Jansson's code, so a multithreaded
-program must perform its own locking if JSON values are shared by
-multiple threads. Jansson uses built-in compiler atomic functions to
-manage reference counts. If compiler support is not available it may
-be very difficult to ensure thread safety of reference counting.
-It's possible to have a reference to a value that's also stored inside
-a list or object. Modifying the container (adding or removing values)
-may trigger concurrent access to such values, as containers manage the
-reference count of their contained values.
+There's no locking performed inside Jansson's code. **Read-only**
+access to JSON values shared by multiple threads is safe, but
+**mutating** a JSON value that's shared by multiple threads is not. A
+multithreaded program must perform its own locking if JSON values
+shared by multiple threads are mutated.
+
+However, **reference count manipulation** (:func:`json_incref()`,
+:func:`json_decref()`) is usually thread-safe, and can be performed on
+JSON values that are shared among threads. The thread-safety of
+reference counting can be checked with the
+``JANSSON_THREAD_SAFE_REFCOUNT`` preprocessor constant. Thread-safe
+reference count manipulation is achieved using compiler built-in
+atomic functions, which are available in most modern compilers.
+
+If compiler support is not available (``JANSSON_THREAD_SAFE_REFCOUNT``
+is not defined), it may be very difficult to ensure thread safety of
+reference counting. It's possible to have a reference to a value
+that's also stored inside an array or object in another thread.
+Modifying the container (adding or removing values) may trigger
+concurrent access to such values, as containers manage the reference
+count of their contained values.
 
 
 Hash function seed

src/jansson.h

@@ -36,7 +36,7 @@ extern "C" {
 /* If __atomic or __sync builtins are available the library is thread
  * safe for all read-only functions plus reference counting. */
 #if JSON_HAVE_ATOMIC_BUILTINS || JSON_HAVE_SYNC_BUILTINS
-#define JANSSON_THREAD_SAFE
+#define JANSSON_THREAD_SAFE_REFCOUNT 1
 #endif
 
 /* types */