diff options
author | Corey Farrell <git@cfware.com> | 2018-01-22 19:37:36 -0500 |
---|---|---|
committer | Corey Farrell <git@cfware.com> | 2018-02-01 15:54:35 -0500 |
commit | 3aee856d7bc453d488ff9fa5f2ac70e979dd9869 (patch) | |
tree | 36d64a1437a0b240653da473e407b76f89f306fb /doc | |
parent | 37e0ee4d485f8d0821ea357d8bf97d3904145b73 (diff) | |
download | jansson-3aee856d7bc453d488ff9fa5f2ac70e979dd9869.zip jansson-3aee856d7bc453d488ff9fa5f2ac70e979dd9869.tar.gz jansson-3aee856d7bc453d488ff9fa5f2ac70e979dd9869.tar.bz2 |
Docs: Update information on thread safety.
Fixes #387
Diffstat (limited to 'doc')
-rw-r--r-- | doc/apiref.rst | 5 | ||||
-rw-r--r-- | doc/portability.rst | 24 |
2 files changed, 12 insertions, 17 deletions
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 |