From f44921e1766b4584bb239593ce7e7ea3242c99c3 Mon Sep 17 00:00:00 2001 From: Petri Lehtinen Date: Thu, 8 Feb 2018 12:38:14 +0200 Subject: Clarify thread safety docs, rename JANSSON_THREAD_SAFE --- doc/apiref.rst | 2 +- doc/portability.rst | 38 +++++++++++++++++++++++++------------- 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 */ -- cgit v1.1