pybind11/docs
Ralf W. Grosse-Kunstleve 0e2c3e5db4
Add pybind11/gil_safe_call_once.h (to fix deadlocks in pybind11/numpy.h) (#4877)
* LazyInitializeAtLeastOnceDestroyNever v1

* Go back to using `union` as originally suggested by jbms@. The trick (also suggested by jbms@) is to add empty ctor + dtor.

* Revert "Go back to using `union` as originally suggested by jbms@. The trick (also suggested by jbms@) is to add empty ctor + dtor."

This reverts commit e7b8c4f0fc.

* Remove `#include <stdalign.h>`

* `include\pybind11/numpy.h(24,10): fatal error C1083: Cannot open include file: 'stdalign.h': No such file or directory`

* @tkoeppe wrote: this is a C interop header (and we're not writing C)

* Suppress gcc 4.8.5 (CentOS 7) warning.

```
include/pybind11/eigen/../numpy.h:63:53: error: dereferencing type-punned pointer will break strict-aliasing rules [-Werror=strict-aliasing]
         return *reinterpret_cast<T *>(value_storage_);
                                                     ^
```

* Replace comments:

Document PRECONDITION.

Adopt comment suggested by @tkoeppe: https://github.com/pybind/pybind11/pull/4877#discussion_r1350356093

* Adopt suggestion by @tkoeppe:

* https://github.com/pybind/pybind11/pull/4877#issuecomment-1752969127

* https://godbolt.org/z/Wa79nKz6e

* Add `PYBIND11_CONSTINIT`, but it does not work for the current use cases:

```
g++ -o pybind11/tests/test_numpy_array.os -c -std=c++20 -fPIC -fvisibility=hidden -O0 -g -Wall -Wextra -Wconversion -Wcast-qual -Wdeprecated -Wundef -Wnon-virtual-dtor -Wunused-result -Werror -isystem /usr/include/python3.11 -isystem /usr/include/eigen3 -DPYBIND11_STRICT_ASSERTS_CLASS_HOLDER_VS_TYPE_CASTER_MIX -DPYBIND11_ENABLE_TYPE_CASTER_ODR_GUARD_IF_AVAILABLE -DPYBIND11_TEST_BOOST -Ipybind11/include -I/usr/local/google/home/rwgk/forked/pybind11/include -I/usr/local/google/home/rwgk/clone/pybind11/include /usr/local/google/home/rwgk/forked/pybind11/tests/test_numpy_array.cpp
```

```
In file included from /usr/local/google/home/rwgk/forked/pybind11/tests/test_numpy_array.cpp:10:
/usr/local/google/home/rwgk/forked/pybind11/include/pybind11/numpy.h: In static member function ‘static pybind11::detail::npy_api& pybind11::detail::npy_api::get()’:
/usr/local/google/home/rwgk/forked/pybind11/include/pybind11/numpy.h:258:82: error: ‘constinit’ variable ‘api_init’ does not have a constant initializer
  258 |         PYBIND11_CONSTINIT static LazyInitializeAtLeastOnceDestroyNever<npy_api> api_init;
      |                                                                                  ^~~~~~~~
```

```
In file included from /usr/local/google/home/rwgk/forked/pybind11/tests/test_numpy_array.cpp:10:
/usr/local/google/home/rwgk/forked/pybind11/include/pybind11/numpy.h: In static member function ‘static pybind11::object& pybind11::dtype::_dtype_from_pep3118()’:
/usr/local/google/home/rwgk/forked/pybind11/include/pybind11/numpy.h:697:13: error: ‘constinit’ variable ‘imported_obj’ does not have a constant initializer
  697 |             imported_obj;
      |             ^~~~~~~~~~~~
```

* Revert "Add `PYBIND11_CONSTINIT`, but it does not work for the current use cases:"

This reverts commit f07b28bda9.

* Reapply "Add `PYBIND11_CONSTINIT`, but it does not work for the current use cases:"

This reverts commit 36be645758.

* Add Default Member Initializer on `value_storage_` as suggested by @tkoeppe:

https://github.com/pybind/pybind11/pull/4877#issuecomment-1753201342

This fixes the errors reported under commit f07b28bda9.

* Fix copy-paste-missed-a-change mishap in commit 88cec1152a.

* Semi-paranoid placement new (based on https://github.com/pybind/pybind11/pull/4877#discussion_r1350573114).

* Move PYBIND11_CONSTINIT to detail/common.h

* Move code to the right places, rename new class and some variables.

* Fix oversight: update tests/extra_python_package/test_files.py

* Get the name right first.

* Use `std::call_once`, `std::atomic`, following a pattern developed by @tkoeppe

* Make the API more self-documenting (and possibly more easily reusable).

* google-clang-tidy IWYU fixes

* Rewrite comment as suggested by @tkoeppe

* Update test_exceptions.cpp and exceptions.rst

* Fix oversight in previous commit: add `PYBIND11_CONSTINIT`

* Make `get_stored()` non-const for simplicity.

As suggested by @tkoeppe: not seeing any reasonable use in which `get_stored` has to be const.

* Add comment regarding `KeyboardInterrupt` behavior, based heavily on information provided by @jbms.

* Add `assert(PyGILState_Check())` in `gil_scoped_release` ctor (simple & non-simple implementation) as suggested by @EthanSteinberg.

* Fix oversight in previous commit (missing include cassert).

* Remove use of std::atomic, leaving comments with rationale, why it is not needed.

* Rewrite comment re `std:optional` based on deeper reflection (aka 2nd thoughts).

* Additional comment with the conclusion of a discussion under PR #4877.

* https://github.com/pybind/pybind11/pull/4877#issuecomment-1757363179

* Small comment changes suggested by @tkoeppe.
2023-10-11 21:05:31 -07:00
..
_static/css docs: use Furo (#3109) 2022-07-13 10:13:35 -05:00
advanced Add pybind11/gil_safe_call_once.h (to fix deadlocks in pybind11/numpy.h) (#4877) 2023-10-11 21:05:31 -07:00
cmake fix: find_import didn't work properly for classic tools (#2550) 2020-10-05 15:31:00 -04:00
Doxyfile Python 2 removal part 1: tests (C++ code is intentionally ~untouched) (#3688) 2022-02-10 18:28:08 -08:00
Makefile took a stab at some documentation 2015-10-13 03:16:44 +02:00
basics.rst Dropping MSVC 2015 (#3722) 2022-02-14 11:36:22 -08:00
benchmark.py chore(deps): update pre-commit hooks (#4838) 2023-09-06 06:04:27 -07:00
benchmark.rst ci: GHA basic format & pre-commit (#2309) 2020-07-20 13:35:21 -04:00
changelog.rst Copy v2.11.1 changelog section as released. (#4755) 2023-07-17 12:07:42 -07:00
classes.rst Warning on comparing wrapper enums with is (#4732) 2023-07-12 08:56:40 -07:00
compiling.rst docs: Remove upper bound on pybind11 in example pyproject.toml for setuptools (#4774) 2023-08-03 22:14:23 -07:00
conf.py chore: move to Ruff and add rules (#4483) 2023-02-22 06:18:55 -08:00
faq.rst fix: support CMake 3.27, drop 3.4 (#4719) 2023-07-12 13:10:24 -05:00
index.rst fix: chapters in PDF again (#2606) 2020-10-18 14:31:28 -04:00
installing.rst docs: add a note about compiling the example (#2737) 2020-12-24 09:51:36 -05:00
limitations.rst docs: reduce visibility of 3.9.0 warning (#3105) 2021-07-15 15:01:13 -04:00
pybind11-logo.png docs: use Furo (#3109) 2022-07-13 10:13:35 -05:00
pybind11_vs_boost_python1.png documentation improvements 2016-04-28 15:32:07 +02:00
pybind11_vs_boost_python1.svg Much more efficient generation of function signatures, updated docs 2016-01-17 22:31:15 +01:00
pybind11_vs_boost_python2.png documentation improvements 2016-04-28 15:32:07 +02:00
pybind11_vs_boost_python2.svg Much more efficient generation of function signatures, updated docs 2016-01-17 22:31:15 +01:00
reference.rst feat: reapply fixed version of #3271 (#3293) 2021-09-23 15:06:07 -04:00
release.rst Add command to check for vX.Y.Z tag vs pybind11/_version.py consistency. (#4757) 2023-07-23 11:10:10 -07:00
requirements.txt docs: use Furo (#3109) 2022-07-13 10:13:35 -05:00
upgrade.rst fix: support CMake 3.27, drop 3.4 (#4719) 2023-07-12 13:10:24 -05:00