From 3aee856d7bc453d488ff9fa5f2ac70e979dd9869 Mon Sep 17 00:00:00 2001 From: Corey Farrell Date: Mon, 22 Jan 2018 19:37:36 -0500 Subject: Docs: Update information on thread safety. Fixes #387 --- doc/apiref.rst | 5 +++++ doc/portability.rst | 24 +++++++----------------- 2 files changed, 12 insertions(+), 17 deletions(-) (limited to 'doc') diff --git a/doc/apiref.rst b/doc/apiref.rst index a8cf8d6..6c73d30 100644 --- a/doc/apiref.rst +++ b/doc/apiref.rst @@ -58,6 +58,11 @@ the library: /* Code specific to version 1.3 and above */ #endif +``JANSSON_THREAD_SAFE`` + 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. + Value Representation ==================== diff --git a/doc/portability.rst b/doc/portability.rst index 272e46a..e1b0c0b 100644 --- a/doc/portability.rst +++ b/doc/portability.rst @@ -13,23 +13,13 @@ 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's reference counting semantics may make this -a bit harder than it seems, as 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. Bugs involving concurrent incrementing or -decrementing of deference counts may be hard to track. - -The encoding functions (:func:`json_dumps()` and friends) track -reference loops by modifying the internal state of objects and arrays. -For this reason, encoding functions must not be run on the same JSON -values in two separate threads at the same time. As already noted -above, be especially careful if two arrays or objects share their -contained values with another array or object. - -If you want to make sure that two JSON value hierarchies do not -contain shared values, use :func:`json_deep_copy()` to make copies. +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. Hash function seed -- cgit v1.1