/usr/share/doc/libjansson-dev/html/portability.html is in libjansson-doc 2.11-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | <!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.11 documentation</title>
<link rel="stylesheet" href="_static/alabaster.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.11',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="API Reference" href="apiref.html" />
<link rel="prev" title="RFC Conformance" href="conformance.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<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 as a library 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. <strong>Read-only</strong>
access to JSON values shared by multiple threads is safe, but
<strong>mutating</strong> a JSON value that’s shared by multiple threads is not. A
multithreaded program must perform its own locking if JSON values
shared by multiple threads are mutated.</p>
<p>However, <strong>reference count manipulation</strong> (<a class="reference internal" href="apiref.html#c.json_incref" title="json_incref"><code class="xref c c-func docutils literal"><span class="pre">json_incref()</span></code></a>,
<a class="reference internal" href="apiref.html#c.json_decref" title="json_decref"><code class="xref c c-func docutils literal"><span class="pre">json_decref()</span></code></a>) is usually thread-safe, and can be performed on
JSON values that are shared among threads. The thread-safety of
reference counting can be checked with the
<code class="docutils literal"><span class="pre">JANSSON_THREAD_SAFE_REFCOUNT</span></code> preprocessor constant. Thread-safe
reference count manipulation is achieved using compiler built-in
atomic functions, which are available in most modern compilers.</p>
<p>If compiler support is not available (<code class="docutils literal"><span class="pre">JANSSON_THREAD_SAFE_REFCOUNT</span></code>
is not defined), it may be very difficult to ensure thread safety of
reference counting. It’s possible to have a reference to a value
that’s also stored inside an array or object in another thread.
Modifying the container (adding or removing values) may trigger
concurrent access to such values, as containers manage the reference
count of their contained values.</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"><code class="xref c c-func docutils literal"><span class="pre">json_object()</span></code></a>, if <a class="reference internal" href="apiref.html#c.json_object_seed" title="json_object_seed"><code class="xref c c-func docutils literal"><span class="pre">json_object_seed()</span></code></a> has not been
called beforehand.</p>
<p>The seed is generated by using operating system’s entropy sources if
they are available (<code class="docutils literal"><span class="pre">/dev/urandom</span></code>, <code class="docutils literal"><span class="pre">CryptGenRandom()</span></code>). 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
<code class="docutils literal"><span class="pre">json_object_seed(0)</span></code> , 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"><span class="std std-ref">Custom Memory Allocation</span></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 <code class="docutils literal"><span class="pre">setlocale()</span></code>
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
<code class="docutils literal"><span class="pre">setlocale()</span></code>, because <code class="docutils literal"><span class="pre">setlocale()</span></code> switches the locale for all
running threads, not only the thread that calls <code class="docutils literal"><span class="pre">setlocale()</span></code>.</p>
<p>If your program uses <code class="docutils literal"><span class="pre">setlocale()</span></code> as described above, consider
using the thread-safe <code class="docutils literal"><span class="pre">uselocale()</span></code> instead.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<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>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="conformance.html" title="previous chapter">RFC Conformance</a></li>
<li>Next: <a href="apiref.html" title="next chapter">API Reference</a></li>
</ul></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/portability.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2009-2018, Petri Lehtinen.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.6</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
|
<a href="_sources/portability.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|