Merge pull request #4489 from randombit/jack/update-threading-docs

Update threading related docs

configure.py

@@ -3320,6 +3320,9 @@ def validate_options(options, info_os, info_cc, available_module_policies):
         if options.msvc_runtime not in ['MT', 'MD', 'MTd', 'MDd']:
             logging.warning("MSVC runtime option '%s' not known", options.msvc_runtime)
 
+    if 'threads' in options.without_os_features:
+        logging.warning('Disabling thread support will cause data races if threads are used by the application')
+
 def run_compiler_preproc(options, ccinfo, source_file, default_return, extra_flags=None):
     if extra_flags is None:
         extra_flags = []

doc/building.rst

@@ -155,6 +155,12 @@ completely supported by the build system. To extend the example, we must tell
    threading or mutexes in the C++ standard library. You can work around
    this by disabling thread support using ``--without-os-feature=threads``
 
+.. warning::
+
+   Using ``--without-os-feature=threads`` disables *all* support for threads,
+   including any locking of internal data structures. In this configuration,
+   calling into the library from multiple threads will cause data races.
+
 You can also specify the alternate tools by setting the `CXX` and `AR`
 environment variables (instead of the `--cc-bin` and `--ar-command` options), as
 is commonly done with autoconf builds.
@@ -720,6 +726,16 @@ Specify an OS feature to enable. See ``src/build-data/os`` and
 
 Specify an OS feature to disable.
 
+.. warning::
+
+   One operating system feature that can be disabled using this option is
+   ``threads``. Be warned that doing so will disable all support for threads
+   including any locking of internal data structures. Calling the library from
+   multiple threads in such a configuration will lead to data races.
+
+   This is intended for use only on targets which truly do not support threads,
+   for example certain baremetal configurations.
+
 ``--enable-experimental-features``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

src/build-data/cc/clang.txt

@@ -29,6 +29,7 @@ undefined -> "-fsanitize=undefined -fno-sanitize-recover=undefined"
 coverage  -> "-fsanitize=fuzzer-no-link"
 memory    -> "-fsanitize=memory"
 fuzzer    -> "-fsanitize=fuzzer"
+thread    -> "-fsanitize=thread"
 
 iterator  -> "-D_LIBCPP_DEBUG=1 -D_GLIBCXX_DEBUG"
 </sanitizers>