pybind11

When exposing C++ classes with virtual methods to Python, you must use a trampoline class to allow Python to override those methods.

Key Requirements:

1. Override every virtual method: For every method you want Python to be able to override, the trampoline class must provide an override using PYBIND11_OVERRIDE or PYBIND11_OVERRIDE_PURE.
2. Inheritance chain: If you have a hierarchy (e.g., Animal -> Dog -> Husky), every level in the hierarchy that is registered with pybind11 requires its own trampoline class, even if that specific level doesn't introduce new virtual methods. This is because the trampoline is needed to bridge the virtual dispatch for the entire chain.
3. Trailing commas: When using PYBIND11_OVERRIDE for functions with no arguments, you must include a trailing comma (e.g., PYBIND11_OVERRIDE(type, Class, name, )) to ensure portable implementation.

Optimization: Template Trampolines

To avoid duplicating override logic across multiple trampoline classes in a deep hierarchy, you can use template trampoline classes. This allows you to define the override logic once in a base template and reuse it for derived classes.

// Example of a template trampoline approach
template <class AnimalBase = Animal>
class PyAnimal : public AnimalBase, public py::trampoline_self_life_support {
public:
    using AnimalBase::AnimalBase;
    std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE(std::string, AnimalBase, go, n_times); }
    std::string name() override { PYBIND11_OVERRIDE(std::string, AnimalBase, name, ); }
};

template <class DogBase = Dog>
class PyDog : public PyAnimal<DogBase>, public py::trampoline_self_life_support {
public:
    using PyAnimal<DogBase>::PyAnimal;
    std::string go(int n_times) override { PYBIND11_OVERRIDE(std::string, DogBase, go, n_times); }
    std::string bark() override { PYBIND11_OVERRIDE(std::string, DogBase, bark, ); }
};

// Registration
py::class_<Animal, PyAnimal<>, py::smart_holder> animal(m, "Animal");
py::class_<Dog, Animal, PyDog<>, py::smart_holder> dog(m, "Dog");

When defining a class with py::class_<T>, you can specify a holder type to manage object references. Note that a single type T (and its derivatives) can only use one holder type.

1. std::unique_ptr<T> (The Default)

If no holder is provided, py::class_<T> defaults to std::unique_ptr<T>.

• Pros: Works as expected for most simple cases.
• Cons: Does not support passing a std::unique_ptr from Python back to C++ (e.g., as a function argument). It also involves a reinterpret_cast for base/derived classes which is technically undefined behavior.

2. std::shared_ptr<T> (Manual)

You can explicitly use std::shared_ptr:

py::class_<Example, std::shared_ptr<Example>>(m, "Example");

• Cons: Because only one holder can be used per type, if you choose std::shared_ptr, you cannot pass std::unique_ptr from C++ to Python. This can lead to runtime segmentation faults.

Comparison Summary

When using factory functions with classes that require a trampoline (alias class) for overriding virtual functions in Python, you have three strategies:

1. Rvalue-reference constructor: Add a constructor to your alias class that takes a base value by rvalue-reference (Example &&base). pybind11 will use this to move the value returned by the factory into the alias instance.
2. Dual factory functions: Provide two factory functions to .def(py::init(...)). The first is used when no alias is required (standard usage), and the second is used when an alias is required (when the class is inherited from in Python).
3. Always return an alias: Specify a single factory function that always returns an alias instance (similar to py::init_alias<...>()).

#include <pybind11/factory.h>
class Example {
public:
    virtual ~Example() = default;
};
class PyExample : public Example, public py::trampoline_self_life_support {
public:
    using Example::Example;
    PyExample(Example &&base) : Example(std::move(base)) {}
};

py::class_<Example, PyExample, py::smart_holder>(m, "Example")
    // 1. Returns an Example pointer. If PyExample is needed, it's moved via the rvalue constructor.
    .def(py::init([]() { return new Example(); }))
    // 2. Two callbacks: first for no alias, second for when alias is needed
    .def(py::init([]() { return new Example(); },
                  []() { return new PyExample(); }))
    // 3. *Always* returns an alias instance
    .def(py::init([]() { return new PyExample(); }));