1 /*
2 pybind11/detail/internals.h: Internal data structure and related functions
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 "../pytypes.h"
13
14 /// Tracks the `internals` and `type_info` ABI version independent of the main library version.
15 ///
16 /// Some portions of the code use an ABI that is conditional depending on this
17 /// version number. That allows ABI-breaking changes to be "pre-implemented".
18 /// Once the default version number is incremented, the conditional logic that
19 /// no longer applies can be removed. Additionally, users that need not
20 /// maintain ABI compatibility can increase the version number in order to take
21 /// advantage of any functionality/efficiency improvements that depend on the
22 /// newer ABI.
23 ///
24 /// WARNING: If you choose to manually increase the ABI version, note that
25 /// pybind11 may not be tested as thoroughly with a non-default ABI version, and
26 /// further ABI-incompatible changes may be made before the ABI is officially
27 /// changed to the new version.
28 #ifndef PYBIND11_INTERNALS_VERSION
29 # define PYBIND11_INTERNALS_VERSION 4
30 #endif
31
32 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
33
34 using ExceptionTranslator = void (*)(std::exception_ptr);
35
36 PYBIND11_NAMESPACE_BEGIN(detail)
37
38 // Forward declarations
39 inline PyTypeObject *make_static_property_type();
40 inline PyTypeObject *make_default_metaclass();
41 inline PyObject *make_object_base_type(PyTypeObject *metaclass);
42
43 // The old Python Thread Local Storage (TLS) API is deprecated in Python 3.7 in favor of the new
44 // Thread Specific Storage (TSS) API.
45 #if PY_VERSION_HEX >= 0x03070000
46 // Avoid unnecessary allocation of `Py_tss_t`, since we cannot use
47 // `Py_LIMITED_API` anyway.
48 # if PYBIND11_INTERNALS_VERSION > 4
49 # define PYBIND11_TLS_KEY_REF Py_tss_t &
50 # ifdef __GNUC__
51 // Clang on macOS warns due to `Py_tss_NEEDS_INIT` not specifying an initializer
52 // for every field.
53 # define PYBIND11_TLS_KEY_INIT(var) \
54 _Pragma("GCC diagnostic push") /**/ \
55 _Pragma("GCC diagnostic ignored \"-Wmissing-field-initializers\"") /**/ \
56 Py_tss_t var \
57 = Py_tss_NEEDS_INIT; \
58 _Pragma("GCC diagnostic pop")
59 # else
60 # define PYBIND11_TLS_KEY_INIT(var) Py_tss_t var = Py_tss_NEEDS_INIT;
61 # endif
62 # define PYBIND11_TLS_KEY_CREATE(var) (PyThread_tss_create(&(var)) == 0)
63 # define PYBIND11_TLS_GET_VALUE(key) PyThread_tss_get(&(key))
64 # define PYBIND11_TLS_REPLACE_VALUE(key, value) PyThread_tss_set(&(key), (value))
65 # define PYBIND11_TLS_DELETE_VALUE(key) PyThread_tss_set(&(key), nullptr)
66 # define PYBIND11_TLS_FREE(key) PyThread_tss_delete(&(key))
67 # else
68 # define PYBIND11_TLS_KEY_REF Py_tss_t *
69 # define PYBIND11_TLS_KEY_INIT(var) Py_tss_t *var = nullptr;
70 # define PYBIND11_TLS_KEY_CREATE(var) \
71 (((var) = PyThread_tss_alloc()) != nullptr && (PyThread_tss_create((var)) == 0))
72 # define PYBIND11_TLS_GET_VALUE(key) PyThread_tss_get((key))
73 # define PYBIND11_TLS_REPLACE_VALUE(key, value) PyThread_tss_set((key), (value))
74 # define PYBIND11_TLS_DELETE_VALUE(key) PyThread_tss_set((key), nullptr)
75 # define PYBIND11_TLS_FREE(key) PyThread_tss_free(key)
76 # endif
77 #else
78 // Usually an int but a long on Cygwin64 with Python 3.x
79 # define PYBIND11_TLS_KEY_REF decltype(PyThread_create_key())
80 # define PYBIND11_TLS_KEY_INIT(var) PYBIND11_TLS_KEY_REF var = 0;
81 # define PYBIND11_TLS_KEY_CREATE(var) (((var) = PyThread_create_key()) != -1)
82 # define PYBIND11_TLS_GET_VALUE(key) PyThread_get_key_value((key))
83 # if PY_MAJOR_VERSION < 3 || defined(PYPY_VERSION)
84 // On CPython < 3.4 and on PyPy, `PyThread_set_key_value` strangely does not set
85 // the value if it has already been set. Instead, it must first be deleted and
86 // then set again.
tls_replace_value(PYBIND11_TLS_KEY_REF key,void * value)87 inline void tls_replace_value(PYBIND11_TLS_KEY_REF key, void *value) {
88 PyThread_delete_key_value(key);
89 PyThread_set_key_value(key, value);
90 }
91 # define PYBIND11_TLS_DELETE_VALUE(key) PyThread_delete_key_value(key)
92 # define PYBIND11_TLS_REPLACE_VALUE(key, value) \
93 ::pybind11::detail::tls_replace_value((key), (value))
94 # else
95 # define PYBIND11_TLS_DELETE_VALUE(key) PyThread_set_key_value((key), nullptr)
96 # define PYBIND11_TLS_REPLACE_VALUE(key, value) PyThread_set_key_value((key), (value))
97 # endif
98 # define PYBIND11_TLS_FREE(key) (void) key
99 #endif
100
101 // Python loads modules by default with dlopen with the RTLD_LOCAL flag; under libc++ and possibly
102 // other STLs, this means `typeid(A)` from one module won't equal `typeid(A)` from another module
103 // even when `A` is the same, non-hidden-visibility type (e.g. from a common include). Under
104 // libstdc++, this doesn't happen: equality and the type_index hash are based on the type name,
105 // which works. If not under a known-good stl, provide our own name-based hash and equality
106 // functions that use the type name.
107 #if defined(__GLIBCXX__)
same_type(const std::type_info & lhs,const std::type_info & rhs)108 inline bool same_type(const std::type_info &lhs, const std::type_info &rhs) { return lhs == rhs; }
109 using type_hash = std::hash<std::type_index>;
110 using type_equal_to = std::equal_to<std::type_index>;
111 #else
same_type(const std::type_info & lhs,const std::type_info & rhs)112 inline bool same_type(const std::type_info &lhs, const std::type_info &rhs) {
113 return lhs.name() == rhs.name() || std::strcmp(lhs.name(), rhs.name()) == 0;
114 }
115
116 struct type_hash {
operatortype_hash117 size_t operator()(const std::type_index &t) const {
118 size_t hash = 5381;
119 const char *ptr = t.name();
120 while (auto c = static_cast<unsigned char>(*ptr++))
121 hash = (hash * 33) ^ c;
122 return hash;
123 }
124 };
125
126 struct type_equal_to {
operatortype_equal_to127 bool operator()(const std::type_index &lhs, const std::type_index &rhs) const {
128 return lhs.name() == rhs.name() || std::strcmp(lhs.name(), rhs.name()) == 0;
129 }
130 };
131 #endif
132
133 template <typename value_type>
134 using type_map = std::unordered_map<std::type_index, value_type, type_hash, type_equal_to>;
135
136 struct override_hash {
operatoroverride_hash137 inline size_t operator()(const std::pair<const PyObject *, const char *>& v) const {
138 size_t value = std::hash<const void *>()(v.first);
139 value ^= std::hash<const void *>()(v.second) + 0x9e3779b9 + (value<<6) + (value>>2);
140 return value;
141 }
142 };
143
144 /// Internal data structure used to track registered instances and types.
145 /// Whenever binary incompatible changes are made to this structure,
146 /// `PYBIND11_INTERNALS_VERSION` must be incremented.
147 struct internals {
148 type_map<type_info *> registered_types_cpp; // std::type_index -> pybind11's type information
149 std::unordered_map<PyTypeObject *, std::vector<type_info *>> registered_types_py; // PyTypeObject* -> base type_info(s)
150 std::unordered_multimap<const void *, instance*> registered_instances; // void * -> instance*
151 std::unordered_set<std::pair<const PyObject *, const char *>, override_hash> inactive_override_cache;
152 type_map<std::vector<bool (*)(PyObject *, void *&)>> direct_conversions;
153 std::unordered_map<const PyObject *, std::vector<PyObject *>> patients;
154 std::forward_list<ExceptionTranslator> registered_exception_translators;
155 std::unordered_map<std::string, void *> shared_data; // Custom data to be shared across extensions
156 #if PYBIND11_INTERNALS_VERSION == 4
157 std::vector<PyObject *> unused_loader_patient_stack_remove_at_v5;
158 #endif
159 std::forward_list<std::string> static_strings; // Stores the std::strings backing detail::c_str()
160 PyTypeObject *static_property_type;
161 PyTypeObject *default_metaclass;
162 PyObject *instance_base;
163 #if defined(WITH_THREAD)
164 PYBIND11_TLS_KEY_INIT(tstate)
165 # if PYBIND11_INTERNALS_VERSION > 4
166 PYBIND11_TLS_KEY_INIT(loader_life_support_tls_key)
167 # endif // PYBIND11_INTERNALS_VERSION > 4
168 PyInterpreterState *istate = nullptr;
~internalsinternals169 ~internals() {
170 # if PYBIND11_INTERNALS_VERSION > 4
171 PYBIND11_TLS_FREE(loader_life_support_tls_key);
172 # endif // PYBIND11_INTERNALS_VERSION > 4
173
174 // This destructor is called *after* Py_Finalize() in finalize_interpreter().
175 // That *SHOULD BE* fine. The following details what happens when PyThread_tss_free is
176 // called. PYBIND11_TLS_FREE is PyThread_tss_free on python 3.7+. On older python, it does
177 // nothing. PyThread_tss_free calls PyThread_tss_delete and PyMem_RawFree.
178 // PyThread_tss_delete just calls TlsFree (on Windows) or pthread_key_delete (on *NIX).
179 // Neither of those have anything to do with CPython internals. PyMem_RawFree *requires*
180 // that the `tstate` be allocated with the CPython allocator.
181 PYBIND11_TLS_FREE(tstate);
182 }
183 #endif
184 };
185
186 /// Additional type information which does not fit into the PyTypeObject.
187 /// Changes to this struct also require bumping `PYBIND11_INTERNALS_VERSION`.
188 struct type_info {
189 PyTypeObject *type;
190 const std::type_info *cpptype;
191 size_t type_size, type_align, holder_size_in_ptrs;
192 void *(*operator_new)(size_t);
193 void (*init_instance)(instance *, const void *);
194 void (*dealloc)(value_and_holder &v_h);
195 std::vector<PyObject *(*)(PyObject *, PyTypeObject *)> implicit_conversions;
196 std::vector<std::pair<const std::type_info *, void *(*)(void *)>> implicit_casts;
197 std::vector<bool (*)(PyObject *, void *&)> *direct_conversions;
198 buffer_info *(*get_buffer)(PyObject *, void *) = nullptr;
199 void *get_buffer_data = nullptr;
200 void *(*module_local_load)(PyObject *, const type_info *) = nullptr;
201 /* A simple type never occurs as a (direct or indirect) parent
202 * of a class that makes use of multiple inheritance */
203 bool simple_type : 1;
204 /* True if there is no multiple inheritance in this type's inheritance tree */
205 bool simple_ancestors : 1;
206 /* for base vs derived holder_type checks */
207 bool default_holder : 1;
208 /* true if this is a type registered with py::module_local */
209 bool module_local : 1;
210 };
211
212 /// On MSVC, debug and release builds are not ABI-compatible!
213 #if defined(_MSC_VER) && defined(_DEBUG)
214 # define PYBIND11_BUILD_TYPE "_debug"
215 #else
216 # define PYBIND11_BUILD_TYPE ""
217 #endif
218
219 /// Let's assume that different compilers are ABI-incompatible.
220 /// A user can manually set this string if they know their
221 /// compiler is compatible.
222 #ifndef PYBIND11_COMPILER_TYPE
223 # if defined(_MSC_VER)
224 # define PYBIND11_COMPILER_TYPE "_msvc"
225 # elif defined(__INTEL_COMPILER)
226 # define PYBIND11_COMPILER_TYPE "_icc"
227 # elif defined(__clang__)
228 # define PYBIND11_COMPILER_TYPE "_clang"
229 # elif defined(__PGI)
230 # define PYBIND11_COMPILER_TYPE "_pgi"
231 # elif defined(__MINGW32__)
232 # define PYBIND11_COMPILER_TYPE "_mingw"
233 # elif defined(__CYGWIN__)
234 # define PYBIND11_COMPILER_TYPE "_gcc_cygwin"
235 # elif defined(__GNUC__)
236 # define PYBIND11_COMPILER_TYPE "_gcc"
237 # else
238 # define PYBIND11_COMPILER_TYPE "_unknown"
239 # endif
240 #endif
241
242 /// Also standard libs
243 #ifndef PYBIND11_STDLIB
244 # if defined(_LIBCPP_VERSION)
245 # define PYBIND11_STDLIB "_libcpp"
246 # elif defined(__GLIBCXX__) || defined(__GLIBCPP__)
247 # define PYBIND11_STDLIB "_libstdcpp"
248 # else
249 # define PYBIND11_STDLIB ""
250 # endif
251 #endif
252
253 /// On Linux/OSX, changes in __GXX_ABI_VERSION__ indicate ABI incompatibility.
254 #ifndef PYBIND11_BUILD_ABI
255 # if defined(__GXX_ABI_VERSION)
256 # define PYBIND11_BUILD_ABI "_cxxabi" PYBIND11_TOSTRING(__GXX_ABI_VERSION)
257 # else
258 # define PYBIND11_BUILD_ABI ""
259 # endif
260 #endif
261
262 #ifndef PYBIND11_INTERNALS_KIND
263 # if defined(WITH_THREAD)
264 # define PYBIND11_INTERNALS_KIND ""
265 # else
266 # define PYBIND11_INTERNALS_KIND "_without_thread"
267 # endif
268 #endif
269
270 #define PYBIND11_INTERNALS_ID "__pybind11_internals_v" \
271 PYBIND11_TOSTRING(PYBIND11_INTERNALS_VERSION) PYBIND11_INTERNALS_KIND PYBIND11_COMPILER_TYPE PYBIND11_STDLIB PYBIND11_BUILD_ABI PYBIND11_BUILD_TYPE "__"
272
273 #define PYBIND11_MODULE_LOCAL_ID "__pybind11_module_local_v" \
274 PYBIND11_TOSTRING(PYBIND11_INTERNALS_VERSION) PYBIND11_INTERNALS_KIND PYBIND11_COMPILER_TYPE PYBIND11_STDLIB PYBIND11_BUILD_ABI PYBIND11_BUILD_TYPE "__"
275
276 /// Each module locally stores a pointer to the `internals` data. The data
277 /// itself is shared among modules with the same `PYBIND11_INTERNALS_ID`.
get_internals_pp()278 inline internals **&get_internals_pp() {
279 static internals **internals_pp = nullptr;
280 return internals_pp;
281 }
282
translate_exception(std::exception_ptr p)283 inline void translate_exception(std::exception_ptr p) {
284 try {
285 if (p) std::rethrow_exception(p);
286 } catch (error_already_set &e) { e.restore(); return;
287 } catch (const builtin_exception &e) { e.set_error(); return;
288 } catch (const std::bad_alloc &e) { PyErr_SetString(PyExc_MemoryError, e.what()); return;
289 } catch (const std::domain_error &e) { PyErr_SetString(PyExc_ValueError, e.what()); return;
290 } catch (const std::invalid_argument &e) { PyErr_SetString(PyExc_ValueError, e.what()); return;
291 } catch (const std::length_error &e) { PyErr_SetString(PyExc_ValueError, e.what()); return;
292 } catch (const std::out_of_range &e) { PyErr_SetString(PyExc_IndexError, e.what()); return;
293 } catch (const std::range_error &e) { PyErr_SetString(PyExc_ValueError, e.what()); return;
294 } catch (const std::overflow_error &e) { PyErr_SetString(PyExc_OverflowError, e.what()); return;
295 } catch (const std::exception &e) { PyErr_SetString(PyExc_RuntimeError, e.what()); return;
296 } catch (...) {
297 PyErr_SetString(PyExc_RuntimeError, "Caught an unknown exception!");
298 return;
299 }
300 }
301
302 #if !defined(__GLIBCXX__)
translate_local_exception(std::exception_ptr p)303 inline void translate_local_exception(std::exception_ptr p) {
304 try {
305 if (p) std::rethrow_exception(p);
306 } catch (error_already_set &e) { e.restore(); return;
307 } catch (const builtin_exception &e) { e.set_error(); return;
308 }
309 }
310 #endif
311
312 /// Return a reference to the current `internals` data
get_internals()313 PYBIND11_NOINLINE internals &get_internals() {
314 auto **&internals_pp = get_internals_pp();
315 if (internals_pp && *internals_pp)
316 return **internals_pp;
317
318 // Ensure that the GIL is held since we will need to make Python calls.
319 // Cannot use py::gil_scoped_acquire here since that constructor calls get_internals.
320 struct gil_scoped_acquire_local {
321 gil_scoped_acquire_local() : state (PyGILState_Ensure()) {}
322 ~gil_scoped_acquire_local() { PyGILState_Release(state); }
323 const PyGILState_STATE state;
324 } gil;
325
326 PYBIND11_STR_TYPE id(PYBIND11_INTERNALS_ID);
327 auto builtins = handle(PyEval_GetBuiltins());
328 if (builtins.contains(id) && isinstance<capsule>(builtins[id])) {
329 internals_pp = static_cast<internals **>(capsule(builtins[id]));
330
331 // We loaded builtins through python's builtins, which means that our `error_already_set`
332 // and `builtin_exception` may be different local classes than the ones set up in the
333 // initial exception translator, below, so add another for our local exception classes.
334 //
335 // libstdc++ doesn't require this (types there are identified only by name)
336 // libc++ with CPython doesn't require this (types are explicitly exported)
337 // libc++ with PyPy still need it, awaiting further investigation
338 #if !defined(__GLIBCXX__)
339 (*internals_pp)->registered_exception_translators.push_front(&translate_local_exception);
340 #endif
341 } else {
342 if (!internals_pp) internals_pp = new internals*();
343 auto *&internals_ptr = *internals_pp;
344 internals_ptr = new internals();
345 #if defined(WITH_THREAD)
346
347 # if PY_VERSION_HEX < 0x03090000
348 PyEval_InitThreads();
349 # endif
350 PyThreadState *tstate = PyThreadState_Get();
351 if (!PYBIND11_TLS_KEY_CREATE(internals_ptr->tstate)) {
352 pybind11_fail("get_internals: could not successfully initialize the tstate TSS key!");
353 }
354 PYBIND11_TLS_REPLACE_VALUE(internals_ptr->tstate, tstate);
355
356 # if PYBIND11_INTERNALS_VERSION > 4
357 if (!PYBIND11_TLS_KEY_CREATE(internals_ptr->loader_life_support_tls_key)) {
358 pybind11_fail("get_internals: could not successfully initialize the "
359 "loader_life_support TSS key!");
360 }
361 # endif
362 internals_ptr->istate = tstate->interp;
363 #endif
364 builtins[id] = capsule(internals_pp);
365 internals_ptr->registered_exception_translators.push_front(&translate_exception);
366 internals_ptr->static_property_type = make_static_property_type();
367 internals_ptr->default_metaclass = make_default_metaclass();
368 internals_ptr->instance_base = make_object_base_type(internals_ptr->default_metaclass);
369 }
370 return **internals_pp;
371 }
372
373 // the internals struct (above) is shared between all the modules. local_internals are only
374 // for a single module. Any changes made to internals may require an update to
375 // PYBIND11_INTERNALS_VERSION, breaking backwards compatibility. local_internals is, by design,
376 // restricted to a single module. Whether a module has local internals or not should not
377 // impact any other modules, because the only things accessing the local internals is the
378 // module that contains them.
379 struct local_internals {
380 type_map<type_info *> registered_types_cpp;
381 std::forward_list<ExceptionTranslator> registered_exception_translators;
382 #if defined(WITH_THREAD) && PYBIND11_INTERNALS_VERSION == 4
383
384 // For ABI compatibility, we can't store the loader_life_support TLS key in
385 // the `internals` struct directly. Instead, we store it in `shared_data` and
386 // cache a copy in `local_internals`. If we allocated a separate TLS key for
387 // each instance of `local_internals`, we could end up allocating hundreds of
388 // TLS keys if hundreds of different pybind11 modules are loaded (which is a
389 // plausible number).
390 PYBIND11_TLS_KEY_INIT(loader_life_support_tls_key)
391
392 // Holds the shared TLS key for the loader_life_support stack.
393 struct shared_loader_life_support_data {
394 PYBIND11_TLS_KEY_INIT(loader_life_support_tls_key)
shared_loader_life_support_datalocal_internals::shared_loader_life_support_data395 shared_loader_life_support_data() {
396 if (!PYBIND11_TLS_KEY_CREATE(loader_life_support_tls_key)) {
397 pybind11_fail("local_internals: could not successfully initialize the "
398 "loader_life_support TLS key!");
399 }
400 }
401 // We can't help but leak the TLS key, because Python never unloads extension modules.
402 };
403
local_internalslocal_internals404 local_internals() {
405 auto &internals = get_internals();
406 // Get or create the `loader_life_support_stack_key`.
407 auto &ptr = internals.shared_data["_life_support"];
408 if (!ptr) {
409 ptr = new shared_loader_life_support_data;
410 }
411 loader_life_support_tls_key
412 = static_cast<shared_loader_life_support_data *>(ptr)->loader_life_support_tls_key;
413 }
414 #endif // defined(WITH_THREAD) && PYBIND11_INTERNALS_VERSION == 4
415 };
416
417 /// Works like `get_internals`, but for things which are locally registered.
get_local_internals()418 inline local_internals &get_local_internals() {
419 static local_internals locals;
420 return locals;
421 }
422
423
424 /// Constructs a std::string with the given arguments, stores it in `internals`, and returns its
425 /// `c_str()`. Such strings objects have a long storage duration -- the internal strings are only
426 /// cleared when the program exits or after interpreter shutdown (when embedding), and so are
427 /// suitable for c-style strings needed by Python internals (such as PyTypeObject's tp_name).
428 template <typename... Args>
c_str(Args &&...args)429 const char *c_str(Args &&...args) {
430 auto &strings = get_internals().static_strings;
431 strings.emplace_front(std::forward<Args>(args)...);
432 return strings.front().c_str();
433 }
434
PYBIND11_NAMESPACE_END(detail)435 PYBIND11_NAMESPACE_END(detail)
436
437 /// Returns a named pointer that is shared among all extension modules (using the same
438 /// pybind11 version) running in the current interpreter. Names starting with underscores
439 /// are reserved for internal usage. Returns `nullptr` if no matching entry was found.
440 PYBIND11_NOINLINE void *get_shared_data(const std::string &name) {
441 auto &internals = detail::get_internals();
442 auto it = internals.shared_data.find(name);
443 return it != internals.shared_data.end() ? it->second : nullptr;
444 }
445
446 /// Set the shared data that can be later recovered by `get_shared_data()`.
set_shared_data(const std::string & name,void * data)447 PYBIND11_NOINLINE void *set_shared_data(const std::string &name, void *data) {
448 detail::get_internals().shared_data[name] = data;
449 return data;
450 }
451
452 /// Returns a typed reference to a shared data entry (by using `get_shared_data()`) if
453 /// such entry exists. Otherwise, a new object of default-constructible type `T` is
454 /// added to the shared data under the given name and a reference to it is returned.
455 template<typename T>
get_or_create_shared_data(const std::string & name)456 T &get_or_create_shared_data(const std::string &name) {
457 auto &internals = detail::get_internals();
458 auto it = internals.shared_data.find(name);
459 T *ptr = (T *) (it != internals.shared_data.end() ? it->second : nullptr);
460 if (!ptr) {
461 ptr = new T();
462 internals.shared_data[name] = ptr;
463 }
464 return *ptr;
465 }
466
467 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
468