--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/components/jansson/doc/html/portability.html Wed Oct 29 17:55:16 2014 +0100
@@ -0,0 +1,186 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Portability — Jansson 2.7 documentation</title>
+
+ <link rel="stylesheet" href="_static/default.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '2.7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="Jansson 2.7 documentation" href="index.html" />
+ <link rel="next" title="API Reference" href="apiref.html" />
+ <link rel="prev" title="RFC Conformance" href="conformance.html" />
+ </head>
+ <body>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="apiref.html" title="API Reference"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="conformance.html" title="RFC Conformance"
+ accesskey="P">previous</a> |</li>
+ <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
+ </ul>
+ </div>
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body">
+
+ <div class="section" id="portability">
+<h1>Portability<a class="headerlink" href="#portability" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="thread-safety">
+<span id="portability-thread-safety"></span><h2>Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline">¶</a></h2>
+<p>Jansson is thread safe and has no mutable global state. The only
+exceptions are the hash function seed and memory allocation functions,
+see below.</p>
+<p>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.</p>
+<p>The encoding functions (<a class="reference internal" href="apiref.html#c.json_dumps" title="json_dumps"><tt class="xref c c-func docutils literal"><span class="pre">json_dumps()</span></tt></a> 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.</p>
+<p>If you want to make sure that two JSON value hierarchies do not
+contain shared values, use <a class="reference internal" href="apiref.html#c.json_deep_copy" title="json_deep_copy"><tt class="xref c c-func docutils literal"><span class="pre">json_deep_copy()</span></tt></a> to make copies.</p>
+<div class="section" id="hash-function-seed">
+<h3>Hash function seed<a class="headerlink" href="#hash-function-seed" title="Permalink to this headline">¶</a></h3>
+<p>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
+<a class="reference internal" href="apiref.html#c.json_object" title="json_object"><tt class="xref c c-func docutils literal"><span class="pre">json_object()</span></tt></a>, if <a class="reference internal" href="apiref.html#c.json_object_seed" title="json_object_seed"><tt class="xref c c-func docutils literal"><span class="pre">json_object_seed()</span></tt></a> has not been
+called beforehand.</p>
+<p>The seed is generated by using operating system’s entropy sources if
+they are available (<tt class="docutils literal"><span class="pre">/dev/urandom</span></tt>, <tt class="docutils literal"><span class="pre">CryptGenRandom()</span></tt>). 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.</p>
+<p>If you’re using threads, it’s recommended to autoseed the hashtable
+explicitly before spawning any threads by calling
+<tt class="docutils literal"><span class="pre">json_object_seed(0)</span></tt> , especially if you’re unsure whether the
+initialization is thread safe on your platform.</p>
+</div>
+<div class="section" id="memory-allocation-functions">
+<h3>Memory allocation functions<a class="headerlink" href="#memory-allocation-functions" title="Permalink to this headline">¶</a></h3>
+<p>Memory allocation functions should be set at most once, and only on
+program startup. See <a class="reference internal" href="apiref.html#apiref-custom-memory-allocation"><em>Custom Memory Allocation</em></a>.</p>
+</div>
+</div>
+<div class="section" id="locale">
+<h2>Locale<a class="headerlink" href="#locale" title="Permalink to this headline">¶</a></h2>
+<p>Jansson works fine under any locale.</p>
+<p>However, if the host program is multithreaded and uses <tt class="docutils literal"><span class="pre">setlocale()</span></tt>
+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.</p>
+<p>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
+<tt class="docutils literal"><span class="pre">setlocale()</span></tt>, because <tt class="docutils literal"><span class="pre">setlocale()</span></tt> switches the locale for all
+running threads, not only the thread that calls <tt class="docutils literal"><span class="pre">setlocale()</span></tt>.</p>
+<p>If your program uses <tt class="docutils literal"><span class="pre">setlocale()</span></tt> as described above, consider
+using the thread-safe <tt class="docutils literal"><span class="pre">uselocale()</span></tt> instead.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Portability</a><ul>
+<li><a class="reference internal" href="#thread-safety">Thread safety</a><ul>
+<li><a class="reference internal" href="#hash-function-seed">Hash function seed</a></li>
+<li><a class="reference internal" href="#memory-allocation-functions">Memory allocation functions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#locale">Locale</a></li>
+</ul>
+</li>
+</ul>
+
+ <h4>Previous topic</h4>
+ <p class="topless"><a href="conformance.html"
+ title="previous chapter">RFC Conformance</a></p>
+ <h4>Next topic</h4>
+ <p class="topless"><a href="apiref.html"
+ title="next chapter">API Reference</a></p>
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="_sources/portability.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+<div id="searchbox" style="display: none">
+ <h3>Quick search</h3>
+ <form class="search" action="search.html" method="get">
+ <input type="text" name="q" />
+ <input type="submit" value="Go" />
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+ <p class="searchtip" style="font-size: 90%">
+ Enter search terms or a module, class or function name.
+ </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="apiref.html" title="API Reference"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="conformance.html" title="RFC Conformance"
+ >previous</a> |</li>
+ <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2009-2014, Petri Lehtinen.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file