Clarify thread safety docs, rename JANSSON_THREAD_SAFE

This commit is contained in:
Petri Lehtinen 2018-02-08 12:38:14 +02:00
parent 3aee856d7b
commit f44921e176
3 changed files with 26 additions and 14 deletions

View File

@ -58,7 +58,7 @@ the library:
/* Code specific to version 1.3 and above */ /* Code specific to version 1.3 and above */
#endif #endif
``JANSSON_THREAD_SAFE`` ``JANSSON_THREAD_SAFE_REFCOUNT``
If this value is defined all read-only operations and reference counting in 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 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. ``2.11`` or when the compiler does not provide built-in atomic functions.

View File

@ -7,19 +7,31 @@ Portability
Thread safety Thread safety
------------- -------------
Jansson is thread safe and has no mutable global state. The only Jansson as a library is thread safe and has no mutable global state.
exceptions are the hash function seed and memory allocation functions, The only exceptions are the hash function seed and memory allocation
see below. functions, see below.
There's no locking performed inside Jansson's code, so a multithreaded There's no locking performed inside Jansson's code. **Read-only**
program must perform its own locking if JSON values are shared by access to JSON values shared by multiple threads is safe, but
multiple threads. Jansson uses built-in compiler atomic functions to **mutating** a JSON value that's shared by multiple threads is not. A
manage reference counts. If compiler support is not available it may multithreaded program must perform its own locking if JSON values
be very difficult to ensure thread safety of reference counting. shared by multiple threads are mutated.
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) However, **reference count manipulation** (:func:`json_incref()`,
may trigger concurrent access to such values, as containers manage the :func:`json_decref()`) is usually thread-safe, and can be performed on
reference count of their contained values. 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 Hash function seed

View File

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