portability.html revision 3421
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<html xmlns="http://www.w3.org/1999/xhtml">
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <title>Portability — Jansson 2.7 documentation</title>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <link rel="stylesheet" href="_static/default.css" type="text/css" />
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher var DOCUMENTATION_OPTIONS = {
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher URL_ROOT: './',
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher VERSION: '2.7',
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher COLLAPSE_INDEX: false,
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher FILE_SUFFIX: '.html',
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher HAS_SOURCE: true
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <script type="text/javascript" src="_static/jquery.js"></script>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <script type="text/javascript" src="_static/underscore.js"></script>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <script type="text/javascript" src="_static/doctools.js"></script>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <link rel="top" title="Jansson 2.7 documentation" href="index.html" />
d0e0e73e86f2afdb7f8fefbed70fda8d77b1c25aStephen Gallagher <link rel="next" title="API Reference" href="apiref.html" />
008e1ee835602023891ac45408483d87f41e4d5cSumit Bose <link rel="prev" title="RFC Conformance" href="conformance.html" />
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <li class="right" style="margin-right: 10px">
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <a href="apiref.html" title="API Reference"
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <a href="conformance.html" title="RFC Conformance"
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<h1>Portability<a class="headerlink" href="#portability" title="Permalink to this headline">¶</a></h1>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<span id="portability-thread-safety"></span><h2>Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline">¶</a></h2>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>Jansson is thread safe and has no mutable global state. The only
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherexceptions are the hash function seed and memory allocation functions,
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>There’s no locking performed inside Jansson’s code, so a multithreaded
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherprogram must perform its own locking if JSON values are shared by
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghermultiple threads. Jansson’s reference counting semantics may make this
2ce00e0d3896bb42db169d1e79553a81ca837a22Simo Sorcea bit harder than it seems, as it’s possible to have a reference to a
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghervalue that’s also stored inside a list or object. Modifying the
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghercontainer (adding or removing values) may trigger concurrent access to
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghersuch values, as containers manage the reference count of their
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghercontained values. Bugs involving concurrent incrementing or
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherdecrementing of deference counts may be hard to track.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<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
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherreference loops by modifying the internal state of objects and arrays.
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen GallagherFor this reason, encoding functions must not be run on the same JSON
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghervalues in two separate threads at the same time. As already noted
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherabove, be especially careful if two arrays or objects share their
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghercontained values with another array or object.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>If you want to make sure that two JSON value hierarchies do not
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghercontain 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>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<div class="section" id="hash-function-seed">
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<h3>Hash function seed<a class="headerlink" href="#hash-function-seed" title="Permalink to this headline">¶</a></h3>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>To prevent an attacker from intentionally causing large JSON objects
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherwith specially crafted keys to perform very slow, the hash function
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherused by Jansson is randomized using a seed value. The seed is
2ce00e0d3896bb42db169d1e79553a81ca837a22Simo Sorceautomatically generated on the first explicit or implicit call to
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<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
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallaghercalled beforehand.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>The seed is generated by using operating system’s entropy sources if
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherthey are available (<tt class="docutils literal"><span class="pre">/dev/urandom</span></tt>, <tt class="docutils literal"><span class="pre">CryptGenRandom()</span></tt>). The
749cfb5d3270b5daf389d51a0dbd3fd2aec6e05dJakub Hrozekinitialization is done in as thread safe manner as possible, by using
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherarchitecture specific lockless operations if provided by the platform
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagheror the compiler.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>If you’re using threads, it’s recommended to autoseed the hashtable
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherexplicitly before spawning any threads by calling
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<tt class="docutils literal"><span class="pre">json_object_seed(0)</span></tt> , especially if you’re unsure whether the
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherinitialization is thread safe on your platform.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<div class="section" id="memory-allocation-functions">
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<h3>Memory allocation functions<a class="headerlink" href="#memory-allocation-functions" title="Permalink to this headline">¶</a></h3>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>Memory allocation functions should be set at most once, and only on
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherprogram startup. See <a class="reference internal" href="apiref.html#apiref-custom-memory-allocation"><em>Custom Memory Allocation</em></a>.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<h2>Locale<a class="headerlink" href="#locale" title="Permalink to this headline">¶</a></h2>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>Jansson works fine under any locale.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>However, if the host program is multithreaded and uses <tt class="docutils literal"><span class="pre">setlocale()</span></tt>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherto switch the locale in one thread while Jansson is currently encoding
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagheror decoding JSON data in another thread, the result may be wrong or
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherthe program may even crash.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>Jansson uses locale specific functions for certain string conversions
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashovin the encoder and decoder, and then converts the locale specific
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashovvalues to/from the JSON representation. This fails if the locale
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherchanges between the string conversion and the locale-to-JSON
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherconversion. This can only happen in multithreaded programs that use
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<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
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherrunning threads, not only the thread that calls <tt class="docutils literal"><span class="pre">setlocale()</span></tt>.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<p>If your program uses <tt class="docutils literal"><span class="pre">setlocale()</span></tt> as described above, consider
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagherusing the thread-safe <tt class="docutils literal"><span class="pre">uselocale()</span></tt> instead.</p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <h3><a href="index.html">Table Of Contents</a></h3>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<li><a class="reference internal" href="#">Portability</a><ul>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<li><a class="reference internal" href="#thread-safety">Thread safety</a><ul>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<li><a class="reference internal" href="#hash-function-seed">Hash function seed</a></li>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<li><a class="reference internal" href="#memory-allocation-functions">Memory allocation functions</a></li>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<li><a class="reference internal" href="#locale">Locale</a></li>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <p class="topless"><a href="conformance.html"
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher title="previous chapter">RFC Conformance</a></p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher title="next chapter">API Reference</a></p>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <form class="search" action="search.html" method="get">
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <input type="hidden" name="check_keywords" value="yes" />
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <input type="hidden" name="area" value="default" />
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <p class="searchtip" style="font-size: 90%">
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher Enter search terms or a module, class or function name.
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher<script type="text/javascript">$('#searchbox').show(0);</script>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <li class="right" style="margin-right: 10px">
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <a href="genindex.html" title="General Index"
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <a href="apiref.html" title="API Reference"
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <a href="conformance.html" title="RFC Conformance"
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher © Copyright 2009-2014, Petri Lehtinen.
d42d371c00c83ae44b9d1c3e88ecbe0e01b112e6Stephen Gallagher Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.