PSARC/2014/362 Jansson
19903653 Jansson - C library for working with JSON should be added to Userland
<!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>