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