diff options
author | Petri Lehtinen <petri@digip.org> | 2018-02-08 12:38:14 +0200 |
---|---|---|
committer | Petri Lehtinen <petri@digip.org> | 2018-02-08 12:38:14 +0200 |
commit | f44921e1766b4584bb239593ce7e7ea3242c99c3 (patch) | |
tree | f40ab7766463ca549abd75cbf2483603181c9590 | |
parent | 3aee856d7bc453d488ff9fa5f2ac70e979dd9869 (diff) | |
download | jansson-f44921e1766b4584bb239593ce7e7ea3242c99c3.zip jansson-f44921e1766b4584bb239593ce7e7ea3242c99c3.tar.gz jansson-f44921e1766b4584bb239593ce7e7ea3242c99c3.tar.bz2 |
Clarify thread safety docs, rename JANSSON_THREAD_SAFEthreadsafety
-rw-r--r-- | doc/apiref.rst | 2 | ||||
-rw-r--r-- | doc/portability.rst | 38 | ||||
-rw-r--r-- | src/jansson.h | 2 |
3 files changed, 27 insertions, 15 deletions
diff --git a/doc/apiref.rst b/doc/apiref.rst index 6c73d30..3ad406d 100644 --- a/doc/apiref.rst +++ b/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. diff --git a/doc/portability.rst b/doc/portability.rst index e1b0c0b..f8d81cd 100644 --- a/doc/portability.rst +++ b/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. - -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. +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. **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 diff --git a/src/jansson.h b/src/jansson.h index 042390c..b17e8f4 100644 --- a/src/jansson.h +++ b/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 */ |