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