doc/portability.rst

   1 ***********
   2 Portability
   3 ***********
   4
   5 Thread safety
   6 -------------
   7
   8 Jansson is thread safe and has no mutable global state. The only
   9 exception are the memory allocation functions, that should be set at
  10 most once, and only on program startup. See
  11 :ref:`apiref-custom-memory-allocation`.
  12
  13 There's no locking performed inside Jansson's code, so a multithreaded
  14 program must perform its own locking if JSON values are shared by
  15 multiple threads. Jansson's reference counting semantics may make this
  16 a bit harder than it seems, as it's possible to have a reference to a
  17 value that's also stored inside a list or object. Modifying the
  18 container (adding or removing values) may trigger concurrent access to
  19 such values, as containers manage the reference count of their
  20 contained values. Bugs involving concurrent incrementing or
  21 decrementing of deference counts may be hard to track.
  22
  23 Locale
  24 ------
  25
  26 Jansson works fine under any locale.
  27
  28 However, if the host program is multithreaded and uses ``setlocale()``
  29 to switch the locale in one thread while Jansson is currently encoding
  30 or decoding JSON data in another thread, the result may be wrong or
  31 the program may even crash.
  32
  33 Jansson uses locale specific functions for certain string conversions
  34 in the encoder and decoder, and then converts the locale specific
  35 values to/from the JSON representation. This fails if the locale
  36 changes between the string conversion and the locale-to-JSON
  37 conversion. This can only happen in multithreaded programs that use
  38 ``setlocale()``, because ``setlocale()`` switches the locale for all
  39 running threads, not only the thread that calls ``setlocale()``.
  40
  41 If your program uses ``setlocale()`` as described above, consider
  42 using the thread-safe ``uselocale()`` instead.