[smart_holder] Introduce PYBIND11_SMART_HOLDER_DISABLE option. (#5348)

* Step 1: Establish new `PYBIND11_SMART_HOLDER_ENABLED` macro, but only under include/pybind11/

At the stage `PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT` and `PYBIND11_SMART_HOLDER_ENABLED` are still equivalent.

* Systematically replace all `PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT` with `PYBIND11_SMART_HOLDER_ENABLED` under tests/ and ubench/

As at the previous stage, `PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT` and `PYBIND11_SMART_HOLDER_ENABLED` are still equivalent.

* Introduce `PYBIND11_SMART_HOLDER_DISABLE` option.

* `#ifdef` out entire `wrap()` function to avoid `unused-parameter` warning-as-error under macos-13

```
/Users/runner/work/pybind11/pybind11/tests/test_class_sh_trampoline_basic.cpp:67:23: error: unused parameter 'm' [-Werror,-Wunused-parameter]
void wrap(py::module_ m, const char *py_class_name) {
                      ^
/Users/runner/work/pybind11/pybind11/tests/test_class_sh_trampoline_basic.cpp:67:38: error: unused parameter 'py_class_name' [-Werror,-Wunused-parameter]
void wrap(py::module_ m, const char *py_class_name) {
                                     ^
2 errors generated.
```

Author: rwgk

.github/workflows/ci.yml

@@ -68,6 +68,8 @@ jobs:
           # Extra ubuntu latest job
           - runs-on: ubuntu-latest
             python: '3.11'
+          # Exercise PYBIND11_USE_SMART_HOLDER_AS_DEFAULT
+          # with recent (or ideally latest) released Python version.
           - runs-on: ubuntu-latest
             python: '3.12'
             args: >
@@ -80,6 +82,20 @@ jobs:
             python: '3.12'
             args: >
               -DCMAKE_CXX_FLAGS="/DPYBIND11_USE_SMART_HOLDER_AS_DEFAULT /GR /EHsc"
+          # Exercise PYBIND11_SMART_HOLDER_DISABLE
+          # with recent (or ideally latest) released Python version.
+          - runs-on: ubuntu-latest
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="-DPYBIND11_SMART_HOLDER_DISABLE"
+          - runs-on: macos-13
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="-DPYBIND11_SMART_HOLDER_DISABLE"
+          - runs-on: windows-2022
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="/DPYBIND11_SMART_HOLDER_DISABLE /GR /EHsc"
 
     name: "🐍 ${{ matrix.python }} • ${{ matrix.runs-on }} • x64 ${{ matrix.args }}"
     runs-on: ${{ matrix.runs-on }}

include/pybind11/cast.h

@@ -836,7 +836,7 @@ struct copyable_holder_caster : public type_caster_base<type> {
     holder_type holder;
 };
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 
 template <typename, typename SFINAE = void>
 struct copyable_holder_caster_shared_ptr_with_smart_holder_support_enabled : std::true_type {};
@@ -968,7 +968,7 @@ struct copyable_holder_caster<
     std::shared_ptr<type> shared_ptr_storage;
 };
 
-#endif // PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#endif // PYBIND11_SMART_HOLDER_ENABLED
 
 /// Specialize for the common std::shared_ptr, so users don't need to
 template <typename T>
@@ -990,7 +990,7 @@ struct move_only_holder_caster {
     static constexpr auto name = type_caster_base<type>::name;
 };
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 
 template <typename, typename SFINAE = void>
 struct move_only_holder_caster_unique_ptr_with_smart_holder_support_enabled : std::true_type {};
@@ -1129,7 +1129,7 @@ struct move_only_holder_caster<
     std::shared_ptr<std::unique_ptr<type, deleter>> unique_ptr_storage;
 };
 
-#endif // PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#endif // PYBIND11_SMART_HOLDER_ENABLED
 
 template <typename type, typename deleter>
 class type_caster<std::unique_ptr<type, deleter>>
@@ -1167,7 +1167,7 @@ struct is_holder_type
 template <typename base, typename deleter>
 struct is_holder_type<base, std::unique_ptr<base, deleter>> : std::true_type {};
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 template <typename base>
 struct is_holder_type<base, smart_holder> : std::true_type {};
 #endif

include/pybind11/detail/init.h

@@ -198,7 +198,7 @@ void construct(value_and_holder &v_h, Alias<Class> &&result, bool) {
     v_h.value_ptr() = new Alias<Class>(std::move(result));
 }
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 
 template <typename T, typename D>
 smart_holder init_smart_holder_from_unique_ptr(std::unique_ptr<T, D> &&unq_ptr,
@@ -268,7 +268,7 @@ void construct(value_and_holder &v_h,
     v_h.type->init_instance(v_h.inst, &smhldr);
 }
 
-#endif // PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#endif // PYBIND11_SMART_HOLDER_ENABLED
 
 // Implementing class for py::init<...>()
 template <typename... Args>

include/pybind11/detail/internals.h

@@ -252,6 +252,11 @@ enum class holder_enum_t : uint8_t {
 
 #endif
 
+#if defined(PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT)                                     \
+    && !defined(PYBIND11_SMART_HOLDER_DISABLE)
+#    define PYBIND11_SMART_HOLDER_ENABLED
+#endif
+
 /// Additional type information which does not fit into the PyTypeObject.
 /// Changes to this struct also require bumping `PYBIND11_INTERNALS_VERSION`.
 struct type_info {

include/pybind11/detail/type_caster_base.h

@@ -473,7 +473,7 @@ inline PyThreadState *get_thread_state_unchecked() {
 void keep_alive_impl(handle nurse, handle patient);
 inline PyObject *make_new_instance(PyTypeObject *type);
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 
 // PYBIND11:REMINDER: Needs refactoring of existing pybind11 code.
 inline bool deregister_instance(instance *self, void *valptr, const type_info *tinfo);
@@ -830,7 +830,7 @@ struct load_helper : value_and_holder_helper {
 
 PYBIND11_NAMESPACE_END(smart_holder_type_caster_support)
 
-#endif // PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#endif // PYBIND11_SMART_HOLDER_ENABLED
 
 class type_caster_generic {
 public:
@@ -936,7 +936,7 @@ class type_caster_generic {
 
     // Base methods for generic caster; there are overridden in copyable_holder_caster
     void load_value(value_and_holder &&v_h) {
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
         if (typeinfo->holder_enum_v == detail::holder_enum_t::smart_holder) {
             smart_holder_type_caster_support::value_and_holder_helper v_h_helper;
             v_h_helper.loaded_v_h = v_h;

include/pybind11/detail/using_smart_holder.h

@@ -9,19 +9,19 @@
 
 #include <type_traits>
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 #    include "struct_smart_holder.h"
 #endif
 
 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 using pybindit::memory::smart_holder;
 #endif
 
 PYBIND11_NAMESPACE_BEGIN(detail)
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 template <typename H>
 using is_smart_holder = std::is_same<H, smart_holder>;
 #else

include/pybind11/pybind11.h

@@ -1631,7 +1631,7 @@ PYBIND11_NAMESPACE_END(detail)
 template <typename T, typename D, typename SFINAE = void>
 struct property_cpp_function : detail::property_cpp_function_classic<T, D> {};
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 
 PYBIND11_NAMESPACE_BEGIN(detail)
 
@@ -1810,10 +1810,9 @@ struct property_cpp_function<
         detail::both_t_and_d_use_type_caster_base<T, typename D::element_type>>::value>>
     : detail::property_cpp_function_sh_unique_ptr_member<T, D> {};
 
-#endif // PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#endif // PYBIND11_SMART_HOLDER_ENABLED
 
-#if defined(PYBIND11_USE_SMART_HOLDER_AS_DEFAULT)                                                 \
-    && defined(PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT)
+#if defined(PYBIND11_USE_SMART_HOLDER_AS_DEFAULT) && defined(PYBIND11_SMART_HOLDER_ENABLED)
 // NOTE: THIS IS MEANT FOR STRESS-TESTING ONLY!
 //       As of PR #5257, for production use, there is no longer a strong reason to make
 //       smart_holder the default holder:
@@ -1881,7 +1880,7 @@ class class_ : public detail::generic_type {
         // A more fitting name would be uses_unique_ptr_holder.
         record.default_holder = detail::is_instantiation<std::unique_ptr, holder_type>::value;
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
         if (detail::is_instantiation<std::unique_ptr, holder_type>::value) {
             record.holder_enum_v = detail::holder_enum_t::std_unique_ptr;
         } else if (detail::is_instantiation<std::shared_ptr, holder_type>::value) {
@@ -2226,7 +2225,7 @@ class class_ : public detail::generic_type {
         init_holder(inst, v_h, (const holder_type *) holder_ptr, v_h.value_ptr<type>());
     }
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 
     template <typename WrappedType>
     static bool try_initialization_using_shared_from_this(holder_type *, WrappedType *, ...) {
@@ -2287,7 +2286,7 @@ class class_ : public detail::generic_type {
         v_h.set_holder_constructed();
     }
 
-#endif // PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#endif // PYBIND11_SMART_HOLDER_ENABLED
 
     /// Deallocates an instance; via holder, if constructed; otherwise via operator delete.
     static void dealloc(detail::value_and_holder &v_h) {
@@ -2329,7 +2328,7 @@ class class_ : public detail::generic_type {
     }
 };
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 
 // Supports easier switching between py::class_<T> and py::class_<T, py::smart_holder>:
 // users can simply replace the `_` in `class_` with `h` or vice versa.

include/pybind11/trampoline_self_life_support.h

@@ -6,7 +6,7 @@
 
 #include "detail/internals.h"
 
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
 
 #    include "detail/common.h"
 #    include "detail/using_smart_holder.h"
@@ -63,4 +63,4 @@ struct trampoline_self_life_support {
 
 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
 
-#endif // PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#endif // PYBIND11_SMART_HOLDER_ENABLED

tests/test_class.cpp

@@ -93,7 +93,7 @@ TEST_SUBMODULE(class_, m) {
     struct ToBeHeldByUniquePtr {};
     py::class_<ToBeHeldByUniquePtr, std::unique_ptr<ToBeHeldByUniquePtr>>(m, "ToBeHeldByUniquePtr")
         .def(py::init<>());
-#ifdef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#ifdef PYBIND11_SMART_HOLDER_ENABLED
     m.def("pass_unique_ptr", [](std::unique_ptr<ToBeHeldByUniquePtr> &&) {});
 #else
     m.attr("pass_unique_ptr") = py::none();

tests/test_class_sh_basic.cpp

@@ -156,8 +156,8 @@ namespace pybind11_tests {
 namespace class_sh_basic {
 
 TEST_SUBMODULE(class_sh_basic, m) {
-    m.attr("defined_PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT") =
-#ifndef PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+    m.attr("defined_PYBIND11_SMART_HOLDER_ENABLED") =
+#ifndef PYBIND11_SMART_HOLDER_ENABLED
         false;
 #else
         true;
@@ -260,7 +260,7 @@ TEST_SUBMODULE(class_sh_basic, m) {
           []() { return CastUnusualOpRefConstRef(LocalUnusualOpRef()); });
     m.def("CallCastUnusualOpRefMovable",
           []() { return CastUnusualOpRefMovable(LocalUnusualOpRef()); });
-#endif // PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT
+#endif // PYBIND11_SMART_HOLDER_ENABLED
 }
 
 } // namespace class_sh_basic