pybind11/detail/value_and_holder.h

0001 // Copyright (c) 2016-2024 The Pybind Development Team.
0002 // All rights reserved. Use of this source code is governed by a
0003 // BSD-style license that can be found in the LICENSE file.
0004
0005 #pragma once
0006
0007 #include "common.h"
0008
0009 #include <cstddef>
0010 #include <cstdint>
0011 #include <typeinfo>
0012
0013 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
0014 PYBIND11_NAMESPACE_BEGIN(detail)
0015
0016 struct value_and_holder {
0017     instance *inst = nullptr;
0018     size_t index = 0u;
0019     const detail::type_info *type = nullptr;
0020     void **vh = nullptr;
0021
0022     // Main constructor for a found value/holder:
0023     value_and_holder(instance *i, const detail::type_info *type, size_t vpos, size_t index)
0024         : inst{i}, index{index}, type{type},
0025           vh{inst->simple_layout ? inst->simple_value_holder
0026                                  : &inst->nonsimple.values_and_holders[vpos]} {}
0027
0028     // Default constructor (used to signal a value-and-holder not found by get_value_and_holder())
0029     value_and_holder() = default;
0030
0031     // Used for past-the-end iterator
0032     explicit value_and_holder(size_t index) : index{index} {}
0033
0034     template <typename V = void>
0035     V *&value_ptr() const {
0036         return reinterpret_cast<V *&>(vh[0]);
0037     }
0038     // True if this `value_and_holder` has a non-null value pointer
0039     explicit operator bool() const { return value_ptr() != nullptr; }
0040
0041     template <typename H>
0042     H &holder() const {
0043         return reinterpret_cast<H &>(vh[1]);
0044     }
0045     bool holder_constructed() const {
0046         return inst->simple_layout
0047                    ? inst->simple_holder_constructed
0048                    : (inst->nonsimple.status[index] & instance::status_holder_constructed) != 0u;
0049     }
0050     // NOLINTNEXTLINE(readability-make-member-function-const)
0051     void set_holder_constructed(bool v = true) {
0052         if (inst->simple_layout) {
0053             inst->simple_holder_constructed = v;
0054         } else if (v) {
0055             inst->nonsimple.status[index] |= instance::status_holder_constructed;
0056         } else {
0057             inst->nonsimple.status[index]
0058                 &= static_cast<std::uint8_t>(~instance::status_holder_constructed);
0059         }
0060     }
0061     bool instance_registered() const {
0062         return inst->simple_layout
0063                    ? inst->simple_instance_registered
0064                    : ((inst->nonsimple.status[index] & instance::status_instance_registered) != 0);
0065     }
0066     // NOLINTNEXTLINE(readability-make-member-function-const)
0067     void set_instance_registered(bool v = true) {
0068         if (inst->simple_layout) {
0069             inst->simple_instance_registered = v;
0070         } else if (v) {
0071             inst->nonsimple.status[index] |= instance::status_instance_registered;
0072         } else {
0073             inst->nonsimple.status[index]
0074                 &= static_cast<std::uint8_t>(~instance::status_instance_registered);
0075         }
0076     }
0077 };
0078
0079 // This is a semi-public API to check if the corresponding instance has been constructed with a
0080 // holder. That is, if the instance has been constructed with a holder, the `__init__` method is
0081 // called and the C++ object is valid. Otherwise, the C++ object might only be allocated, but not
0082 // initialized. This will lead to **SEGMENTATION FAULTS** if the C++ object is used in any way.
0083 // Example usage: https://pybind11.readthedocs.io/en/stable/advanced/classes.html#custom-type-setup
0084 //                for `tp_traverse` and `tp_clear` implementations.
0085 // WARNING: The caller is responsible for ensuring that the `reinterpret_cast` is valid.
0086 inline bool is_holder_constructed(PyObject *obj) {
0087     auto *const instance = reinterpret_cast<pybind11::detail::instance *>(obj);
0088     return instance->get_value_and_holder().holder_constructed();
0089 }
0090
0091 PYBIND11_NAMESPACE_END(detail)
0092 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)