Allow arbitrary class_ template option ordering
The current pybind11::class_<Type, Holder, Trampoline> fixed template
ordering results in a requirement to repeat the Holder with its default
value (std::unique_ptr<Type>) argument, which is a little bit annoying:
it needs to be specified not because we want to override the default,
but rather because we need to specify the third argument.
This commit removes this limitation by making the class_ template take
the type name plus a parameter pack of options. It then extracts the
first valid holder type and the first subclass type for holder_type and
trampoline type_alias, respectively. (If unfound, both fall back to
their current defaults, `std::unique_ptr<type>` and `type`,
respectively). If any unmatched template arguments are provided, a
static assertion fails.
What this means is that you can specify or omit the arguments in any
order:
py::class_<A, PyA> c1(m, "A");
py::class_<B, PyB, std::shared_ptr<B>> c2(m, "B");
py::class_<C, std::shared_ptr<C>, PyB> c3(m, "C");
It also allows future class attributes (such as base types in the next
commit) to be passed as class template types rather than needing to use
a py::base<> wrapper.
diff --git a/docs/advanced.rst b/docs/advanced.rst
index cf588af..6a4a020 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -311,7 +311,7 @@
PYBIND11_PLUGIN(example) {
py::module m("example", "pybind11 example plugin");
- py::class_<Animal, std::unique_ptr<Animal>, PyAnimal /* <--- trampoline*/> animal(m, "Animal");
+ py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal");
animal
.def(py::init<>())
.def("go", &Animal::go);
@@ -325,9 +325,10 @@
}
Importantly, pybind11 is made aware of the trampoline trampoline helper class
-by specifying it as the *third* template argument to :class:`class_`. The
-second argument with the unique pointer is simply the default holder type used
-by pybind11. Following this, we are able to define a constructor as usual.
+by specifying it as an extra template argument to :class:`class_`. (This can
+also be combined with other template arguments such as a custom holder type;
+the order of template types does not matter). Following this, we are able to
+define a constructor as usual.
Note, however, that the above is sufficient for allowing python classes to
extend ``Animal``, but not ``Dog``: see ref:`virtual_and_inheritance` for the
@@ -453,9 +454,9 @@
.. code-block:: cpp
- py::class_<Animal, std::unique_ptr<Animal>, PyAnimal<>> animal(m, "Animal");
- py::class_<Dog, std::unique_ptr<Dog>, PyDog<>> dog(m, "Dog");
- py::class_<Husky, std::unique_ptr<Husky>, PyDog<Husky>> husky(m, "Husky");
+ py::class_<Animal, PyAnimal<>> animal(m, "Animal");
+ py::class_<Dog, PyDog<>> dog(m, "Dog");
+ py::class_<Husky, PyDog<Husky>> husky(m, "Husky");
// ... add animal, dog, husky definitions
Note that ``Husky`` did not require a dedicated trampoline template class at
@@ -525,7 +526,7 @@
PYBIND11_PLUGIN(example) {
py::module m("example", "pybind11 example plugin");
- py::class_<Animal, std::unique_ptr<Animal>, PyAnimal> animal(m, "Animal");
+ py::class_<Animal, PyAnimal> animal(m, "Animal");
animal
.def(py::init<>())
.def("go", &Animal::go);
@@ -939,11 +940,11 @@
types with internal reference counting. For the simpler C++11 unique pointers,
refer to the previous section.
-The binding generator for classes, :class:`class_`, takes an optional second
-template type, which denotes a special *holder* type that is used to manage
-references to the object. When wrapping a type named ``Type``, the default
-value of this template parameter is ``std::unique_ptr<Type>``, which means that
-the object is deallocated when Python's reference count goes to zero.
+The binding generator for classes, :class:`class_`, can be passed a template
+type that denotes a special *holder* type that is used to manage references to
+the object. If no such holder type template argument is given, the default for
+a type named ``Type`` is ``std::unique_ptr<Type>``, which means that the object
+is deallocated when Python's reference count goes to zero.
It is possible to switch to other types of reference counting wrappers or smart
pointers, which is useful in codebases that rely on them. For instance, the
@@ -977,6 +978,8 @@
.. code-block:: cpp
+ PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>);
+
class Child { };
class Parent {
@@ -1089,7 +1092,7 @@
is responsible for managing the lifetime of instances will reference the
destructor even if no deallocations ever take place. In order to expose classes
with private or protected destructors, it is possible to override the holder
-type via the second argument to ``class_``. Pybind11 provides a helper class
+type via a holder type argument to ``class_``. Pybind11 provides a helper class
``py::nodelete`` that disables any destructor invocations. In this case, it is
crucial that instances are deallocated on the C++ side to avoid memory leaks.