Permalink
Browse files

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...
1 parent f0d5c04 commit 0f358c8eaa2bd68dc2618ca816aa85e23bb1ae7e @akheron committed Oct 3, 2011
Showing with 51 additions and 24 deletions.
  1. +2 −0 doc/apiref.rst
  2. +1 −24 doc/conformance.rst
  3. +6 −0 doc/index.rst
  4. +42 −0 doc/portability.rst
View
@@ -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
========================
View
@@ -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.
View
@@ -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
View
@@ -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.

0 comments on commit 0f358c8

Please sign in to comment.