What does mod_gil_not_used do?

[sambaPython24]

Hey, thank you for the work that you are putting into this package.

When I was using the introductary examples, I saw that there was the element

mod_gil_not_used in 
PYBIND11_MODULE(example, m, py::mod_gil_not_used()) {

Why should I use this option and what implications does it have?

[TrondMelen]

Pybind11 and Global Interpreter Lock (GIL) is documented here.

Summary by Copilot:

The py::mod_gil_not_used tag is an optional third argument to the PYBIND11_MODULE macro used to inform pybind11 that the extension module is thread-safe and can be used in free-threaded builds of Python (versions 3.13+ where the Global Interpreter Lock, or GIL, is removed).

Key Details:

Purpose: The primary purpose is to signal that the C++ code within the module handles its own threading concerns and does not rely on the Python GIL for thread safety.

Compatibility: Modules using this tag will still be compatible with standard, non-free-threaded Python builds (where the GIL is present).

Requirement: To actually run without the GIL, the module must be built specifically against a Python free-threading branch (3.13 or later).
Developer

Responsibility: By using py::mod_gil_not_used, the developer makes a "promise that your code is thread safe".