Add basic support for tag-based static polymorphism (#1326)
* Add basic support for tag-based static polymorphism
Sometimes it is possible to look at a C++ object and know what its dynamic type is,
even if it doesn't use C++ polymorphism, because instances of the object and its
subclasses conform to some other mechanism for being self-describing; for example,
perhaps there's an enumerated "tag" or "kind" member in the base class that's always
set to an indication of the correct type. This might be done for performance reasons,
or to permit most-derived types to be trivially copyable. One of the most widely-known
examples is in LLVM: https://llvm.org/docs/HowToSetUpLLVMStyleRTTI.html
This PR permits pybind11 to be informed of such conventions via a new specializable
detail::polymorphic_type_hook<> template, which generalizes the previous logic for
determining the runtime type of an object based on C++ RTTI. Implementors provide
a way to map from a base class object to a const std::type_info* for the dynamic
type; pybind11 then uses this to ensure that casting a Base* to Python creates a
Python object that knows it's wrapping the appropriate sort of Derived.
There are a number of restrictions with this tag-based static polymorphism support
compared to pybind11's existing support for built-in C++ polymorphism:
- there is no support for this-pointer adjustment, so only single inheritance is permitted
- there is no way to make C++ code call new Python-provided subclasses
- when binding C++ classes that redefine a method in a subclass, the .def() must be
repeated in the binding for Python to know about the update
But these are not much of an issue in practice in many cases, the impact on the
complexity of pybind11's innards is minimal and localized, and the support for
automatic downcasting improves usability a great deal.
diff --git a/docs/classes.rst b/docs/classes.rst
index 75a8fb2..1deec9b 100644
--- a/docs/classes.rst
+++ b/docs/classes.rst
@@ -228,8 +228,8 @@
.. _inheritance:
-Inheritance and automatic upcasting
-===================================
+Inheritance and automatic downcasting
+=====================================
Suppose now that the example consists of two data structures with an
inheritance relationship:
@@ -298,7 +298,7 @@
>>> p = example.pet_store()
>>> type(p) # `Dog` instance behind `Pet` pointer
- Pet # no pointer upcasting for regular non-polymorphic types
+ Pet # no pointer downcasting for regular non-polymorphic types
>>> p.bark()
AttributeError: 'Pet' object has no attribute 'bark'
@@ -330,11 +330,11 @@
>>> p = example.pet_store2()
>>> type(p)
- PolymorphicDog # automatically upcast
+ PolymorphicDog # automatically downcast
>>> p.bark()
u'woof!'
-Given a pointer to a polymorphic base, pybind11 performs automatic upcasting
+Given a pointer to a polymorphic base, pybind11 performs automatic downcasting
to the actual derived type. Note that this goes beyond the usual situation in
C++: we don't just get access to the virtual functions of the base, we get the
concrete derived type including functions and attributes that the base type may