doc: Add project status to introduction, add portability chapter

Move the multithreading-and-setlocale documentation to the new
portability chapter.

Fixes GH-36.

diff --git a/doc/apiref.rst b/doc/apiref.rst
index b49861d..59d86fb 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
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.