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