deploy: cdfb130fa6
This commit is contained in:
1 parent
8ddeea7128
commit
5097c20962
516 files changed
+7306
-5984
No files matched your search
@@ -0,0 +1,72 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/macros/json_recursion_depth_limit/" rel="canonical"><link href=../json_precise_stream_position/ rel=prev><link href=../json_skip_library_version_check/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.8.0"><title>JSON_RECURSION_DEPTH_LIMIT - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.57a0d79d.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.fb2fffe2.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#json_recursion_depth_limit class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> JSON_RECURSION_DEPTH_LIMIT </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=Line truncated
|
||||
</code></pre></div> <p>This macro sets how many nesting levels the operations that walk a value recurse into on the call stack. Beyond that, they continue with an explicit stack on the heap. The value is an integer constant from <code>0</code> to <code>254</code>; the default is <code>128</code>.</p> <p>The operations are copying a value, comparing two values, serializing with <a href=../../basic_json/dump/ ><code>dump</code></a> or <a href=../../operator_ltlt/ ><code>operator<<</code></a>, hashing with <code>std::hash</code>, <a href=../../basic_json/merge_patch/ ><code>merge_patch</code></a>, <a href=../../basic_json/update/ ><code>update</code></a> with <code>merge_objects</code>, <a href=../../basic_json/diff/ ><code>diff</code></a>, <a href=../../basic_json/merge_diff/ ><code>merge_diff</code></a>, converting a value to another specialization of <code>basic_json</code>, destroying a value, and the binary writers <a href=../../basic_json/to_cbor/ ><code>to_cbor</code></a>, <a href=../../basic_json/to_msgpack/ ><code>to_msgpack</code></a>, <a href=../../basic_json/to_ubjson/ ><code>to_ubjson</code></a>, <a href=../../basic_json/to_bjdata/ ><code>to_bjdata</code></a>, and <a href=../../basic_json/to_bon8/ ><code>to_bon8</code></a>. They share this one limit; none has a limit of its own. Recursing is the fastest way to walk a value, but a value nested deeply enough would exhaust the call stack, so the library recurses only as far as the limit and finishes the levels below with an explicit stack. This is what makes all of them safe for untrusted input (see <a href=../../../features/parsing/untrusted_input/#nesting-depth>Nesting depth</a>). Parsing, the binary readers, <a href=../../basic_json/flatten/ ><code>flatten</code></a>, <a href=../../basic_json/unflatten/ ><code>unflatten</code></a>, and <a href=../../basic_json/to_bson/ ><code>to_bson</code></a> always use an explicit stack and do not depend on the macro. The lockstep comparison of two <a href=../../basic_json_view/ ><code>json_view</code></a> documents has a fixed bound of its own, 48 levels, and does not depend on it either.</p> <p>The call stack that these operations need grows with the limit: roughly <em>a few kilobytes plus a cost per level times the limit</em>, where the cost per level is up to about 2.3 KiB in an unoptimized and up to about 0.5 KiB in an optimized build (see <a href=#stack-needed>Stack needed</a>). The default of <code>128</code> levels is tuned for threads with ordinary stacks of a few hundred kilobytes or more. Set a lower limit if your threads have small stacks (RTOS tasks, fibers, threads of the musl C library, which has a default stack of 128 KiB), or a higher limit to trade stack for speed on deeply nested values.</p> <p>The macro changes only how much stack is used and how fast the operations are. It never changes a result: every operation returns the same value for every setting of the limit, for values nested less deeply than the limit as well as for values nested more deeply.</p> <h2 id=default-definition>Default definition<a class=headerlink href=#default-definition title="Permanent link">¶</a></h2> <p>The default value is <code>128</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#define JSON_RECURSION_DEPTH_LIMIT 128</span>
|
||||
</code></pre></div> <p>When the macro is not defined, the library defines it to its default value.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <div class="admonition note"> <p class=admonition-title>Allowed values</p> <p>The value must be an integer constant expression from <code>0</code> to <code>254</code>; any other value (a negative number, a number above <code>254</code>, a floating-point number such as <code>254.0</code>, or <code>true</code> or <code>false</code>) is rejected at compile time with an error message that names the macro. A character of any character type (<code>'a'</code>, <code>L'a'</code>, <code>u8'a'</code>, ...) is rejected, too, although it is an integer.</p> <ul> <li><code>0</code> is allowed, and means that every operation uses its explicit stack from the first level on and no operation recurses over the nesting of a value at all. That needs a constant amount of call stack (at most 16 KiB in the measurements below, for a value nested 20,000 levels deep) and is the setting for tiny stacks, at the price of speed (see <a href=#speed>Speed</a>).</li> <li><code>254</code> is the largest allowed value. Copying a value and comparing two values (with <code><=></code>, or with the operators on objects and arrays of a custom type) cannot pass the depth down as an argument, because the signatures of the copy constructor and the operators are fixed. They count the levels they have descended into in a variable of type <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span></code> that exists once per thread (see <a href=../json_no_thread_local/ ><code>JSON_NO_THREAD_LOCAL</code></a>). Only the levels that are descended into are counted, so the count never exceeds the limit, not even when user code (a copy constructor of a custom base class, say) copies a value while a copy is going on. A byte holds <code>255</code> at most, and the limit stays below that, so that the count cannot wrap around. (More levels would hardly be useful: <code>254</code> levels need up to 576 KiB of stack in an unoptimized build already, twice as much as the default.)</li> </ul> </div> <h3 id=stack-needed>Stack needed<a class=headerlink href=#stack-needed title="Permanent link">¶</a></h3> <p>The tables show the smallest stack that an operation needs, in KiB, at several limits, on a value that is nested more deeply than the limit (limit + 10 levels). Each cell shows the result for Clang (Apple clang 21) and for <abbr title="GNU Compiler Collection">GCC</abbr> 16, separated by a slash; both measured on macOS with arm64, compiling in C++20 mode. The operations run in a thread whose stack has the size given, and are not given any stack that they do not need: the value is built, and the result destroyed, outside of that thread. Stacks can only be set in steps of 16 KiB (the page size), so <code>16</code> means "16 KiB or less". A row stands for all operations listed; the table shows the largest value among them.</p> <p>Unoptimized (<code>-O0</code>):</p> <table> <thead> <tr> <th>Operation</th> <th style="text-align: right;">limit 16</th> <th style="text-align: right;">limit 32</th> <th style="text-align: right;">limit 64</th> <th style="text-align: right;">limit 128</th> <th style="text-align: right;">limit 254</th> </tr> </thead> <tbody> <tr> <td><code>dump()</code> and <code>dump(indent)</code>, <code>operator<<</code></td> <td style="text-align: right;">48 / 32</td> <td style="text-align: right;">80 / 64</td> <td style="text-align: right;">144 / 128</td> <td style="text-align: right;">288 / 256</td> <td style="text-align: right;">576 / 512</td> </tr> <tr> <td>copy construction and assignment</td> <td style="text-align: right;">32 / 16</td> <td style="text-align: right;">48 / 32</td> <td style="text-align: right;">112 / 80</td> <td style="text-align: right;">224 / 144</td> <td style="text-align: right;">432 / 304</td> </tr> <tr> <td><code>==</code></td> <td style="text-align: right;">16 / 16</td> <td style="text-align: right;">16 / 16</td> <td style="text-align: right;">16 / 16</td> <td style="text-align: right;">48 / 32</td> <td style="text-align: right;">96 / 48</td> </tr> <tr> <td><code><=></code> (C++20)</td> <td style="text-align: right;">16 / 16</td> <td style="text-align: right;">16 / 16</td> <td style="text-align: right;">32 / 32</td> <td style="text-align: right;">64 / 64</td> <td style="text-align: right;">144 / 128</td> </tr> <tr> <td><code>std::hash</code></td> <td style="text-align: right;">16 / 16</td> <td style="text-align: right;">16 / 16</td> <td style="text-align: right;">32 / 32</td> <td style="text-align: right;">80 / 64</td> <td style="text-align: right;">160 / 128</td> </tr> <tr> <td><code>merge_patch</code>, <code>update(j, true)</code>, <code>patch</code></td> <td style="text-align: right;">32 / 16</td> <td style="text-align: right;">48 / 32</td> <td style="text-align: right;">112 / Line truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><utility></span>
|
||||
|
||||
<span class=c1>// walk over at most 16 nesting levels on the call stack, and over the rest with an explicit stack</span>
|
||||
<span class=cp>#define JSON_RECURSION_DEPTH_LIMIT 16</span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// an array nested 5,000 levels deep, built without recursion</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=mi>1</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=k>for</span><span class=w> </span><span class=p>(</span><span class=kt>int</span><span class=w> </span><span class=n>i</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=mi>0</span><span class=p>;</span><span class=w> </span><span class=n>i</span><span class=w> </span><span class=o><</span><span class=w> </span><span class=mi>5000</span><span class=p>;</span><span class=w> </span><span class=o>++</span><span class=n>i</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>outer</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>array</span><span class=p>();</span>
|
||||
<span class=w> </span><span class=n>outer</span><span class=p>.</span><span class=n>push_back</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>move</span><span class=p>(</span><span class=n>j</span><span class=p>));</span>
|
||||
<span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>move</span><span class=p>(</span><span class=n>outer</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// the results are those of any other limit</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>copy</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>j</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"limit: "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>JSON_RECURSION_DEPTH_LIMIT</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"copy equals original: "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=p>(</span><span class=n>copy</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>j</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"length of dump(): "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>dump</span><span class=p>().</span><span class=n>size</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"same hash: "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>copy</span><span class=p>)</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>j</span><span class=p>))</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code>limit: 16
|
||||
copy equals original: true
|
||||
length of dump(): 10001
|
||||
same hash: true
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: find out how much stack an operation needs</summary> <p>The program runs <code>dump()</code> on a value nested <code>depth</code> levels deep in a thread with a stack of <code>kib</code> KiB. Compile it with the options and the limit that you use, e.g. <code>-DJSON_RECURSION_DEPTH_LIMIT=64</code>, run it with <code>depth</code> set to the limit plus 10 and decreasing values of <code>kib</code> (the stack size must be a multiple of the page size, often 4 or 16 KiB), and note the smallest stack with which it still finishes. That is how the tables above were measured.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><cstdlib></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><string></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><utility></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><pthread.h></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>static</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=w> </span><span class=n>value</span><span class=p>;</span>
|
||||
|
||||
<span class=k>static</span><span class=w> </span><span class=kt>void</span><span class=o>*</span><span class=w> </span><span class=nf>run</span><span class=p>(</span><span class=kt>void</span><span class=o>*</span><span class=p>)</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"dump() ok, "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>value</span><span class=p>.</span><span class=n>dump</span><span class=p>().</span><span class=n>size</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>" bytes</span><span class=se>\n</span><span class=s>"</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=k>return</span><span class=w> </span><span class=nb>nullptr</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>(</span><span class=kt>int</span><span class=w> </span><span class=n>argc</span><span class=p>,</span><span class=w> </span><span class=kt>char</span><span class=o>**</span><span class=w> </span><span class=n>argv</span><span class=p>)</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>int</span><span class=w> </span><span class=n>depth</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>atoi</span><span class=p>(</span><span class=n>argv</span><span class=p>[</span><span class=mi>1</span><span class=p>]);</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span><span class=w> </span><span class=n>kib</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=k>static_cast</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span><span class=o>></span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>atoi</span><span class=p>(</span><span class=n>argv</span><span class=p>[</span><span class=mi>2</span><span class=p>]));</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// built on the main thread, without recursion</span>
|
||||
<span class=w> </span><span class=n>value</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=mi>1</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=k>for</span><span class=w> </span><span class=p>(</span><span class=kt>int</span><span class=w> </span><span class=n>i</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=mi>0</span><span class=p>;</span><span class=w> </span><span class=n>i</span><span class=w> </span><span class=o><</span><span class=w> </span><span class=n>depth</span><span class=p>;</span><span class=w> </span><span class=o>++</span><span class=n>i</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=w> </span><span class=n>outer</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>::</span><span class=n>array</span><span class=p>();</span>
|
||||
<span class=w> </span><span class=n>outer</span><span class=p>.</span><span class=n>push_back</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>move</span><span class=p>(</span><span class=n>value</span><span class=p>));</span>
|
||||
<span class=w> </span><span class=n>value</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>move</span><span class=p>(</span><span class=n>outer</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
|
||||
<span class=w> </span><span class=n>pthread_attr_t</span><span class=w> </span><span class=n>attr</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>pthread_attr_init</span><span class=p>(</span><span class=o>&</span><span class=n>attr</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>pthread_attr_setstacksize</span><span class=p>(</span><span class=o>&</span><span class=n>attr</span><span class=p>,</span><span class=w> </span><span class=n>kib</span><span class=w> </span><span class=o>*</span><span class=w> </span><span class=mi>1024</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>pthread_t</span><span class=w> </span><span class=kr>thread</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>pthread_create</span><span class=p>(</span><span class=o>&</span><span class=kr>thread</span><span class=p>,</span><span class=w> </span><span class=o>&</span><span class=n>attr</span><span class=p>,</span><span class=w> </span><span class=n>run</span><span class=p>,</span><span class=w> </span><span class=nb>nullptr</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>pthread_join</span><span class=p>(</span><span class=kr>thread</span><span class=p>,</span><span class=w> </span><span class=nb>nullptr</span><span class=p>);</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../../features/parsing/untrusted_input/#nesting-depth>Nesting depth</a> - how the library handles deeply nested values</li> <li><a href=../json_no_thread_local/ ><code>JSON_NO_THREAD_LOCAL</code></a> - switch off the use of <code>thread_local</code> storage</li> <li><a href=../../../features/macros/ >Supported Macros</a> - guide to all supported macros</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="November 11, 2026 21:32:05 UTC">November 11, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../json_precise_stream_position/ class="md-footer__link md-footer__link--prev" aria-label="Previous: JSON_PRECISE_STREAM_POSITION"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> JSON_PRECISE_STREAM_POSITION </div> </div> </a> <a href=../json_skip_library_version_check/ class="md-footer__link md-footer__link--next" aria-label="Next: JSON_SKIP_LIBRARY_VERSION_CHECK"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> JSON_SKIP_LIBRARY_VERSION_CHECK </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-Line truncated
|
||||
@@ -0,0 +1,249 @@
|
||||
# JSON_RECURSION_DEPTH_LIMIT
|
||||
|
||||
```
|
||||
#define JSON_RECURSION_DEPTH_LIMIT /* value */
|
||||
```
|
||||
|
||||
This macro sets how many nesting levels the operations that walk a value recurse into on the call stack. Beyond that, they continue with an explicit stack on the heap. The value is an integer constant from `0` to `254`; the default is `128`.
|
||||
|
||||
The operations are copying a value, comparing two values, serializing with [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) or [`operator<<`](https://json.nlohmann.me/api/operator_ltlt/index.md), hashing with `std::hash`, [`merge_patch`](https://json.nlohmann.me/api/basic_json/merge_patch/index.md), [`update`](https://json.nlohmann.me/api/basic_json/update/index.md) with `merge_objects`, [`diff`](https://json.nlohmann.me/api/basic_json/diff/index.md), [`merge_diff`](https://json.nlohmann.me/api/basic_json/merge_diff/index.md), converting a value to another specialization of `basic_json`, destroying a value, and the binary writers [`to_cbor`](https://json.nlohmann.me/api/basic_json/to_cbor/index.md), [`to_msgpack`](https://json.nlohmann.me/api/basic_json/to_msgpack/index.md), [`to_ubjson`](https://json.nlohmann.me/api/basic_json/to_ubjson/index.md), [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md), and [`to_bon8`](https://json.nlohmann.me/api/basic_json/to_bon8/index.md). They share this one limit; none has a limit of its own. Recursing is the fastest way to walk a value, but a value nested deeply enough would exhaust the call stack, so the library recurses only as far as the limit and finishes the levels below with an explicit stack. This is what makes all of them safe for untrusted input (see [Nesting depth](https://json.nlohmann.me/features/parsing/untrusted_input/#nesting-depth)). Parsing, the binary readers, [`flatten`](https://json.nlohmann.me/api/basic_json/flatten/index.md), [`unflatten`](https://json.nlohmann.me/api/basic_json/unflatten/index.md), and [`to_bson`](https://json.nlohmann.me/api/basic_json/to_bson/index.md) always use an explicit stack and do not depend on the macro. The lockstep comparison of two [`json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) documents has a fixed bound of its own, 48 levels, and does not depend on it either.
|
||||
|
||||
The call stack that these operations need grows with the limit: roughly *a few kilobytes plus a cost per level times the limit*, where the cost per level is up to about 2.3 KiB in an unoptimized and up to about 0.5 KiB in an optimized build (see [Stack needed](#stack-needed)). The default of `128` levels is tuned for threads with ordinary stacks of a few hundred kilobytes or more. Set a lower limit if your threads have small stacks (RTOS tasks, fibers, threads of the musl C library, which has a default stack of 128 KiB), or a higher limit to trade stack for speed on deeply nested values.
|
||||
|
||||
The macro changes only how much stack is used and how fast the operations are. It never changes a result: every operation returns the same value for every setting of the limit, for values nested less deeply than the limit as well as for values nested more deeply.
|
||||
|
||||
## Default definition
|
||||
|
||||
The default value is `128`.
|
||||
|
||||
```
|
||||
#define JSON_RECURSION_DEPTH_LIMIT 128
|
||||
```
|
||||
|
||||
When the macro is not defined, the library defines it to its default value.
|
||||
|
||||
## Notes
|
||||
|
||||
Allowed values
|
||||
|
||||
The value must be an integer constant expression from `0` to `254`; any other value (a negative number, a number above `254`, a floating-point number such as `254.0`, or `true` or `false`) is rejected at compile time with an error message that names the macro. A character of any character type (`'a'`, `L'a'`, `u8'a'`, ...) is rejected, too, although it is an integer.
|
||||
|
||||
- `0` is allowed, and means that every operation uses its explicit stack from the first level on and no operation recurses over the nesting of a value at all. That needs a constant amount of call stack (at most 16 KiB in the measurements below, for a value nested 20,000 levels deep) and is the setting for tiny stacks, at the price of speed (see [Speed](#speed)).
|
||||
- `254` is the largest allowed value. Copying a value and comparing two values (with `<=>`, or with the operators on objects and arrays of a custom type) cannot pass the depth down as an argument, because the signatures of the copy constructor and the operators are fixed. They count the levels they have descended into in a variable of type `std::uint8_t` that exists once per thread (see [`JSON_NO_THREAD_LOCAL`](https://json.nlohmann.me/api/macros/json_no_thread_local/index.md)). Only the levels that are descended into are counted, so the count never exceeds the limit, not even when user code (a copy constructor of a custom base class, say) copies a value while a copy is going on. A byte holds `255` at most, and the limit stays below that, so that the count cannot wrap around. (More levels would hardly be useful: `254` levels need up to 576 KiB of stack in an unoptimized build already, twice as much as the default.)
|
||||
|
||||
### Stack needed
|
||||
|
||||
The tables show the smallest stack that an operation needs, in KiB, at several limits, on a value that is nested more deeply than the limit (limit + 10 levels). Each cell shows the result for Clang (Apple clang 21) and for GCC 16, separated by a slash; both measured on macOS with arm64, compiling in C++20 mode. The operations run in a thread whose stack has the size given, and are not given any stack that they do not need: the value is built, and the result destroyed, outside of that thread. Stacks can only be set in steps of 16 KiB (the page size), so `16` means "16 KiB or less". A row stands for all operations listed; the table shows the largest value among them.
|
||||
|
||||
Unoptimized (`-O0`):
|
||||
|
||||
| Operation | limit 16 | limit 32 | limit 64 | limit 128 | limit 254 |
|
||||
| ----------------------------------------- | -------- | -------- | --------- | --------- | --------- |
|
||||
| `dump()` and `dump(indent)`, `operator<<` | 48 / 32 | 80 / 64 | 144 / 128 | 288 / 256 | 576 / 512 |
|
||||
| copy construction and assignment | 32 / 16 | 48 / 32 | 112 / 80 | 224 / 144 | 432 / 304 |
|
||||
| `==` | 16 / 16 | 16 / 16 | 16 / 16 | 48 / 32 | 96 / 48 |
|
||||
| `<=>` (C++20) | 16 / 16 | 16 / 16 | 32 / 32 | 64 / 64 | 144 / 128 |
|
||||
| `std::hash` | 16 / 16 | 16 / 16 | 32 / 32 | 80 / 64 | 160 / 128 |
|
||||
| `merge_patch`, `update(j, true)`, `patch` | 32 / 16 | 48 / 32 | 112 / 80 | 224 / 144 | 432 / 304 |
|
||||
| `diff` | 16 / 16 | 16 / 16 | 32 / 32 | 64 / 48 | 144 / 96 |
|
||||
| `merge_diff` | 16 / 16 | 48 / 32 | 80 / 48 | 176 / 112 | 352 / 224 |
|
||||
| `to_cbor`, `to_msgpack` | 16 / 16 | 32 / 16 | 64 / 32 | 112 / 80 | 224 / 160 |
|
||||
| `to_ubjson`, `to_bjdata` | 16 / 16 | 16 / 16 | 48 / 32 | 96 / 64 | 176 / 112 |
|
||||
| `to_bon8` | 16 / 16 | 16 / 16 | 16 / 16 | 32 / 16 | 64 / 48 |
|
||||
| conversion to another `basic_json` type | 32 / 16 | 64 / 32 | 112 / 80 | 224 / 144 | 448 / 304 |
|
||||
| destruction | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 | 32 / 32 |
|
||||
|
||||
Optimized (`-O2`):
|
||||
|
||||
| Operation | limit 16 | limit 32 | limit 64 | limit 128 | limit 254 |
|
||||
| ----------------------------------------- | -------- | -------- | -------- | --------- | --------- |
|
||||
| `dump()` and `dump(indent)`, `operator<<` | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 | 32 / 32 |
|
||||
| copy construction and assignment | 16 / 16 | 16 / 16 | 16 / 16 | 32 / 32 | 64 / 48 |
|
||||
| `==` | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 |
|
||||
| `<=>` (C++20) | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 | 48 / 16 |
|
||||
| `std::hash` | 16 / 16 | 16 / 16 | 16 / 16 | 32 / 48 | 80 / 80 |
|
||||
| `merge_patch`, `update(j, true)`, `patch` | 16 / 16 | 16 / 16 | 16 / 16 | 32 / 32 | 64 / 48 |
|
||||
| `diff` | 16 / 16 | 16 / 16 | 16 / 32 | 48 / 48 | 96 / 112 |
|
||||
| `merge_diff` | 16 / 16 | 16 / 16 | 16 / 16 | 48 / 32 | 96 / 64 |
|
||||
| `to_cbor`, `to_msgpack` | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 |
|
||||
| `to_ubjson`, `to_bjdata` | 16 / 16 | 16 / 16 | 16 / 16 | 32 / 32 | 64 / 64 |
|
||||
| `to_bon8` | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 32 | 32 / 64 |
|
||||
| conversion to another `basic_json` type | 16 / 16 | 16 / 16 | 16 / 16 | 32 / 48 | 64 / 96 |
|
||||
| destruction | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 | 16 / 16 |
|
||||
|
||||
With a limit of `0`, every operation in the tables ran in a 16 KiB stack at `-O0` (Clang and GCC), on a value nested 20,000 levels deep. The operations that do not depend on the macro (`flatten`, `unflatten`, `to_bson`) needed 16 KiB or less at every limit.
|
||||
|
||||
The rule of thumb is
|
||||
|
||||
> stack needed ≈ a few KiB + cost per level × limit
|
||||
|
||||
with a cost per level of up to 2.3 KiB (`dump` at `-O0` with Clang; 2.1 KiB with GCC), 1.7 KiB for copying and merging (1.3 KiB with GCC), and 0.1 to 0.5 KiB for most other operations at `-O0`; and 0.5 KiB or less at `-O2`. The numbers come from the difference between the limits `128` and `254` in the tables, so they are rough: other compilers, other targets (the frames of x86-64 code are about as large), other standard libraries, `JSON_DIAGNOSTICS`, and sanitizers change them. Measure with your own tool chain (see the example below) rather than relying on the tables. The stack that your own code and the operating system need comes on top of these numbers.
|
||||
|
||||
Which limit to choose, for the stack that you can spare for the library (the largest limit of those measured for which the slowest operation needs at most that much):
|
||||
|
||||
| Stack for the library | optimized (`-O2`) | unoptimized (`-O0`) |
|
||||
| ---------------------------------------------- | ----------------- | ------------------- |
|
||||
| 32 KiB | 64 | 0 |
|
||||
| 64 KiB | 128 | 16 |
|
||||
| 128 KiB (the default stack of threads on musl) | 254 | 32 |
|
||||
| 256 KiB | 254 | 64 |
|
||||
| 512 KiB | 254 | 128 |
|
||||
| 1 MiB or more | 254 | 254 |
|
||||
|
||||
### Speed
|
||||
|
||||
Operations are faster the more of a value they handle with plain recursion. The levels below the limit are handled with an explicit stack, which has to be kept on the heap and costs more per level. The macro therefore trades speed against stack.
|
||||
|
||||
The table shows the time of copying a value (including destroying the copy), of `==` on two equal values, of `dump`, and of `std::hash` for several limits, relative to the default of `128` (`1.00` means the same time; more is slower). It was measured with Clang 21 at `-O2` in C++17 mode on macOS with arm64, as the best of seven runs of each setting (two rounds, best of both). The documents are ordinary JSON files that are nested 7 (`canada.json`), 8 (`citm_catalog.json`), 10 (`twitter.json`), and 2 levels deep (`jeopardy.json`); the other values are one array or object with one member per level, nested 1,000 and 100,000 levels deep. The absolute time at the limit `128` is given in the third column. Differences of up to about 0.1 are noise: a different limit changes the layout of the compiled code, and timings of the same binary vary by about as much. The slow columns (limits 0 and 1) vary more: repeating `std::hash` on `canada.json` gave 1.27 to 1.30 for limit 0 and 1.4 to 1.9 for limit 1, so read the cells of those two columns as accurate to about 0.3.
|
||||
|
||||
| Value | Operation | limit 128 (absolute) | limit 0 | limit 1 | limit 16 | limit 254 |
|
||||
| ---------------------------- | ----------- | -------------------- | ------- | ------- | -------- | --------- |
|
||||
| `canada.json` (2.1 MB) | copy | 3.5 ms | 1.80 | 1.80 | 0.99 | 1.00 |
|
||||
| `canada.json` (2.1 MB) | `==` | 350.5 µs | 2.36 | 2.38 | 1.00 | 0.99 |
|
||||
| `canada.json` (2.1 MB) | `dump` | 2.4 ms | 1.11 | 1.11 | 1.00 | 1.00 |
|
||||
| `canada.json` (2.1 MB) | `std::hash` | 920.2 µs | 1.33 | 1.59 | 1.00 | 1.00 |
|
||||
| `citm_catalog.json` (1.7 MB) | copy | 1.8 ms | 1.38 | 1.36 | 1.00 | 0.99 |
|
||||
| `citm_catalog.json` (1.7 MB) | `==` | 275.5 µs | 1.31 | 1.31 | 0.99 | 1.00 |
|
||||
| `citm_catalog.json` (1.7 MB) | `dump` | 314.6 µs | 1.24 | 1.23 | 1.00 | 1.00 |
|
||||
| `citm_catalog.json` (1.7 MB) | `std::hash` | 309.1 µs | 1.77 | 1.42 | 1.06 | 1.05 |
|
||||
| `twitter.json` (0.6 MB) | copy | 865.7 µs | 1.45 | 1.47 | 1.01 | 1.00 |
|
||||
| `twitter.json` (0.6 MB) | `==` | 135.8 µs | 1.26 | 1.23 | 1.00 | 1.00 |
|
||||
| `twitter.json` (0.6 MB) | `dump` | 224.6 µs | 1.12 | 1.12 | 1.01 | 1.00 |
|
||||
| `twitter.json` (0.6 MB) | `std::hash` | 132.9 µs | 1.28 | 1.27 | 1.03 | 1.04 |
|
||||
| `jeopardy.json` (53 MB) | copy | 111.1 ms | 1.22 | 1.25 | 1.00 | 1.00 |
|
||||
| `jeopardy.json` (53 MB) | `==` | 23.5 ms | 1.29 | 1.53 | 1.07 | 1.00 |
|
||||
| `jeopardy.json` (53 MB) | `dump` | 33.2 ms | 1.14 | 1.34 | 1.03 | 1.01 |
|
||||
| `jeopardy.json` (53 MB) | `std::hash` | 19.9 ms | 1.17 | 1.52 | 1.05 | 1.00 |
|
||||
| arrays, 1,000 levels | copy | 69.9 µs | 0.95 | 0.98 | 0.92 | 0.99 |
|
||||
| arrays, 1,000 levels | `==` | 10.4 µs | 1.02 | 1.01 | 0.96 | 1.00 |
|
||||
| arrays, 1,000 levels | `dump` | 9.6 µs | 0.97 | 0.96 | 0.97 | 1.06 |
|
||||
| arrays, 1,000 levels | `std::hash` | 16.9 µs | 1.00 | 1.01 | 1.01 | 0.98 |
|
||||
| objects, 1,000 levels | copy | 77.1 µs | 0.98 | 0.97 | 0.97 | 1.03 |
|
||||
| objects, 1,000 levels | `==` | 12.0 µs | 0.96 | 0.95 | 0.95 | 1.07 |
|
||||
| objects, 1,000 levels | `dump` | 12.6 µs | 0.97 | 0.95 | 0.98 | 1.01 |
|
||||
| objects, 1,000 levels | `std::hash` | 17.3 µs | 0.99 | 1.01 | 0.98 | 1.00 |
|
||||
| arrays, 100,000 levels | copy | 6.4 ms | 1.00 | 1.00 | 1.00 | 1.00 |
|
||||
| arrays, 100,000 levels | `==` | 1.1 ms | 1.01 | 1.03 | 1.00 | 1.06 |
|
||||
| arrays, 100,000 levels | `dump` | 917.9 µs | 1.01 | 1.01 | 1.02 | 1.01 |
|
||||
| arrays, 100,000 levels | `std::hash` | 1.7 ms | 1.04 | 1.05 | 0.99 | 0.99 |
|
||||
| objects, 100,000 levels | copy | 7.5 ms | 0.99 | 1.02 | 1.01 | 0.99 |
|
||||
| objects, 100,000 levels | `==` | 1.3 ms | 1.02 | 1.09 | 1.08 | 0.96 |
|
||||
| objects, 100,000 levels | `dump` | 1.2 ms | 1.06 | 0.99 | 1.01 | 0.99 |
|
||||
| objects, 100,000 levels | `std::hash` | 1.8 ms | 1.00 | 1.00 | 1.00 | 1.00 |
|
||||
|
||||
The results are as follows.
|
||||
|
||||
- A limit of `16` or more does not change the speed of ordinary documents (differences are within noise), because they are not nested more deeply than that anyway. A document nested more deeply than the limit is walked partly with the explicit stack.
|
||||
- A limit of `0` or `1` makes the operations on ordinary documents 1.1 to 2.4 times as slow, because even their first levels are handled with the explicit stack. The slowdown is largest for `==` on a document of many small containers (`canada.json`: 2.4 times) and for copying (up to 1.8 times).
|
||||
- For values that are nested far more deeply than any limit (1,000 and 100,000 levels deep), the limit makes no measurable difference: almost all of the levels are handled with the explicit stack for every setting. Raising the limit gains nothing for them, and lowering it costs nothing.
|
||||
|
||||
Other macros
|
||||
|
||||
- With [`JSON_NO_THREAD_LOCAL`](https://json.nlohmann.me/api/macros/json_no_thread_local/index.md) defined (or for Clang targeting MinGW, where the library defines it by itself), copying and comparing never descend, so for them the limit does not matter. The other operations still recurse as many levels as the limit says. The range of the limit is the same.
|
||||
- The macro is not part of the [ABI tag](https://json.nlohmann.me/features/namespace/index.md), as `JSON_NO_THREAD_LOCAL` is not, and it is not undefined at the end of `json.hpp`.
|
||||
|
||||
Use the same value in every translation unit
|
||||
|
||||
All translation units of a program that include the library must define the same value. Otherwise, the program violates the One Definition Rule: the function `nlohmann::detail::recursion_depth_limit()` and all the functions that use it are defined differently in different translation units. Which limit a call uses then depends on which functions the compiler inlined (an inlined copy uses the value of its own translation unit) and which out-of-line copy of each remaining function the linker kept, which is not specified. A function compiled with one value can call a function compiled with another, so a single operation can mix both limits.
|
||||
|
||||
Mixing values cannot corrupt the byte per thread that counts the levels of copying and comparing: each limit is at most `254`, and all of them stop counting at their own limit, so the count never exceeds `254`, whichever translation unit's definition runs. The counter exists once per thread and `basic_json` specialization, and is shared by all translation units. Nor can mixing values change any result, as no result depends on the limit. What changes is how much stack is used and how fast the operations are. Nevertheless, avoid it: the program has undefined behavior as far as the C++ standard is concerned.
|
||||
|
||||
## Examples
|
||||
|
||||
Example: lower the limit
|
||||
|
||||
The example nests an array 5,000 levels deep. With the limit set to 16, the library recurses over the first 16 levels and over the rest uses an explicit stack. The results are those of the default limit.
|
||||
|
||||
```
|
||||
#include <functional>
|
||||
#include <iostream>
|
||||
#include <utility>
|
||||
|
||||
// walk over at most 16 nesting levels on the call stack, and over the rest with an explicit stack
|
||||
#define JSON_RECURSION_DEPTH_LIMIT 16
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// an array nested 5,000 levels deep, built without recursion
|
||||
json j = 1;
|
||||
for (int i = 0; i < 5000; ++i)
|
||||
{
|
||||
json outer = json::array();
|
||||
outer.push_back(std::move(j));
|
||||
j = std::move(outer);
|
||||
}
|
||||
|
||||
// the results are those of any other limit
|
||||
const json copy = j;
|
||||
std::cout << std::boolalpha;
|
||||
std::cout << "limit: " << JSON_RECURSION_DEPTH_LIMIT << '\n';
|
||||
std::cout << "copy equals original: " << (copy == j) << '\n';
|
||||
std::cout << "length of dump(): " << j.dump().size() << '\n';
|
||||
std::cout << "same hash: " << (std::hash<json> {}(copy) == std::hash<json> {}(j)) << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
limit: 16
|
||||
copy equals original: true
|
||||
length of dump(): 10001
|
||||
same hash: true
|
||||
```
|
||||
|
||||
Example: find out how much stack an operation needs
|
||||
|
||||
The program runs `dump()` on a value nested `depth` levels deep in a thread with a stack of `kib` KiB. Compile it with the options and the limit that you use, e.g. `-DJSON_RECURSION_DEPTH_LIMIT=64`, run it with `depth` set to the limit plus 10 and decreasing values of `kib` (the stack size must be a multiple of the page size, often 4 or 16 KiB), and note the smallest stack with which it still finishes. That is how the tables above were measured.
|
||||
|
||||
```
|
||||
#include <cstdlib>
|
||||
#include <iostream>
|
||||
#include <string>
|
||||
#include <utility>
|
||||
#include <pthread.h>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
static nlohmann::json value;
|
||||
|
||||
static void* run(void*)
|
||||
{
|
||||
std::cout << "dump() ok, " << value.dump().size() << " bytes\n";
|
||||
return nullptr;
|
||||
}
|
||||
|
||||
int main(int argc, char** argv)
|
||||
{
|
||||
const int depth = std::atoi(argv[1]);
|
||||
const std::size_t kib = static_cast<std::size_t>(std::atoi(argv[2]));
|
||||
|
||||
// built on the main thread, without recursion
|
||||
value = 1;
|
||||
for (int i = 0; i < depth; ++i)
|
||||
{
|
||||
nlohmann::json outer = nlohmann::json::array();
|
||||
outer.push_back(std::move(value));
|
||||
value = std::move(outer);
|
||||
}
|
||||
|
||||
pthread_attr_t attr;
|
||||
pthread_attr_init(&attr);
|
||||
pthread_attr_setstacksize(&attr, kib * 1024);
|
||||
pthread_t thread;
|
||||
pthread_create(&thread, &attr, run, nullptr);
|
||||
pthread_join(thread, nullptr);
|
||||
}
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [Nesting depth](https://json.nlohmann.me/features/parsing/untrusted_input/#nesting-depth) - how the library handles deeply nested values
|
||||
- [`JSON_NO_THREAD_LOCAL`](https://json.nlohmann.me/api/macros/json_no_thread_local/index.md) - switch off the use of `thread_local` storage
|
||||
- [Supported Macros](https://json.nlohmann.me/features/macros/index.md) - guide to all supported macros
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0 unreleased.
|
||||
Reference in new issue
Block a user