deploy: f3768d6868

api/macros/index.md

@@ -31,6 +31,7 @@ Some aspects of the library can be configured by defining preprocessor macros **
 - [**JSON_HAS_STD_FORMAT**](https://json.nlohmann.me/api/macros/json_has_std_format/index.md) - control `std::format`/`std::formatter` support
 - [**JSON_HAS_THREE_WAY_COMPARISON**](https://json.nlohmann.me/api/macros/json_has_three_way_comparison/index.md) - control 3-way comparison support
 - [**JSON_NO_IO**](https://json.nlohmann.me/api/macros/json_no_io/index.md) - switch off functions relying on certain C++ I/O headers
+- [**JSON_NO_THREAD_LOCAL**](https://json.nlohmann.me/api/macros/json_no_thread_local/index.md) - switch off the use of `thread_local` storage
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](https://json.nlohmann.me/api/macros/json_skip_unsupported_compiler_check/index.md) - do not warn about unsupported compilers
 - [**JSON_USE_GLOBAL_UDLS**](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md) - place user-defined string literals (UDLs) into the global namespace
 - [**JSON_USE_SIMDUTF**](https://json.nlohmann.me/api/macros/json_use_simdutf/index.md) - use the simdutf library to accelerate UTF-8 validation

api/macros/json_no_thread_local.md

@@ -0,0 +1,47 @@
+# JSON_NO_THREAD_LOCAL
+
+```cpp
+#define JSON_NO_THREAD_LOCAL
+```
+
+When defined, the library does not use `#!cpp thread_local` storage. This is relevant for the few environments whose
+toolchain does not support it.
+
+The copy constructor copies the first levels of a value by copying the containers, which copy their elements, and
+completes whatever is nested deeper than that without the call stack, so that copying a value cannot exhaust the stack
+however deeply it is nested. It counts the levels it has descended into in a `#!cpp thread_local` variable, as a counter
+shared between threads would be raced.
+
+Without that counter, no descent can be bounded safely, so objects and arrays are copied without the call stack right
+away. Copying keeps working exactly as it does otherwise - the same values come out, and deeply nested values are copied
+just as safely - but copying is slower, because the containers no longer copy themselves. Copying the benchmark
+documents takes 9% (`canada.json`) to 34% (`twitter.json`) longer; values built mostly from objects are affected the
+most.
+
+## Default definition
+
+By default, `#!cpp JSON_NO_THREAD_LOCAL` is not defined.
+
+```cpp
+#undef JSON_NO_THREAD_LOCAL
+```
+
+The library defines it by itself for Clang targeting MinGW, which does not survive the `#!cpp thread_local` storage:
+copying a value segfaults there, with both old and current Clang versions, while GCC targeting MinGW is unaffected.
+
+## Examples
+
+??? example
+
+    The code below forces the library not to use `#!cpp thread_local` storage.
+
+    ```cpp
+    #define JSON_NO_THREAD_LOCAL 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
+## Version history
+
+- Added in version 3.12.1.

api/macros/json_no_thread_local/index.md

@@ -0,0 +1,38 @@
+# JSON_NO_THREAD_LOCAL
+
+```
+#define JSON_NO_THREAD_LOCAL
+```
+
+When defined, the library does not use `thread_local` storage. This is relevant for the few environments whose toolchain does not support it.
+
+The copy constructor copies the first levels of a value by copying the containers, which copy their elements, and completes whatever is nested deeper than that without the call stack, so that copying a value cannot exhaust the stack however deeply it is nested. It counts the levels it has descended into in a `thread_local` variable, as a counter shared between threads would be raced.
+
+Without that counter, no descent can be bounded safely, so objects and arrays are copied without the call stack right away. Copying keeps working exactly as it does otherwise - the same values come out, and deeply nested values are copied just as safely - but copying is slower, because the containers no longer copy themselves. Copying the benchmark documents takes 9% (`canada.json`) to 34% (`twitter.json`) longer; values built mostly from objects are affected the most.
+
+## Default definition
+
+By default, `JSON_NO_THREAD_LOCAL` is not defined.
+
+```
+#undef JSON_NO_THREAD_LOCAL
+```
+
+The library defines it by itself for Clang targeting MinGW, which does not survive the `thread_local` storage: copying a value segfaults there, with both old and current Clang versions, while GCC targeting MinGW is unaffected.
+
+## Examples
+
+Example
+
+The code below forces the library not to use `thread_local` storage.
+
+```
+#define JSON_NO_THREAD_LOCAL 1
+#include <nlohmann/json.hpp>
+
+...
+```
+
+## Version history
+
+- Added in version 3.12.1.