embed.h revision 14299:2fbea9df56d2
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 67NAMESPACE_BEGIN(PYBIND11_NAMESPACE) 68NAMESPACE_BEGIN(detail) 69 70/// Python 2.7/3.x compatible version of `PyImport_AppendInittab` and error checks. 71struct 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 87NAMESPACE_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 */ 102inline 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 */ 147inline 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 */ 180class scoped_interpreter { 181public: 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 196private: 197 bool is_valid = true; 198}; 199 200NAMESPACE_END(PYBIND11_NAMESPACE) 201