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