From 0f358c8eaa2bd68dc2618ca816aa85e23bb1ae7e Mon Sep 17 00:00:00 2001 From: Petri Lehtinen Date: Mon, 3 Oct 2011 22:42:39 +0300 Subject: [PATCH] doc: Add project status to introduction, add portability chapter Move the multithreading-and-setlocale documentation to the new portability chapter. Fixes GH-36. --- doc/apiref.rst | 2 ++ doc/conformance.rst | 25 +------------------------ doc/index.rst | 6 ++++++ doc/portability.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 51 insertions(+), 24 deletions(-) create mode 100644 doc/portability.rst diff --git a/doc/apiref.rst b/doc/apiref.rst index b49861d..59d86fb 100644 --- a/doc/apiref.rst +++ b/doc/apiref.rst @@ -1191,6 +1191,8 @@ copied in a recursive fashion. Returns a deep copy of *value*, or *NULL* on error. +.. _apiref-custom-memory-allocation: + Custom Memory Allocation ======================== diff --git a/doc/conformance.rst b/doc/conformance.rst index 3446e26..6f4c929 100644 --- a/doc/conformance.rst +++ b/doc/conformance.rst @@ -5,8 +5,7 @@ RFC Conformance *************** JSON is specified in :rfc:`4627`, *"The application/json Media Type -for JavaScript Object Notation (JSON)"*. This chapter discusses -Jansson's conformance to this specification. +for JavaScript Object Notation (JSON)"*. Character Encoding ================== @@ -110,25 +109,3 @@ types, ``long double``, etc. Obviously, shorter types like ``short``, are implicitly handled via the ordinary C type coercion rules (subject to overflow semantics). Also, no support or hooks are provided for any supplemental "bignum" type add-on packages. - - -Locale -====== - -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()``, that 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. diff --git a/doc/index.rst b/doc/index.rst index b5a3be8..1f3f8ef 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -22,6 +22,11 @@ data. Its main features and design principles are: Jansson is licensed under the `MIT license`_; see LICENSE in the source distribution for details. +Jansson is used in production and its API is stable. It works on +numerous platforms, including numerous Unix like systems and Windows. +It's suitable for use on any system, including desktop, server, and +small embedded systems. + .. _`MIT license`: http://www.opensource.org/licenses/mit-license.php .. _Jansson: http://www.digip.org/jansson/ @@ -36,6 +41,7 @@ Contents upgrading tutorial conformance + portability apiref changes diff --git a/doc/portability.rst b/doc/portability.rst new file mode 100644 index 0000000..0a49e2e --- /dev/null +++ b/doc/portability.rst @@ -0,0 +1,42 @@ +*********** +Portability +*********** + +Thread safety +------------- + +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 +:ref:`apiref-custom-memory-allocation`. + +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. + +Locale +------ + +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.