pybind11/include/pybind11/detail/struct_smart_holder.h

// Copyright (c) 2020-2024 The Pybind Development Team.
// All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

/* Proof-of-Concept for smart pointer interoperability.

High-level aspects:

* Support all `unique_ptr`, `shared_ptr` interops that are feasible.

* Cleanly and clearly report all interops that are infeasible.

* Meant to fit into a `PyObject`, as a holder for C++ objects.

* Support a system design that makes it impossible to trigger
  C++ Undefined Behavior, especially from Python.

* Support a system design with clean runtime inheritance casting. From this
  it follows that the `smart_holder` needs to be type-erased (`void*`).

* Handling of RTTI for the type-erased held pointer is NOT implemented here.
  It is the responsibility of the caller to ensure that `static_cast<T *>`
  is well-formed when calling `as_*` member functions. Inheritance casting
  needs to be handled in a different layer (similar to the code organization
  in boost/python/object/inheritance.hpp).

Details:

* The "root holder" chosen here is a `shared_ptr<void>` (named `vptr` in this
  implementation). This choice is practically inevitable because `shared_ptr`
  has only very limited support for inspecting and accessing its deleter.

* If created from a raw pointer, or a `unique_ptr` without a custom deleter,
  `vptr` always uses a custom deleter, to support `unique_ptr`-like disowning.
  The custom deleters could be extended to included life-time management for
  external objects (e.g. `PyObject`).

* If created from an external `shared_ptr`, or a `unique_ptr` with a custom
  deleter, including life-time management for external objects is infeasible.

* By choice, the smart_holder is movable but not copyable, to keep the design
  simple, and to guard against accidental copying overhead.

* The `void_cast_raw_ptr` option is needed to make the `smart_holder` `vptr`
  member invisible to the `shared_from_this` mechanism, in case the lifetime
  of a `PyObject` is tied to the pointee.
*/

#pragma once

#include "pybind11_namespace_macros.h"

#include <functional>
#include <memory>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <typeinfo>
#include <utility>

// IMPORTANT: This code block must stay BELOW the #include <stdexcept> above.
// This is only required on some builds with libc++ (one of three implementations
// in
// https://github.com/llvm/llvm-project/blob/a9b64bb3180dab6d28bf800a641f9a9ad54d2c0c/libcxx/include/typeinfo#L271-L276
// require it)
#if !defined(PYBIND11_EXPORT_GUARDED_DELETE)
#    if defined(_LIBCPP_VERSION) && !defined(WIN32) && !defined(_WIN32)
#        define PYBIND11_EXPORT_GUARDED_DELETE __attribute__((visibility("default")))
#    else
#        define PYBIND11_EXPORT_GUARDED_DELETE
#    endif
#endif

PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
PYBIND11_NAMESPACE_BEGIN(memory)

// Default fallback.
static constexpr bool type_has_shared_from_this(...) { return false; }

// This overload uses SFINAE to skip enable_shared_from_this checks when the
// base is inaccessible (e.g. private inheritance).
template <typename T>
static auto type_has_shared_from_this(const T *ptr)
    -> decltype(static_cast<const std::enable_shared_from_this<T> *>(ptr), true) {
    return true;
}

// Inaccessible base → substitution failure → fallback overload selected
template <typename T>
static constexpr bool type_has_shared_from_this(const void *) {
    return false;
}

struct PYBIND11_EXPORT_GUARDED_DELETE guarded_delete {
    std::weak_ptr<void> released_ptr;    // Trick to keep the smart_holder memory footprint small.
    std::function<void(void *)> del_fun; // Rare case.
    void (*del_ptr)(void *);             // Common case.
    bool use_del_fun;
    bool armed_flag;
    guarded_delete(std::function<void(void *)> &&del_fun, bool armed_flag)
        : del_fun{std::move(del_fun)}, del_ptr{nullptr}, use_del_fun{true},
          armed_flag{armed_flag} {}
    guarded_delete(void (*del_ptr)(void *), bool armed_flag)
        : del_ptr{del_ptr}, use_del_fun{false}, armed_flag{armed_flag} {}
    void operator()(void *raw_ptr) const {
        if (armed_flag) {
            if (use_del_fun) {
                del_fun(raw_ptr);
            } else {
                del_ptr(raw_ptr);
            }
        }
    }
};

template <typename T, typename std::enable_if<std::is_destructible<T>::value, int>::type = 0>
inline void builtin_delete_if_destructible(void *raw_ptr) {
    std::default_delete<T>{}(static_cast<T *>(raw_ptr));
}

template <typename T, typename std::enable_if<!std::is_destructible<T>::value, int>::type = 0>
inline void builtin_delete_if_destructible(void *) {
    // This noop operator is needed to avoid a compilation error (for `delete raw_ptr;`), but
    // throwing an exception from a destructor will std::terminate the process. Therefore the
    // runtime check for lifetime-management correctness is implemented elsewhere (in
    // ensure_pointee_is_destructible()).
}

template <typename T>
guarded_delete make_guarded_builtin_delete(bool armed_flag) {
    return guarded_delete(builtin_delete_if_destructible<T>, armed_flag);
}

template <typename T, typename D>
struct custom_deleter {
    D deleter;
    explicit custom_deleter(D &&deleter) : deleter{std::forward<D>(deleter)} {}
    void operator()(void *raw_ptr) { deleter(static_cast<T *>(raw_ptr)); }
};

template <typename T, typename D>
guarded_delete make_guarded_custom_deleter(D &&uqp_del, bool armed_flag) {
    return guarded_delete(
        std::function<void(void *)>(custom_deleter<T, D>(std::forward<D>(uqp_del))), armed_flag);
}

template <typename T>
inline bool is_std_default_delete(const std::type_info &rtti_deleter) {
    return rtti_deleter == typeid(std::default_delete<T>)
           || rtti_deleter == typeid(std::default_delete<T const>);
}

struct smart_holder {
    const std::type_info *rtti_uqp_del = nullptr;
    std::shared_ptr<void> vptr;
    bool vptr_is_using_noop_deleter : 1;
    bool vptr_is_using_builtin_delete : 1;
    bool vptr_is_external_shared_ptr : 1;
    bool is_populated : 1;
    bool is_disowned : 1;

    // Design choice: smart_holder is movable but not copyable.
    smart_holder(smart_holder &&) = default;
    smart_holder(const smart_holder &) = delete;
    smart_holder &operator=(smart_holder &&) = delete;
    smart_holder &operator=(const smart_holder &) = delete;

    smart_holder()
        : vptr_is_using_noop_deleter{false}, vptr_is_using_builtin_delete{false},
          vptr_is_external_shared_ptr{false}, is_populated{false}, is_disowned{false} {}

    bool has_pointee() const { return vptr != nullptr; }

    template <typename T>
    static void ensure_pointee_is_destructible(const char *context) {
        if (!std::is_destructible<T>::value) {
            throw std::invalid_argument(std::string("Pointee is not destructible (") + context
                                        + ").");
        }
    }

    void ensure_is_populated(const char *context) const {
        if (!is_populated) {
            throw std::runtime_error(std::string("Unpopulated holder (") + context + ").");
        }
    }
    void ensure_is_not_disowned(const char *context) const {
        if (is_disowned) {
            throw std::runtime_error(std::string("Holder was disowned already (") + context
                                     + ").");
        }
    }

    void ensure_vptr_is_using_builtin_delete(const char *context) const {
        if (vptr_is_external_shared_ptr) {
            throw std::invalid_argument(std::string("Cannot disown external shared_ptr (")
                                        + context + ").");
        }
        if (vptr_is_using_noop_deleter) {
            throw std::invalid_argument(std::string("Cannot disown non-owning holder (") + context
                                        + ").");
        }
        if (!vptr_is_using_builtin_delete) {
            throw std::invalid_argument(std::string("Cannot disown custom deleter (") + context
                                        + ").");
        }
    }

    template <typename T, typename D>
    void ensure_compatible_rtti_uqp_del(const char *context) const {
        const std::type_info *rtti_requested = &typeid(D);
        if (!rtti_uqp_del) {
            if (!is_std_default_delete<T>(*rtti_requested)) {
                throw std::invalid_argument(std::string("Missing unique_ptr deleter (") + context
                                            + ").");
            }
            ensure_vptr_is_using_builtin_delete(context);
        } else if (!(*rtti_requested == *rtti_uqp_del)
                   && !(vptr_is_using_builtin_delete
                        && is_std_default_delete<T>(*rtti_requested))) {
            throw std::invalid_argument(std::string("Incompatible unique_ptr deleter (") + context
                                        + ").");
        }
    }

    void ensure_has_pointee(const char *context) const {
        if (!has_pointee()) {
            throw std::invalid_argument(std::string("Disowned holder (") + context + ").");
        }
    }

    void ensure_use_count_1(const char *context) const {
        if (vptr == nullptr) {
            throw std::invalid_argument(std::string("Cannot disown nullptr (") + context + ").");
        }
        // In multithreaded environments accessing use_count can lead to
        // race conditions, but in the context of Python it is a bug (elsewhere)
        // if the Global Interpreter Lock (GIL) is not being held when this code
        // is reached.
        // PYBIND11:REMINDER: This may need to be protected by a mutex in free-threaded Python.
        if (vptr.use_count() != 1) {
            throw std::invalid_argument(std::string("Cannot disown use_count != 1 (") + context
                                        + ").");
        }
    }

    void reset_vptr_deleter_armed_flag(bool armed_flag) const {
        auto *vptr_del_ptr = std::get_deleter<guarded_delete>(vptr);
        if (vptr_del_ptr == nullptr) {
            throw std::runtime_error(
                "smart_holder::reset_vptr_deleter_armed_flag() called in an invalid context.");
        }
        vptr_del_ptr->armed_flag = armed_flag;
    }

    // Caller is responsible for precondition: ensure_compatible_rtti_uqp_del<T, D>() must succeed.
    template <typename T, typename D>
    std::unique_ptr<D> extract_deleter(const char *context) const {
        const auto *gd = std::get_deleter<guarded_delete>(vptr);
        if (gd && gd->use_del_fun) {
            const auto &custom_deleter_ptr = gd->del_fun.template target<custom_deleter<T, D>>();
            if (custom_deleter_ptr == nullptr) {
                throw std::runtime_error(
                    std::string("smart_holder::extract_deleter() precondition failure (") + context
                    + ").");
            }
            static_assert(std::is_copy_constructible<D>::value,
                          "Required for compatibility with smart_holder functionality.");
            return std::unique_ptr<D>(new D(custom_deleter_ptr->deleter));
        }
        return nullptr;
    }

    static smart_holder from_raw_ptr_unowned(void *raw_ptr) {
        smart_holder hld;
        hld.vptr.reset(raw_ptr, [](void *) {});
        hld.vptr_is_using_noop_deleter = true;
        hld.is_populated = true;
        return hld;
    }

    template <typename T>
    T *as_raw_ptr_unowned() const {
        return static_cast<T *>(vptr.get());
    }

    template <typename T>
    static smart_holder from_raw_ptr_take_ownership(T *raw_ptr, bool void_cast_raw_ptr = false) {
        ensure_pointee_is_destructible<T>("from_raw_ptr_take_ownership");
        smart_holder hld;
        auto gd = make_guarded_builtin_delete<T>(true);
        if (void_cast_raw_ptr) {
            hld.vptr.reset(static_cast<void *>(raw_ptr), std::move(gd));
        } else {
            hld.vptr.reset(raw_ptr, std::move(gd));
        }
        hld.vptr_is_using_builtin_delete = true;
        hld.is_populated = true;
        return hld;
    }

    // Caller is responsible for ensuring the complex preconditions
    // (see `smart_holder_type_caster_support::load_helper`).
    void disown() {
        reset_vptr_deleter_armed_flag(false);
        is_disowned = true;
    }

    // Caller is responsible for ensuring the complex preconditions
    // (see `smart_holder_type_caster_support::load_helper`).
    void reclaim_disowned() {
        reset_vptr_deleter_armed_flag(true);
        is_disowned = false;
    }

    // Caller is responsible for ensuring the complex preconditions
    // (see `smart_holder_type_caster_support::load_helper`).
    void release_disowned() { vptr.reset(); }

    void ensure_can_release_ownership(const char *context = "ensure_can_release_ownership") const {
        ensure_is_not_disowned(context);
        ensure_vptr_is_using_builtin_delete(context);
        ensure_use_count_1(context);
    }

    // Caller is responsible for ensuring the complex preconditions
    // (see `smart_holder_type_caster_support::load_helper`).
    void release_ownership() {
        reset_vptr_deleter_armed_flag(false);
        release_disowned();
    }

    template <typename T, typename D>
    static smart_holder from_unique_ptr(std::unique_ptr<T, D> &&unq_ptr,
                                        void *void_ptr = nullptr) {
        smart_holder hld;
        hld.rtti_uqp_del = &typeid(D);
        hld.vptr_is_using_builtin_delete = is_std_default_delete<T>(*hld.rtti_uqp_del);
        guarded_delete gd{nullptr, false};
        if (hld.vptr_is_using_builtin_delete) {
            gd = make_guarded_builtin_delete<T>(true);
        } else {
            gd = make_guarded_custom_deleter<T, D>(std::move(unq_ptr.get_deleter()), true);
        }
        if (void_ptr != nullptr) {
            hld.vptr.reset(void_ptr, std::move(gd));
        } else {
            hld.vptr.reset(unq_ptr.get(), std::move(gd));
        }
        (void) unq_ptr.release();
        hld.is_populated = true;
        return hld;
    }

    template <typename T>
    static smart_holder from_shared_ptr(const std::shared_ptr<T> &shd_ptr) {
        smart_holder hld;
        hld.vptr = std::static_pointer_cast<void>(shd_ptr);
        hld.vptr_is_external_shared_ptr = true;
        hld.is_populated = true;
        return hld;
    }

    template <typename T>
    std::shared_ptr<T> as_shared_ptr() const {
        return std::static_pointer_cast<T>(vptr);
    }
};

PYBIND11_NAMESPACE_END(memory)
PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)