embed.h revision 12391:ceeca8b41e4b 
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 \endrst */
96inline void initialize_interpreter(bool init_signal_handlers = true) {
97    if (Py_IsInitialized())
98        pybind11_fail("The interpreter is already running");
99
100    Py_InitializeEx(init_signal_handlers ? 1 : 0);
101
102    // Make .py files in the working directory available by default
103    module::import("sys").attr("path").cast<list>().append(".");
104}
105
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:
109
110    .. code-block:: cpp
111
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
117
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        }
125
126        { // BETTER
127            py::scoped_interpreter guard{};
128            auto hello = py::str("Hello, World!");
129        }
130
131    .. warning::
132
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.
139
140 \endrst */
141inline void finalize_interpreter() {
142    handle builtins(PyEval_GetBuiltins());
143    const char *id = PYBIND11_INTERNALS_ID;
144
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_ptr();
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]);
152
153    Py_Finalize();
154
155    if (internals_ptr_ptr) {
156        delete *internals_ptr_ptr;
157        *internals_ptr_ptr = nullptr;
158    }
159}
160
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.
164
165    .. code-block:: cpp
166
167        #include <pybind11/embed.h>
168
169        int main() {
170            py::scoped_interpreter guard{};
171            py::print(Hello, World!);
172        } // <-- interpreter shutdown
173 \endrst */
174class scoped_interpreter {
175public:
176    scoped_interpreter(bool init_signal_handlers = true) {
177        initialize_interpreter(init_signal_handlers);
178    }
179
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;
184
185    ~scoped_interpreter() {
186        if (is_valid)
187            finalize_interpreter();
188    }
189
190private:
191    bool is_valid = true;
192};
193
194NAMESPACE_END(PYBIND11_NAMESPACE)
195