4139N/A.. _portability-thread-safety:
4139N/AJansson is thread safe and has no mutable global state. The only
4139N/Aexceptions are the hash function seed and memory allocation functions,
4139N/AThere's no locking performed inside Jansson's code, so a multithreaded
4139N/Aprogram must perform its own locking if JSON values are shared by
4139N/Amultiple threads. Jansson's reference counting semantics may make this
4139N/Aa bit harder than it seems, as it's possible to have a reference to a
4139N/Avalue that's also stored inside a list or object. Modifying the
4139N/Acontainer (adding or removing values) may trigger concurrent access to
4139N/Asuch values, as containers manage the reference count of their
4139N/Acontained values. Bugs involving concurrent incrementing or
4139N/Adecrementing of deference counts may be hard to track.
4139N/AThe encoding functions (:func:`json_dumps()` and friends) track
4139N/Areference loops by modifying the internal state of objects and arrays.
4139N/AFor this reason, encoding functions must not be run on the same JSON
4139N/Avalues in two separate threads at the same time. As already noted
4139N/Aabove, be especially careful if two arrays or objects share their
4139N/Acontained values with another array or object.
4139N/AIf you want to make sure that two JSON value hierarchies do not
4139N/Acontain shared values, use :func:`json_deep_copy()` to make copies.
4139N/ATo prevent an attacker from intentionally causing large JSON objects
4139N/Awith specially crafted keys to perform very slow, the hash function
4139N/Aused by Jansson is randomized using a seed value. The seed is
4139N/Aautomatically generated on the first explicit or implicit call to
4139N/A:func:`json_object()`, if :func:`json_object_seed()` has not been
4139N/AThe seed is generated by using operating system's entropy sources if
4139N/Ainitialization is done in as thread safe manner as possible, by using
4139N/Aarchitecture specific lockless operations if provided by the platform
4139N/AIf you're using threads, it's recommended to autoseed the hashtable
4139N/Aexplicitly before spawning any threads by calling
4139N/A``json_object_seed(0)`` , especially if you're unsure whether the
4139N/Ainitialization is thread safe on your platform.
4139N/AMemory allocation functions should be set at most once, and only on
4139N/Aprogram startup. See :ref:`apiref-custom-memory-allocation`.
4139N/AJansson works fine under any locale.
4139N/AHowever, if the host program is multithreaded and uses ``setlocale()``
4139N/Ato switch the locale in one thread while Jansson is currently encoding
4139N/Aor decoding JSON data in another thread, the result may be wrong or
4139N/AJansson uses locale specific functions for certain string conversions
4139N/Ain the encoder and decoder, and then converts the locale specific
4139N/Avalues
to/from the JSON representation. This fails if the locale
4139N/Achanges between the string conversion and the locale-to-JSON
4139N/Aconversion. This can only happen in multithreaded programs that use
4139N/A``setlocale()``, because ``setlocale()`` switches the locale for all
4139N/Arunning threads, not only the thread that calls ``setlocale()``.
4139N/AIf your program uses ``setlocale()`` as described above, consider
4139N/Ausing the thread-safe ``uselocale()`` instead.