include/pybind11/gil.h

0001 /*
0002     pybind11/gil.h: RAII helpers for managing the GIL
0003
0004     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
0005
0006     All rights reserved. Use of this source code is governed by a
0007     BSD-style license that can be found in the LICENSE file.
0008 */
0009
0010 #pragma once
0011
0012 #if defined(PYBIND11_SIMPLE_GIL_MANAGEMENT)
0013
0014 #    include "detail/common.h"
0015 #    include "gil_simple.h"
0016
0017 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
0018
0019 using gil_scoped_acquire = gil_scoped_acquire_simple;
0020 using gil_scoped_release = gil_scoped_release_simple;
0021
0022 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
0023
0024 #else
0025
0026 #    include "detail/common.h"
0027 #    include "detail/internals.h"
0028
0029 #    include <cassert>
0030
0031 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
0032
0033 PYBIND11_NAMESPACE_BEGIN(detail)
0034
0035 PYBIND11_WARNING_PUSH
0036 PYBIND11_WARNING_DISABLE_GCC("-Wredundant-decls")
0037
0038 // forward declarations
0039 PyThreadState *get_thread_state_unchecked();
0040
0041 PYBIND11_WARNING_POP
0042
0043 PYBIND11_NAMESPACE_END(detail)
0044
0045 /* The functions below essentially reproduce the PyGILState_* API using a RAII
0046  * pattern, but there are a few important differences:
0047  *
0048  * 1. When acquiring the GIL from an non-main thread during the finalization
0049  *    phase, the GILState API blindly terminates the calling thread, which
0050  *    is often not what is wanted. This API does not do this.
0051  *
0052  * 2. The gil_scoped_release function can optionally cut the relationship
0053  *    of a PyThreadState and its associated thread, which allows moving it to
0054  *    another thread (this is a fairly rare/advanced use case).
0055  *
0056  * 3. The reference count of an acquired thread state can be controlled. This
0057  *    can be handy to prevent cases where callbacks issued from an external
0058  *    thread would otherwise constantly construct and destroy thread state data
0059  *    structures.
0060  *
0061  * See the Python bindings of NanoGUI (http://github.com/wjakob/nanogui) for an
0062  * example which uses features 2 and 3 to migrate the Python thread of
0063  * execution to another thread (to run the event loop on the original thread,
0064  * in this case).
0065  */
0066
0067 class gil_scoped_acquire {
0068 public:
0069     PYBIND11_NOINLINE gil_scoped_acquire() {
0070         auto &internals = detail::get_internals();
0071         tstate = internals.tstate.get();
0072
0073         if (!tstate) {
0074             /* Check if the GIL was acquired using the PyGILState_* API instead (e.g. if
0075                calling from a Python thread). Since we use a different key, this ensures
0076                we don't create a new thread state and deadlock in PyEval_AcquireThread
0077                below. Note we don't save this state with internals.tstate, since we don't
0078                create it we would fail to clear it (its reference count should be > 0). */
0079             tstate = PyGILState_GetThisThreadState();
0080         }
0081
0082         if (!tstate) {
0083             tstate = PyThreadState_New(internals.istate);
0084 #    if defined(PYBIND11_DETAILED_ERROR_MESSAGES)
0085             if (!tstate) {
0086                 pybind11_fail("scoped_acquire: could not create thread state!");
0087             }
0088 #    endif
0089             tstate->gilstate_counter = 0;
0090             internals.tstate = tstate;
0091         } else {
0092             release = detail::get_thread_state_unchecked() != tstate;
0093         }
0094
0095         if (release) {
0096             PyEval_AcquireThread(tstate);
0097         }
0098
0099         inc_ref();
0100     }
0101
0102     gil_scoped_acquire(const gil_scoped_acquire &) = delete;
0103     gil_scoped_acquire &operator=(const gil_scoped_acquire &) = delete;
0104
0105     void inc_ref() { ++tstate->gilstate_counter; }
0106
0107     PYBIND11_NOINLINE void dec_ref() {
0108         --tstate->gilstate_counter;
0109 #    if defined(PYBIND11_DETAILED_ERROR_MESSAGES)
0110         if (detail::get_thread_state_unchecked() != tstate) {
0111             pybind11_fail("scoped_acquire::dec_ref(): thread state must be current!");
0112         }
0113         if (tstate->gilstate_counter < 0) {
0114             pybind11_fail("scoped_acquire::dec_ref(): reference count underflow!");
0115         }
0116 #    endif
0117         if (tstate->gilstate_counter == 0) {
0118 #    if defined(PYBIND11_DETAILED_ERROR_MESSAGES)
0119             if (!release) {
0120                 pybind11_fail("scoped_acquire::dec_ref(): internal error!");
0121             }
0122 #    endif
0123             // Make sure that PyThreadState_Clear is not recursively called by finalizers.
0124             // See issue #5827
0125             ++tstate->gilstate_counter;
0126             PyThreadState_Clear(tstate);
0127             --tstate->gilstate_counter;
0128             if (active) {
0129                 PyThreadState_DeleteCurrent();
0130             }
0131             detail::get_internals().tstate.reset();
0132             release = false;
0133         }
0134     }
0135
0136     /// This method will disable the PyThreadState_DeleteCurrent call and the
0137     /// GIL won't be released. This method should be used if the interpreter
0138     /// could be shutting down when this is called, as thread deletion is not
0139     /// allowed during shutdown. Check _Py_IsFinalizing() on Python 3.7+, and
0140     /// protect subsequent code.
0141     PYBIND11_NOINLINE void disarm() { active = false; }
0142
0143     PYBIND11_NOINLINE ~gil_scoped_acquire() {
0144         dec_ref();
0145         if (release) {
0146             PyEval_SaveThread();
0147         }
0148     }
0149
0150 private:
0151     PyThreadState *tstate = nullptr;
0152     bool release = true;
0153     bool active = true;
0154 };
0155
0156 class gil_scoped_release {
0157 public:
0158     // PRECONDITION: The GIL must be held when this constructor is called.
0159     explicit gil_scoped_release(bool disassoc = false) : disassoc(disassoc) {
0160         assert(PyGILState_Check());
0161         // `get_internals()` must be called here unconditionally in order to initialize
0162         // `internals.tstate` for subsequent `gil_scoped_acquire` calls. Otherwise, an
0163         // initialization race could occur as multiple threads try `gil_scoped_acquire`.
0164         auto &internals = detail::get_internals();
0165         // NOLINTNEXTLINE(cppcoreguidelines-prefer-member-initializer)
0166         tstate = PyEval_SaveThread();
0167         if (disassoc) {
0168             internals.tstate.reset();
0169         }
0170     }
0171
0172     gil_scoped_release(const gil_scoped_release &) = delete;
0173     gil_scoped_release &operator=(const gil_scoped_release &) = delete;
0174
0175     /// This method will disable the PyThreadState_DeleteCurrent call and the
0176     /// GIL won't be acquired. This method should be used if the interpreter
0177     /// could be shutting down when this is called, as thread deletion is not
0178     /// allowed during shutdown. Check _Py_IsFinalizing() on Python 3.7+, and
0179     /// protect subsequent code.
0180     PYBIND11_NOINLINE void disarm() { active = false; }
0181
0182     ~gil_scoped_release() {
0183         if (!tstate) {
0184             return;
0185         }
0186         // `PyEval_RestoreThread()` should not be called if runtime is finalizing
0187         if (active) {
0188             PyEval_RestoreThread(tstate);
0189         }
0190         if (disassoc) {
0191             detail::get_internals().tstate = tstate;
0192         }
0193     }
0194
0195 private:
0196     PyThreadState *tstate;
0197     bool disassoc;
0198     bool active = true;
0199 };
0200
0201 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
0202
0203 #endif // !PYBIND11_SIMPLE_GIL_MANAGEMENT