Adding pybind11 v2.2.4 to repo
[tidl/tidl-api.git] / tidl_api / pybind11 / include / pybind11 / embed.h
1 /*
2     pybind11/embed.h: Support for embedding the interpreter
4     Copyright (c) 2017 Wenzel Jakob <wenzel.jakob@epfl.ch>
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 */
10 #pragma once
12 #include "pybind11.h"
13 #include "eval.h"
15 #if defined(PYPY_VERSION)
16 #  error Embedding the interpreter is not supported with PyPy
17 #endif
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
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.
37     .. code-block:: cpp
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)
67 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
68 NAMESPACE_BEGIN(detail)
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");
81         auto result = PyImport_AppendInittab(name, init);
82         if (result == -1)
83             pybind11_fail("Insufficient memory to add a new module");
84     }
85 };
87 NAMESPACE_END(detail)
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  \endrst */
96 inline void initialize_interpreter(bool init_signal_handlers = true) {
97     if (Py_IsInitialized())
98         pybind11_fail("The interpreter is already running");
100     Py_InitializeEx(init_signal_handlers ? 1 : 0);
102     // Make .py files in the working directory available by default
103     module::import("sys").attr("path").cast<list>().append(".");
106 /** \rst
107     Shut down the Python interpreter. No pybind11 or CPython API functions can be called
108     after this. In addition, pybind11 objects must not outlive the interpreter:
110     .. code-block:: cpp
112         { // BAD
113             py::initialize_interpreter();
114             auto hello = py::str("Hello, World!");
115             py::finalize_interpreter();
116         } // <-- BOOM, hello's destructor is called after interpreter shutdown
118         { // GOOD
119             py::initialize_interpreter();
120             { // scoped
121                 auto hello = py::str("Hello, World!");
122             } // <-- OK, hello is cleaned up properly
123             py::finalize_interpreter();
124         }
126         { // BETTER
127             py::scoped_interpreter guard{};
128             auto hello = py::str("Hello, World!");
129         }
131     .. warning::
133         The interpreter can be restarted by calling `initialize_interpreter` again.
134         Modules created using pybind11 can be safely re-initialized. However, Python
135         itself cannot completely unload binary extension modules and there are several
136         caveats with regard to interpreter restarting. All the details can be found
137         in the CPython documentation. In short, not all interpreter memory may be
138         freed, either due to reference cycles or user-created global data.
140  \endrst */
141 inline void finalize_interpreter() {
142     handle builtins(PyEval_GetBuiltins());
143     const char *id = PYBIND11_INTERNALS_ID;
145     // Get the internals pointer (without creating it if it doesn't exist).  It's possible for the
146     // internals to be created during Py_Finalize() (e.g. if a py::capsule calls `get_internals()`
147     // during destruction), so we get the pointer-pointer here and check it after Py_Finalize().
148     detail::internals **internals_ptr_ptr = detail::get_internals_pp();
149     // It could also be stashed in builtins, so look there too:
150     if (builtins.contains(id) && isinstance<capsule>(builtins[id]))
151         internals_ptr_ptr = capsule(builtins[id]);
153     Py_Finalize();
155     if (internals_ptr_ptr) {
156         delete *internals_ptr_ptr;
157         *internals_ptr_ptr = nullptr;
158     }
161 /** \rst
162     Scope guard version of `initialize_interpreter` and `finalize_interpreter`.
163     This a move-only guard and only a single instance can exist.
165     .. code-block:: cpp
167         #include <pybind11/embed.h>
169         int main() {
170             py::scoped_interpreter guard{};
171             py::print(Hello, World!);
172         } // <-- interpreter shutdown
173  \endrst */
174 class scoped_interpreter {
175 public:
176     scoped_interpreter(bool init_signal_handlers = true) {
177         initialize_interpreter(init_signal_handlers);
178     }
180     scoped_interpreter(const scoped_interpreter &) = delete;
181     scoped_interpreter(scoped_interpreter &&other) noexcept { other.is_valid = false; }
182     scoped_interpreter &operator=(const scoped_interpreter &) = delete;
183     scoped_interpreter &operator=(scoped_interpreter &&) = delete;
185     ~scoped_interpreter() {
186         if (is_valid)
187             finalize_interpreter();
188     }
190 private:
191     bool is_valid = true;
192 };
194 NAMESPACE_END(PYBIND11_NAMESPACE)