From dbf848aff7c37ef8798bc9459a86193e28b1032f Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Thu, 18 Jul 2024 08:26:45 +0200 Subject: [PATCH] docs: extend `PYBIND11_MODULE` documentation, mention `mod_gil_not_used` (#5250) This follows up on PR 5148, which introduced support for free-threaded CPython. --- include/pybind11/detail/common.h | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/include/pybind11/detail/common.h b/include/pybind11/detail/common.h index fc66e6f75..9418334ca 100644 --- a/include/pybind11/detail/common.h +++ b/include/pybind11/detail/common.h @@ -462,6 +462,22 @@ PYBIND11_WARNING_POP return "Hello, World!"; }); } + + The third macro argument is optional (available since 2.13.0), and can be used to + mark the extension module as safe to run without the GIL under a free-threaded CPython + interpreter. Passing this argument has no effect on other interpreters. + + .. code-block:: cpp + + PYBIND11_MODULE(example, m, py::mod_gil_not_used()) { + m.doc() = "pybind11 example module safe to run without the GIL"; + + // Add bindings here + m.def("foo", []() { + return "Hello, Free-threaded World!"; + }); + } + \endrst */ #define PYBIND11_MODULE(name, variable, ...) \ static ::pybind11::module_::module_def PYBIND11_CONCAT(pybind11_module_def_, name) \