docs/advanced A document about deadlock potential with C++ statics (#5394)

* [docs/advanced] A document about deadlock potential with C++ statics

* [docs/advanced] Refer to deadlock.md from misc.rst

* [docs/advanced] Fix tables in deadlock.md

* Use :ref:`deadlock-reference-label`

* Revert "Use :ref:`deadlock-reference-label`"

This reverts commit e5734d275fa0d38ad4a58a595797353813e65df1.

* Add simple references to docs/advanced/deadlock.md filename. (Maybe someone can work on clickable links later.)

---------

Co-authored-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

docs/advanced/misc.rst

@@ -62,7 +62,11 @@ will acquire the GIL before calling the Python callback. Similarly, the
 back into Python.
 back into Python.
 
 
 When writing C++ code that is called from other C++ code, if that code accesses
 When writing C++ code that is called from other C++ code, if that code accesses
-Python state, it must explicitly acquire and release the GIL.
+Python state, it must explicitly acquire and release the GIL. A separate
+document on deadlocks [#f8]_ elaborates on a particularly subtle interaction
+with C++'s block-scope static variable initializer guard mutexes.
+
+.. [#f8] See docs/advanced/deadlock.md
 
 
 The classes :class:`gil_scoped_release` and :class:`gil_scoped_acquire` can be
 The classes :class:`gil_scoped_release` and :class:`gil_scoped_acquire` can be
 used to acquire and release the global interpreter lock in the body of a C++
 used to acquire and release the global interpreter lock in the body of a C++
@@ -142,6 +146,9 @@ following checklist.
   destructors can sometimes get invoked in weird and unexpected circumstances as a result
   destructors can sometimes get invoked in weird and unexpected circumstances as a result
   of exceptions.
   of exceptions.
 
 
+- C++ static block-scope variable initialization that calls back into Python can
+  cause deadlocks; see [#f8]_ for a detailed discussion.
+
 - You should try running your code in a debug build. That will enable additional assertions
 - You should try running your code in a debug build. That will enable additional assertions
   within pybind11 that will throw exceptions on certain GIL handling errors
   within pybind11 that will throw exceptions on certain GIL handling errors
   (reference counting operations).
   (reference counting operations).

include/pybind11/gil_safe_call_once.h

@@ -46,6 +46,8 @@ PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 // get processed only when it is the main thread's turn again and it is running
 // get processed only when it is the main thread's turn again and it is running
 // normal Python code. However, this will be unnoticeable for quick call-once
 // normal Python code. However, this will be unnoticeable for quick call-once
 // functions, which is usually the case.
 // functions, which is usually the case.
+//
+// For in-depth background, see docs/advanced/deadlock.md
 template <typename T>
 template <typename T>
 class gil_safe_call_once_and_store {
 class gil_safe_call_once_and_store {
 public:
 public: