python_packaging/src/external/pybind/include/pybind11/embed.h

   1 /*
   2     pybind11/embed.h: Support for embedding the interpreter
   3
   4     Copyright (c) 2017 Wenzel Jakob <wenzel.jakob@epfl.ch>
   5
   6     All rights reserved. Use of this source code is governed by a
   7     BSD-style license that can be found in the LICENSE file.
   8 */
   9
  10 #pragma once
  11
  12 #include "pybind11.h"
  13 #include "eval.h"
  14
  15 #if defined(PYPY_VERSION)
  16 #  error Embedding the interpreter is not supported with PyPy
  17 #endif
  18
  19 #if PY_MAJOR_VERSION >= 3
  20 #  define PYBIND11_EMBEDDED_MODULE_IMPL(name)            \
  21       extern "C" PyObject *pybind11_init_impl_##name();  \
  22       extern "C" PyObject *pybind11_init_impl_##name() { \
  23           return pybind11_init_wrapper_##name();         \
  24       }
  25 #else
  26 #  define PYBIND11_EMBEDDED_MODULE_IMPL(name)            \
  27       extern "C" void pybind11_init_impl_##name();       \
  28       extern "C" void pybind11_init_impl_##name() {      \
  29           pybind11_init_wrapper_##name();                \
  30       }
  31 #endif
  32
  33 /** \rst
  34     Add a new module to the table of builtins for the interpreter. Must be
  35     defined in global scope. The first macro parameter is the name of the
  36     module (without quotes). The second parameter is the variable which will
  37     be used as the interface to add functions and classes to the module.
  38
  39     .. code-block:: cpp
  40
  41         PYBIND11_EMBEDDED_MODULE(example, m) {
  42             // ... initialize functions and classes here
  43             m.def("foo", []() {
  44                 return "Hello, World!";
  45             });
  46         }
  47  \endrst */
  48 #define PYBIND11_EMBEDDED_MODULE(name, variable)                              \
  49     static void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &);    \
  50     static PyObject PYBIND11_CONCAT(*pybind11_init_wrapper_, name)() {        \
  51         auto m = pybind11::module(PYBIND11_TOSTRING(name));                   \
  52         try {                                                                 \
  53             PYBIND11_CONCAT(pybind11_init_, name)(m);                         \
  54             return m.ptr();                                                   \
  55         } catch (pybind11::error_already_set &e) {                            \
  56             PyErr_SetString(PyExc_ImportError, e.what());                     \
  57             return nullptr;                                                   \
  58         } catch (const std::exception &e) {                                   \
  59             PyErr_SetString(PyExc_ImportError, e.what());                     \
  60             return nullptr;                                                   \
  61         }                                                                     \
  62     }                                                                         \
  63     PYBIND11_EMBEDDED_MODULE_IMPL(name)                                       \
  64     pybind11::detail::embedded_module name(PYBIND11_TOSTRING(name),           \
  65                                PYBIND11_CONCAT(pybind11_init_impl_, name));   \
  66     void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &variable)
  67
  68
  69 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
  70 NAMESPACE_BEGIN(detail)
  71
  72 /// Python 2.7/3.x compatible version of `PyImport_AppendInittab` and error checks.
  73 struct embedded_module {
  74 #if PY_MAJOR_VERSION >= 3
  75     using init_t = PyObject *(*)();
  76 #else
  77     using init_t = void (*)();
  78 #endif
  79     embedded_module(const char *name, init_t init) {
  80         if (Py_IsInitialized())
  81             pybind11_fail("Can't add new modules after the interpreter has been initialized");
  82
  83         auto result = PyImport_AppendInittab(name, init);
  84         if (result == -1)
  85             pybind11_fail("Insufficient memory to add a new module");
  86     }
  87 };
  88
  89 NAMESPACE_END(detail)
  90
  91 /** \rst
  92     Initialize the Python interpreter. No other pybind11 or CPython API functions can be
  93     called before this is done; with the exception of `PYBIND11_EMBEDDED_MODULE`. The
  94     optional parameter can be used to skip the registration of signal handlers (see the
  95     `Python documentation`_ for details). Calling this function again after the interpreter
  96     has already been initialized is a fatal error.
  97
  98     If initializing the Python interpreter fails, then the program is terminated.  (This
  99     is controlled by the CPython runtime and is an exception to pybind11's normal behavior
 100     of throwing exceptions on errors.)
 101
 102     .. _Python documentation: https://docs.python.org/3/c-api/init.html#c.Py_InitializeEx
 103  \endrst */
 104 inline void initialize_interpreter(bool init_signal_handlers = true) {
 105     if (Py_IsInitialized())
 106         pybind11_fail("The interpreter is already running");
 107
 108     Py_InitializeEx(init_signal_handlers ? 1 : 0);
 109
 110     // Make .py files in the working directory available by default
 111     module::import("sys").attr("path").cast<list>().append(".");
 112 }
 113
 114 /** \rst
 115     Shut down the Python interpreter. No pybind11 or CPython API functions can be called
 116     after this. In addition, pybind11 objects must not outlive the interpreter:
 117
 118     .. code-block:: cpp
 119
 120         { // BAD
 121             py::initialize_interpreter();
 122             auto hello = py::str("Hello, World!");
 123             py::finalize_interpreter();
 124         } // <-- BOOM, hello's destructor is called after interpreter shutdown
 125
 126         { // GOOD
 127             py::initialize_interpreter();
 128             { // scoped
 129                 auto hello = py::str("Hello, World!");
 130             } // <-- OK, hello is cleaned up properly
 131             py::finalize_interpreter();
 132         }
 133
 134         { // BETTER
 135             py::scoped_interpreter guard{};
 136             auto hello = py::str("Hello, World!");
 137         }
 138
 139     .. warning::
 140
 141         The interpreter can be restarted by calling `initialize_interpreter` again.
 142         Modules created using pybind11 can be safely re-initialized. However, Python
 143         itself cannot completely unload binary extension modules and there are several
 144         caveats with regard to interpreter restarting. All the details can be found
 145         in the CPython documentation. In short, not all interpreter memory may be
 146         freed, either due to reference cycles or user-created global data.
 147
 148  \endrst */
 149 inline void finalize_interpreter() {
 150     handle builtins(PyEval_GetBuiltins());
 151     const char *id = PYBIND11_INTERNALS_ID;
 152
 153     // Get the internals pointer (without creating it if it doesn't exist).  It's possible for the
 154     // internals to be created during Py_Finalize() (e.g. if a py::capsule calls `get_internals()`
 155     // during destruction), so we get the pointer-pointer here and check it after Py_Finalize().
 156     detail::internals **internals_ptr_ptr = detail::get_internals_pp();
 157     // It could also be stashed in builtins, so look there too:
 158     if (builtins.contains(id) && isinstance<capsule>(builtins[id]))
 159         internals_ptr_ptr = capsule(builtins[id]);
 160
 161     Py_Finalize();
 162
 163     if (internals_ptr_ptr) {
 164         delete *internals_ptr_ptr;
 165         *internals_ptr_ptr = nullptr;
 166     }
 167 }
 168
 169 /** \rst
 170     Scope guard version of `initialize_interpreter` and `finalize_interpreter`.
 171     This a move-only guard and only a single instance can exist.
 172
 173     .. code-block:: cpp
 174
 175         #include <pybind11/embed.h>
 176
 177         int main() {
 178             py::scoped_interpreter guard{};
 179             py::print(Hello, World!);
 180         } // <-- interpreter shutdown
 181  \endrst */
 182 class scoped_interpreter {
 183 public:
 184     scoped_interpreter(bool init_signal_handlers = true) {
 185         initialize_interpreter(init_signal_handlers);
 186     }
 187
 188     scoped_interpreter(const scoped_interpreter &) = delete;
 189     scoped_interpreter(scoped_interpreter &&other) noexcept { other.is_valid = false; }
 190     scoped_interpreter &operator=(const scoped_interpreter &) = delete;
 191     scoped_interpreter &operator=(scoped_interpreter &&) = delete;
 192
 193     ~scoped_interpreter() {
 194         if (is_valid)
 195             finalize_interpreter();
 196     }
 197
 198 private:
 199     bool is_valid = true;
 200 };
 201
 202 NAMESPACE_END(PYBIND11_NAMESPACE)