--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/components/jansson/doc/html/_sources/portability.txt	Fri Apr 17 01:30:52 2015 -0700
@@ -0,0 +1,83 @@
+***********
+Portability
+***********
+
+.. _portability-thread-safety:
+
+Thread safety
+-------------
+
+Jansson is thread safe and has no mutable global state. The only
+exceptions are the hash function seed and memory allocation functions,
+see below.
+
+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.
+
+The encoding functions (:func:`json_dumps()` and friends) track
+reference loops by modifying the internal state of objects and arrays.
+For this reason, encoding functions must not be run on the same JSON
+values in two separate threads at the same time. As already noted
+above, be especially careful if two arrays or objects share their
+contained values with another array or object.
+
+If you want to make sure that two JSON value hierarchies do not
+contain shared values, use :func:`json_deep_copy()` to make copies.
+
+
+Hash function seed
+==================
+
+To prevent an attacker from intentionally causing large JSON objects
+with specially crafted keys to perform very slow, the hash function
+used by Jansson is randomized using a seed value. The seed is
+automatically generated on the first explicit or implicit call to
+:func:`json_object()`, if :func:`json_object_seed()` has not been
+called beforehand.
+
+The seed is generated by using operating system's entropy sources if
+they are available (``/dev/urandom``, ``CryptGenRandom()``). The
+initialization is done in as thread safe manner as possible, by using
+architecture specific lockless operations if provided by the platform
+or the compiler.
+
+If you're using threads, it's recommended to autoseed the hashtable
+explicitly before spawning any threads by calling
+``json_object_seed(0)`` , especially if you're unsure whether the
+initialization is thread safe on your platform.
+
+
+Memory allocation functions
+===========================
+
+Memory allocation functions should be set at most once, and only on
+program startup. See :ref:`apiref-custom-memory-allocation`.
+
+
+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.