Please sign in to comment.
doc: Add project status to introduction, add portability chapter
Move the multithreading-and-setlocale documentation to the new portability chapter. Fixes GH-36.
- Loading branch information...
Showing with 51 additions and 24 deletions.
|@@ -0,0 +1,42 @@|
|+Jansson is thread safe and has no mutable global state. The only|
|+exception are the memory allocation functions, that should be set at|
|+most once, and only on program startup. See|
|+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.|
|+Jansson works fine under any locale.|
|+However, if the host program is multithreaded and uses ``setlocale()``|
|+to switch the locale in one thread while Jansson is currently encoding|
|+or decoding JSON data in another thread, the result may be wrong or|
|+the program may even crash.|
|+Jansson uses locale specific functions for certain string conversions|
|+in the encoder and decoder, and then converts the locale specific|
|+values to/from the JSON representation. This fails if the locale|
|+changes between the string conversion and the locale-to-JSON|
|+conversion. This can only happen in multithreaded programs that use|
|+``setlocale()``, because ``setlocale()`` switches the locale for all|
|+running threads, not only the thread that calls ``setlocale()``.|
|+If your program uses ``setlocale()`` as described above, consider|
|+using the thread-safe ``uselocale()`` instead.|