4139N/A<!
DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 4139N/A <
meta http-
equiv="Content-Type" content="text/html; charset=utf-8" />
4139N/A <
title>Portability — Jansson 2.7 documentation</
title>
4139N/A var DOCUMENTATION_OPTIONS = {
4139N/A <
li class="right" style="margin-right: 10px">
4139N/A accesskey="I">index</
a></
li>
4139N/A accesskey="N">next</
a> |</
li>
4139N/A accesskey="P">previous</
a> |</
li>
4139N/A <
div class="documentwrapper">
4139N/A <
div class="section" id="portability">
4139N/A<
h1>Portability<
a class="headerlink" href="#portability" title="Permalink to this headline">¶</
a></
h1>
4139N/A<
div class="section" id="thread-safety">
4139N/A<
span id="portability-thread-safety"></
span><
h2>Thread safety<
a class="headerlink" href="#thread-safety" title="Permalink to this headline">¶</
a></
h2>
4139N/A<
p>Jansson is thread safe and has no mutable global state. The only
4139N/Aexceptions are the hash function seed and memory allocation functions,
4139N/A<
p>There’s no locking performed inside Jansson’s code, so a multithreaded
4139N/Aprogram must perform its own locking if JSON values are shared by
4139N/Amultiple threads. Jansson’s reference counting semantics may make this
4139N/Aa bit harder than it seems, as it’s possible to have a reference to a
4139N/Avalue that’s also stored inside a list or object. Modifying the
4139N/Acontainer (adding or removing values) may trigger concurrent access to
4139N/Asuch values, as containers manage the reference count of their
4139N/Acontained values. Bugs involving concurrent incrementing or
4139N/Adecrementing of deference counts may be hard to track.</
p>
4139N/A<
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
4139N/Areference loops by modifying the internal state of objects and arrays.
4139N/AFor this reason, encoding functions must not be run on the same JSON
4139N/Avalues in two separate threads at the same time. As already noted
4139N/Aabove, be especially careful if two arrays or objects share their
4139N/Acontained values with another array or object.</
p>
4139N/A<
p>If you want to make sure that two JSON value hierarchies do not
4139N/Acontain 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>
4139N/A<
div class="section" id="hash-function-seed">
4139N/A<
h3>Hash function seed<
a class="headerlink" href="#hash-function-seed" title="Permalink to this headline">¶</
a></
h3>
4139N/A<
p>To prevent an attacker from intentionally causing large JSON objects
4139N/Awith specially crafted keys to perform very slow, the hash function
4139N/Aused by Jansson is randomized using a seed value. The seed is
4139N/Aautomatically generated on the first explicit or implicit call to
4139N/A<
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
4139N/A<
p>The seed is generated by using operating system’s entropy sources if
4139N/Athey are available (<
tt class="docutils literal"><
span class="pre">/
dev/
urandom</
span></
tt>, <
tt class="docutils literal"><
span class="pre">CryptGenRandom()</
span></
tt>). The
4139N/Ainitialization is done in as thread safe manner as possible, by using
4139N/Aarchitecture specific lockless operations if provided by the platform
4139N/A<
p>If you’re using threads, it’s recommended to autoseed the hashtable
4139N/Aexplicitly before spawning any threads by calling
4139N/A<
tt class="docutils literal"><
span class="pre">json_object_seed(0)</
span></
tt> , especially if you’re unsure whether the
4139N/Ainitialization is thread safe on your platform.</
p>
4139N/A<
div class="section" id="memory-allocation-functions">
4139N/A<
h3>Memory allocation functions<
a class="headerlink" href="#memory-allocation-functions" title="Permalink to this headline">¶</
a></
h3>
4139N/A<
p>Memory allocation functions should be set at most once, and only on
4139N/Aprogram startup. See <
a class="reference internal" href="apiref.html#apiref-custom-memory-allocation"><
em>Custom Memory Allocation</
em></
a>.</
p>
4139N/A<
div class="section" id="locale">
4139N/A<
h2>Locale<
a class="headerlink" href="#locale" title="Permalink to this headline">¶</
a></
h2>
4139N/A<
p>Jansson works fine under any locale.</
p>
4139N/A<
p>However, if the host program is multithreaded and uses <
tt class="docutils literal"><
span class="pre">setlocale()</
span></
tt>
4139N/Ato switch the locale in one thread while Jansson is currently encoding
4139N/Aor decoding JSON data in another thread, the result may be wrong or
4139N/Athe program may even crash.</
p>
4139N/A<
p>Jansson uses locale specific functions for certain string conversions
4139N/Ain the encoder and decoder, and then converts the locale specific
4139N/Avalues
to/
from the JSON representation. This fails if the locale
4139N/Achanges between the string conversion and the locale-to-JSON
4139N/Aconversion. This can only happen in multithreaded programs that use
4139N/A<
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
4139N/Arunning threads, not only the thread that calls <
tt class="docutils literal"><
span class="pre">setlocale()</
span></
tt>.</
p>
4139N/A<
p>If your program uses <
tt class="docutils literal"><
span class="pre">setlocale()</
span></
tt> as described above, consider
4139N/Ausing the thread-safe <
tt class="docutils literal"><
span class="pre">uselocale()</
span></
tt> instead.</
p>
4139N/A <
div class="sphinxsidebar">
4139N/A <
div class="sphinxsidebarwrapper">
4139N/A<
li><
a class="reference internal" href="#">Portability</
a><
ul>
4139N/A<
li><
a class="reference internal" href="#thread-safety">Thread safety</
a><
ul>
4139N/A<
li><
a class="reference internal" href="#hash-function-seed">Hash function seed</
a></
li>
4139N/A<
li><
a class="reference internal" href="#memory-allocation-functions">Memory allocation functions</
a></
li>
4139N/A<
li><
a class="reference internal" href="#locale">Locale</
a></
li>
4139N/A title="previous chapter">RFC Conformance</
a></
p>
4139N/A title="next chapter">API Reference</
a></
p>
4139N/A <
ul class="this-page-menu">
4139N/A rel="nofollow">Show Source</
a></
li>
4139N/A<
div id="searchbox" style="display: none">
4139N/A <
input type="text" name="q" />
4139N/A <
input type="submit" value="Go" />
4139N/A <
input type="hidden" name="check_keywords" value="yes" />
4139N/A <
input type="hidden" name="area" value="default" />
4139N/A <
p class="searchtip" style="font-size: 90%">
4139N/A Enter search terms or a module, class or function name.
4139N/A <
div class="clearer"></
div>
4139N/A <
li class="right" style="margin-right: 10px">
4139N/A © Copyright 2009-2014, Petri Lehtinen.