Redesigned virtual call mechanism and user-facing syntax (breaking change!)
Sergey Lyskov pointed out that the trampoline mechanism used to override
virtual methods from within Python caused unnecessary overheads when
instantiating the original (i.e. non-extended) class.
This commit removes this inefficiency, but some syntax changes were
needed to achieve this. Projects using this features will need to make a
few changes:
In particular, the example below shows the old syntax to instantiate a
class with a trampoline:
class_<TrampolineClass>("MyClass")
.alias<MyClass>()
....
This is what should be used now:
class_<MyClass, std::unique_ptr<MyClass, TrampolineClass>("MyClass")
....
Importantly, the trampoline class is now specified as the *third*
argument to the class_ template, and the alias<..>() call is gone. The
second argument with the unique pointer is simply the default holder
type used by pybind11.
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 032cf85..ba95c20 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -283,9 +283,8 @@
PYBIND11_PLUGIN(example) {
py::module m("example", "pybind11 example plugin");
- py::class_<PyAnimal> animal(m, "Animal");
+ py::class_<Animal, std::unique_ptr<Animal>, PyAnimal /* <--- trampoline*/> animal(m, "Animal");
animal
- .alias<Animal>()
.def(py::init<>())
.def("go", &Animal::go);
@@ -297,10 +296,10 @@
return m.ptr();
}
-Importantly, the trampoline helper class is used as the template argument to
-:class:`class_`, and a call to :func:`class_::alias` informs the binding
-generator that this is merely an alias for the underlying type ``Animal``.
-Following this, we are able to define a constructor as usual.
+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.
The Python session below shows how to override ``Animal::go`` and invoke it via
a virtual method call.
@@ -321,12 +320,12 @@
.. warning::
- Both :func:`PYBIND11_OVERLOAD` and :func:`PYBIND11_OVERLOAD_PURE` are
- macros, which means that they can get confused by commas in a template
- argument such as ``PYBIND11_OVERLOAD(MyReturnValue<T1, T2>, myFunc)``. In
- this case, the preprocessor assumes that the comma indicates the beginnning
- of the next parameter. Use a ``typedef`` to bind the template to another
- name and use it in the macro to avoid this problem.
+ The :func:`PYBIND11_OVERLOAD_*` calls are all just macros, which means that
+ they can get confused by commas in a template argument such as
+ ``PYBIND11_OVERLOAD(MyReturnValue<T1, T2>, myFunc)``. In this case, the
+ preprocessor assumes that the comma indicates the beginnning of the next
+ parameter. Use a ``typedef`` to bind the template to another name and use
+ it in the macro to avoid this problem.
.. seealso::
@@ -369,9 +368,8 @@
PYBIND11_PLUGIN(example) {
py::module m("example", "pybind11 example plugin");
- py::class_<PyAnimal> animal(m, "Animal");
+ py::class_<Animal, std::unique_ptr<Animal>, PyAnimal> animal(m, "Animal");
animal
- .alias<Animal>()
.def(py::init<>())
.def("go", &Animal::go);
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 632f2be..7cf26e1 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -5,9 +5,11 @@
1.8 (Not yet released)
----------------------
+* Redesigned virtual call mechanism and user-facing syntax (breaking change!)
* Prevent implicit conversion of floating point values to integral types in
function arguments
* Transparent conversion of sparse and dense Eigen data types
+* ``std::vector<>`` type bindings analogous to Boost.Python's ``indexing_suite``
* Fixed incorrect default return value policy for functions returning a shared
pointer
* Don't allow casting a ``None`` value into a C++ lvalue reference
@@ -16,10 +18,19 @@
* Extended ``str`` type to also work with ``bytes`` instances
* Added ``[[noreturn]]`` attribute to ``pybind11_fail()`` to quench some
compiler warnings
+* List function arguments in exception text when the dispatch code cannot find
+ a matching overload
* Various minor ``iterator`` and ``make_iterator()`` improvements
+* Transparently support ``__bool__`` on Python 2.x and Python 3.x
+* Fixed issue with destructor of unpickled object not being called
* Minor CMake build system improvements on Windows
* Many ``mkdoc.py`` improvements (enumerations, template arguments, ``DOC()``
macro accepts more arguments)
+* New ``pybind11::args`` and ``pybind11::kwargs`` types to create functions which
+ take an arbitrary number of arguments and keyword arguments
+* New syntax to call a Python function from C++ using ``*args`` and ``*kwargs``
+* Added an ``ExtraFlags`` template argument to the NumPy ``array_t<>`` wrapper. This
+ can be used to disable an enforced cast that may lose precision
* Documentation improvements (pickling support, ``keep_alive``)
1.7 (April 30, 2016)