diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/apiref.rst | 15 | ||||
-rw-r--r-- | doc/portability.rst | 48 |
2 files changed, 40 insertions, 23 deletions
diff --git a/doc/apiref.rst b/doc/apiref.rst index 75c3439..f1a7e16 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_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. + Value Representation ==================== @@ -394,6 +399,16 @@ length-aware functions if you wish to embed null bytes in strings. .. versionadded:: 2.7 +.. function:: json_t *json_sprintf(const char *format, ...) + json_t *json_vsprintf(const char *format, va_list ap) + + .. refcounting:: new + + Construct a JSON string from a format string and varargs, just like + :func:`printf()`. + + .. versionadded:: 2.11 + Number ====== diff --git a/doc/portability.rst b/doc/portability.rst index 272e46a..f8d81cd 100644 --- a/doc/portability.rst +++ b/doc/portability.rst @@ -7,29 +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'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. +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 |