Clarify thread safety docs, rename JANSSON_THREAD_SAFE
This commit is contained in:
parent
3aee856d7b
commit
f44921e176
@ -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.
|
||||||
|
@ -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
|
||||||
|
@ -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 */
|
||||||
|
Loading…
Reference in New Issue
Block a user