112391Sjason@lowepower.com/* 212391Sjason@lowepower.com pybind11/embed.h: Support for embedding the interpreter 312391Sjason@lowepower.com 412391Sjason@lowepower.com Copyright (c) 2017 Wenzel Jakob <wenzel.jakob@epfl.ch> 512391Sjason@lowepower.com 612391Sjason@lowepower.com All rights reserved. Use of this source code is governed by a 712391Sjason@lowepower.com BSD-style license that can be found in the LICENSE file. 812391Sjason@lowepower.com*/ 912391Sjason@lowepower.com 1012391Sjason@lowepower.com#pragma once 1112391Sjason@lowepower.com 1212391Sjason@lowepower.com#include "pybind11.h" 1312391Sjason@lowepower.com#include "eval.h" 1412391Sjason@lowepower.com 1512391Sjason@lowepower.com#if defined(PYPY_VERSION) 1612391Sjason@lowepower.com# error Embedding the interpreter is not supported with PyPy 1712391Sjason@lowepower.com#endif 1812391Sjason@lowepower.com 1912391Sjason@lowepower.com#if PY_MAJOR_VERSION >= 3 2012391Sjason@lowepower.com# define PYBIND11_EMBEDDED_MODULE_IMPL(name) \ 2112391Sjason@lowepower.com extern "C" PyObject *pybind11_init_impl_##name() { \ 2212391Sjason@lowepower.com return pybind11_init_wrapper_##name(); \ 2312391Sjason@lowepower.com } 2412391Sjason@lowepower.com#else 2512391Sjason@lowepower.com# define PYBIND11_EMBEDDED_MODULE_IMPL(name) \ 2612391Sjason@lowepower.com extern "C" void pybind11_init_impl_##name() { \ 2712391Sjason@lowepower.com pybind11_init_wrapper_##name(); \ 2812391Sjason@lowepower.com } 2912391Sjason@lowepower.com#endif 3012391Sjason@lowepower.com 3112391Sjason@lowepower.com/** \rst 3212391Sjason@lowepower.com Add a new module to the table of builtins for the interpreter. Must be 3312391Sjason@lowepower.com defined in global scope. The first macro parameter is the name of the 3412391Sjason@lowepower.com module (without quotes). The second parameter is the variable which will 3512391Sjason@lowepower.com be used as the interface to add functions and classes to the module. 3612391Sjason@lowepower.com 3712391Sjason@lowepower.com .. code-block:: cpp 3812391Sjason@lowepower.com 3912391Sjason@lowepower.com PYBIND11_EMBEDDED_MODULE(example, m) { 4012391Sjason@lowepower.com // ... initialize functions and classes here 4112391Sjason@lowepower.com m.def("foo", []() { 4212391Sjason@lowepower.com return "Hello, World!"; 4312391Sjason@lowepower.com }); 4412391Sjason@lowepower.com } 4512391Sjason@lowepower.com \endrst */ 4612391Sjason@lowepower.com#define PYBIND11_EMBEDDED_MODULE(name, variable) \ 4712391Sjason@lowepower.com static void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &); \ 4812391Sjason@lowepower.com static PyObject PYBIND11_CONCAT(*pybind11_init_wrapper_, name)() { \ 4912391Sjason@lowepower.com auto m = pybind11::module(PYBIND11_TOSTRING(name)); \ 5012391Sjason@lowepower.com try { \ 5112391Sjason@lowepower.com PYBIND11_CONCAT(pybind11_init_, name)(m); \ 5212391Sjason@lowepower.com return m.ptr(); \ 5312391Sjason@lowepower.com } catch (pybind11::error_already_set &e) { \ 5412391Sjason@lowepower.com PyErr_SetString(PyExc_ImportError, e.what()); \ 5512391Sjason@lowepower.com return nullptr; \ 5612391Sjason@lowepower.com } catch (const std::exception &e) { \ 5712391Sjason@lowepower.com PyErr_SetString(PyExc_ImportError, e.what()); \ 5812391Sjason@lowepower.com return nullptr; \ 5912391Sjason@lowepower.com } \ 6012391Sjason@lowepower.com } \ 6112391Sjason@lowepower.com PYBIND11_EMBEDDED_MODULE_IMPL(name) \ 6212391Sjason@lowepower.com pybind11::detail::embedded_module name(PYBIND11_TOSTRING(name), \ 6312391Sjason@lowepower.com PYBIND11_CONCAT(pybind11_init_impl_, name)); \ 6412391Sjason@lowepower.com void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &variable) 6512391Sjason@lowepower.com 6612391Sjason@lowepower.com 6712391Sjason@lowepower.comNAMESPACE_BEGIN(PYBIND11_NAMESPACE) 6812391Sjason@lowepower.comNAMESPACE_BEGIN(detail) 6912391Sjason@lowepower.com 7012391Sjason@lowepower.com/// Python 2.7/3.x compatible version of `PyImport_AppendInittab` and error checks. 7112391Sjason@lowepower.comstruct embedded_module { 7212391Sjason@lowepower.com#if PY_MAJOR_VERSION >= 3 7312391Sjason@lowepower.com using init_t = PyObject *(*)(); 7412391Sjason@lowepower.com#else 7512391Sjason@lowepower.com using init_t = void (*)(); 7612391Sjason@lowepower.com#endif 7712391Sjason@lowepower.com embedded_module(const char *name, init_t init) { 7812391Sjason@lowepower.com if (Py_IsInitialized()) 7912391Sjason@lowepower.com pybind11_fail("Can't add new modules after the interpreter has been initialized"); 8012391Sjason@lowepower.com 8112391Sjason@lowepower.com auto result = PyImport_AppendInittab(name, init); 8212391Sjason@lowepower.com if (result == -1) 8312391Sjason@lowepower.com pybind11_fail("Insufficient memory to add a new module"); 8412391Sjason@lowepower.com } 8512391Sjason@lowepower.com}; 8612391Sjason@lowepower.com 8712391Sjason@lowepower.comNAMESPACE_END(detail) 8812391Sjason@lowepower.com 8912391Sjason@lowepower.com/** \rst 9012391Sjason@lowepower.com Initialize the Python interpreter. No other pybind11 or CPython API functions can be 9112391Sjason@lowepower.com called before this is done; with the exception of `PYBIND11_EMBEDDED_MODULE`. The 9212391Sjason@lowepower.com optional parameter can be used to skip the registration of signal handlers (see the 9314299Sbbruce@ucdavis.edu `Python documentation`_ for details). Calling this function again after the interpreter 9412391Sjason@lowepower.com has already been initialized is a fatal error. 9514299Sbbruce@ucdavis.edu 9614299Sbbruce@ucdavis.edu If initializing the Python interpreter fails, then the program is terminated. (This 9714299Sbbruce@ucdavis.edu is controlled by the CPython runtime and is an exception to pybind11's normal behavior 9814299Sbbruce@ucdavis.edu of throwing exceptions on errors.) 9914299Sbbruce@ucdavis.edu 10014299Sbbruce@ucdavis.edu .. _Python documentation: https://docs.python.org/3/c-api/init.html#c.Py_InitializeEx 10112391Sjason@lowepower.com \endrst */ 10212391Sjason@lowepower.cominline void initialize_interpreter(bool init_signal_handlers = true) { 10312391Sjason@lowepower.com if (Py_IsInitialized()) 10412391Sjason@lowepower.com pybind11_fail("The interpreter is already running"); 10512391Sjason@lowepower.com 10612391Sjason@lowepower.com Py_InitializeEx(init_signal_handlers ? 1 : 0); 10712391Sjason@lowepower.com 10812391Sjason@lowepower.com // Make .py files in the working directory available by default 10912391Sjason@lowepower.com module::import("sys").attr("path").cast<list>().append("."); 11012391Sjason@lowepower.com} 11112391Sjason@lowepower.com 11212391Sjason@lowepower.com/** \rst 11312391Sjason@lowepower.com Shut down the Python interpreter. No pybind11 or CPython API functions can be called 11412391Sjason@lowepower.com after this. In addition, pybind11 objects must not outlive the interpreter: 11512391Sjason@lowepower.com 11612391Sjason@lowepower.com .. code-block:: cpp 11712391Sjason@lowepower.com 11812391Sjason@lowepower.com { // BAD 11912391Sjason@lowepower.com py::initialize_interpreter(); 12012391Sjason@lowepower.com auto hello = py::str("Hello, World!"); 12112391Sjason@lowepower.com py::finalize_interpreter(); 12212391Sjason@lowepower.com } // <-- BOOM, hello's destructor is called after interpreter shutdown 12312391Sjason@lowepower.com 12412391Sjason@lowepower.com { // GOOD 12512391Sjason@lowepower.com py::initialize_interpreter(); 12612391Sjason@lowepower.com { // scoped 12712391Sjason@lowepower.com auto hello = py::str("Hello, World!"); 12812391Sjason@lowepower.com } // <-- OK, hello is cleaned up properly 12912391Sjason@lowepower.com py::finalize_interpreter(); 13012391Sjason@lowepower.com } 13112391Sjason@lowepower.com 13212391Sjason@lowepower.com { // BETTER 13312391Sjason@lowepower.com py::scoped_interpreter guard{}; 13412391Sjason@lowepower.com auto hello = py::str("Hello, World!"); 13512391Sjason@lowepower.com } 13612391Sjason@lowepower.com 13712391Sjason@lowepower.com .. warning:: 13812391Sjason@lowepower.com 13912391Sjason@lowepower.com The interpreter can be restarted by calling `initialize_interpreter` again. 14012391Sjason@lowepower.com Modules created using pybind11 can be safely re-initialized. However, Python 14112391Sjason@lowepower.com itself cannot completely unload binary extension modules and there are several 14212391Sjason@lowepower.com caveats with regard to interpreter restarting. All the details can be found 14312391Sjason@lowepower.com in the CPython documentation. In short, not all interpreter memory may be 14412391Sjason@lowepower.com freed, either due to reference cycles or user-created global data. 14512391Sjason@lowepower.com 14612391Sjason@lowepower.com \endrst */ 14712391Sjason@lowepower.cominline void finalize_interpreter() { 14812391Sjason@lowepower.com handle builtins(PyEval_GetBuiltins()); 14912391Sjason@lowepower.com const char *id = PYBIND11_INTERNALS_ID; 15012391Sjason@lowepower.com 15112391Sjason@lowepower.com // Get the internals pointer (without creating it if it doesn't exist). It's possible for the 15212391Sjason@lowepower.com // internals to be created during Py_Finalize() (e.g. if a py::capsule calls `get_internals()` 15312391Sjason@lowepower.com // during destruction), so we get the pointer-pointer here and check it after Py_Finalize(). 15414299Sbbruce@ucdavis.edu detail::internals **internals_ptr_ptr = detail::get_internals_pp(); 15512391Sjason@lowepower.com // It could also be stashed in builtins, so look there too: 15612391Sjason@lowepower.com if (builtins.contains(id) && isinstance<capsule>(builtins[id])) 15712391Sjason@lowepower.com internals_ptr_ptr = capsule(builtins[id]); 15812391Sjason@lowepower.com 15912391Sjason@lowepower.com Py_Finalize(); 16012391Sjason@lowepower.com 16112391Sjason@lowepower.com if (internals_ptr_ptr) { 16212391Sjason@lowepower.com delete *internals_ptr_ptr; 16312391Sjason@lowepower.com *internals_ptr_ptr = nullptr; 16412391Sjason@lowepower.com } 16512391Sjason@lowepower.com} 16612391Sjason@lowepower.com 16712391Sjason@lowepower.com/** \rst 16812391Sjason@lowepower.com Scope guard version of `initialize_interpreter` and `finalize_interpreter`. 16912391Sjason@lowepower.com This a move-only guard and only a single instance can exist. 17012391Sjason@lowepower.com 17112391Sjason@lowepower.com .. code-block:: cpp 17212391Sjason@lowepower.com 17312391Sjason@lowepower.com #include <pybind11/embed.h> 17412391Sjason@lowepower.com 17512391Sjason@lowepower.com int main() { 17612391Sjason@lowepower.com py::scoped_interpreter guard{}; 17712391Sjason@lowepower.com py::print(Hello, World!); 17812391Sjason@lowepower.com } // <-- interpreter shutdown 17912391Sjason@lowepower.com \endrst */ 18012391Sjason@lowepower.comclass scoped_interpreter { 18112391Sjason@lowepower.compublic: 18212391Sjason@lowepower.com scoped_interpreter(bool init_signal_handlers = true) { 18312391Sjason@lowepower.com initialize_interpreter(init_signal_handlers); 18412391Sjason@lowepower.com } 18512391Sjason@lowepower.com 18612391Sjason@lowepower.com scoped_interpreter(const scoped_interpreter &) = delete; 18712391Sjason@lowepower.com scoped_interpreter(scoped_interpreter &&other) noexcept { other.is_valid = false; } 18812391Sjason@lowepower.com scoped_interpreter &operator=(const scoped_interpreter &) = delete; 18912391Sjason@lowepower.com scoped_interpreter &operator=(scoped_interpreter &&) = delete; 19012391Sjason@lowepower.com 19112391Sjason@lowepower.com ~scoped_interpreter() { 19212391Sjason@lowepower.com if (is_valid) 19312391Sjason@lowepower.com finalize_interpreter(); 19412391Sjason@lowepower.com } 19512391Sjason@lowepower.com 19612391Sjason@lowepower.comprivate: 19712391Sjason@lowepower.com bool is_valid = true; 19812391Sjason@lowepower.com}; 19912391Sjason@lowepower.com 20012391Sjason@lowepower.comNAMESPACE_END(PYBIND11_NAMESPACE) 201