1*********** 2Portability 3*********** 4 5.. _portability-thread-safety: 6 7Thread safety 8------------- 9 10Jansson is thread safe and has no mutable global state. The only 11exceptions are the hash function seed and memory allocation functions, 12see below. 13 14There's no locking performed inside Jansson's code, so a multithreaded 15program must perform its own locking if JSON values are shared by 16multiple threads. Jansson's reference counting semantics may make this 17a bit harder than it seems, as it's possible to have a reference to a 18value that's also stored inside a list or object. Modifying the 19container (adding or removing values) may trigger concurrent access to 20such values, as containers manage the reference count of their 21contained values. Bugs involving concurrent incrementing or 22decrementing of deference counts may be hard to track. 23 24The encoding functions (:func:`json_dumps()` and friends) track 25reference loops by modifying the internal state of objects and arrays. 26For this reason, encoding functions must not be run on the same JSON 27values in two separate threads at the same time. As already noted 28above, be especially careful if two arrays or objects share their 29contained values with another array or object. 30 31If you want to make sure that two JSON value hierarchies do not 32contain shared values, use :func:`json_deep_copy()` to make copies. 33 34 35Hash function seed 36================== 37 38To prevent an attacker from intentionally causing large JSON objects 39with specially crafted keys to perform very slow, the hash function 40used by Jansson is randomized using a seed value. The seed is 41automatically generated on the first explicit or implicit call to 42:func:`json_object()`, if :func:`json_object_seed()` has not been 43called beforehand. 44 45The seed is generated by using operating system's entropy sources if 46they are available (``/dev/urandom``, ``CryptGenRandom()``). The 47initialization is done in as thread safe manner as possible, by using 48architecture specific lockless operations if provided by the platform 49or the compiler. 50 51If you're using threads, it's recommended to autoseed the hashtable 52explicitly before spawning any threads by calling 53``json_object_seed(0)`` , especially if you're unsure whether the 54initialization is thread safe on your platform. 55 56 57Memory allocation functions 58=========================== 59 60Memory allocation functions should be set at most once, and only on 61program startup. See :ref:`apiref-custom-memory-allocation`. 62 63 64Locale 65------ 66 67Jansson works fine under any locale. 68 69However, if the host program is multithreaded and uses ``setlocale()`` 70to switch the locale in one thread while Jansson is currently encoding 71or decoding JSON data in another thread, the result may be wrong or 72the program may even crash. 73 74Jansson uses locale specific functions for certain string conversions 75in the encoder and decoder, and then converts the locale specific 76values to/from the JSON representation. This fails if the locale 77changes between the string conversion and the locale-to-JSON 78conversion. This can only happen in multithreaded programs that use 79``setlocale()``, because ``setlocale()`` switches the locale for all 80running threads, not only the thread that calls ``setlocale()``. 81 82If your program uses ``setlocale()`` as described above, consider 83using the thread-safe ``uselocale()`` instead. 84