Implement py::init_alias<>() constructors
This commit adds support for forcing alias type initialization by
defining constructors with `py::init_alias<arg1, arg2>()` instead of
`py::init<arg1, arg2>()`. Currently py::init<> only results in Alias
initialization if the type is extended in python, or the given
arguments can't be used to construct the base type, but can be used to
construct the alias. py::init_alias<>, in contrast, always invokes the
constructor of the alias type.
It looks like this was already the intention of
`py::detail::init_alias`, which was forward-declared in
86d825f3302701d81414ddd3d38bcd09433076bc, but was apparently never
finished: despite the existance of a .def method accepting it, the
`detail::init_alias` class isn't actually defined anywhere.
This commit completes the feature (or possibly repurposes it), allowing
declaration of classes that will always initialize the trampoline which
is (as I argued in #397) sometimes useful.
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 748f91e..400a926 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -477,6 +477,36 @@
See the file :file:`tests/test_virtual_functions.cpp` for complete examples
using both the duplication and templated trampoline approaches.
+Extended trampoline class functionality
+=======================================
+
+The trampoline classes described in the previous sections are, by default, only
+initialized when needed. More specifically, they are initialized when a python
+class actually inherits from a registered type (instead of merely creating an
+instance of the registered type), or when a registered constructor is only
+valid for the trampoline class but not the registered class. This is primarily
+for performance reasons: when the trampoline class is not needed for anything
+except virtual method dispatching, not initializing the trampoline class
+improves performance by avoiding needing to do a run-time check to see if the
+inheriting python instance has an overloaded method.
+
+Sometimes, however, it is useful to always initialize a trampoline class as an
+intermediate class that does more than just handle virtual method dispatching.
+For example, such a class might perform extra class initialization, extra
+destruction operations, and might define new members and methods to enable a
+more python-like interface to a class.
+
+In order to tell pybind11 that it should *always* initialize the trampoline
+class when creating new instances of a type, the class constructors should be
+declared using ``py::init_alias<Args, ...>()`` instead of the usual
+``py::init<Args, ...>()``. This forces construction via the trampoline class,
+ensuring member initialization and (eventual) destruction.
+
+.. seealso::
+
+ See the file :file:`tests/test_alias_initialization.cpp` for complete examples
+ showing both normal and forced trampoline instantiation.
+
.. _macro_notes:
General notes regarding convenience macros
diff --git a/include/pybind11/pybind11.h b/include/pybind11/pybind11.h
index 8f88d36..2a47eb9 100644
--- a/include/pybind11/pybind11.h
+++ b/include/pybind11/pybind11.h
@@ -1107,17 +1107,17 @@
NAMESPACE_BEGIN(detail)
template <typename... Args> struct init {
- template <typename Class, typename... Extra, typename std::enable_if<!Class::has_alias, int>::type = 0>
- void execute(Class &cl, const Extra&... extra) const {
+ template <typename Class, typename... Extra, enable_if_t<!Class::has_alias, int> = 0>
+ static void execute(Class &cl, const Extra&... extra) {
using Base = typename Class::type;
/// Function which calls a specific C++ in-place constructor
cl.def("__init__", [](Base *self_, Args... args) { new (self_) Base(args...); }, extra...);
}
template <typename Class, typename... Extra,
- typename std::enable_if<Class::has_alias &&
- std::is_constructible<typename Class::type, Args...>::value, int>::type = 0>
- void execute(Class &cl, const Extra&... extra) const {
+ enable_if_t<Class::has_alias &&
+ std::is_constructible<typename Class::type, Args...>::value, int> = 0>
+ static void execute(Class &cl, const Extra&... extra) {
using Base = typename Class::type;
using Alias = typename Class::type_alias;
handle cl_type = cl;
@@ -1130,14 +1130,22 @@
}
template <typename Class, typename... Extra,
- typename std::enable_if<Class::has_alias &&
- !std::is_constructible<typename Class::type, Args...>::value, int>::type = 0>
- void execute(Class &cl, const Extra&... extra) const {
+ enable_if_t<Class::has_alias &&
+ !std::is_constructible<typename Class::type, Args...>::value, int> = 0>
+ static void execute(Class &cl, const Extra&... extra) {
+ init_alias<Args...>::execute(cl, extra...);
+ }
+};
+template <typename... Args> struct init_alias {
+ template <typename Class, typename... Extra,
+ enable_if_t<Class::has_alias && std::is_constructible<typename Class::type_alias, Args...>::value, int> = 0>
+ static void execute(Class &cl, const Extra&... extra) {
using Alias = typename Class::type_alias;
cl.def("__init__", [](Alias *self_, Args... args) { new (self_) Alias(args...); }, extra...);
}
};
+
inline void keep_alive_impl(handle nurse, handle patient) {
/* Clever approach based on weak references taken from Boost.Python */
if (!nurse || !patient)
@@ -1172,6 +1180,7 @@
NAMESPACE_END(detail)
template <typename... Args> detail::init<Args...> init() { return detail::init<Args...>(); }
+template <typename... Args> detail::init_alias<Args...> init_alias() { return detail::init_alias<Args...>(); }
template <typename Iterator,
typename Sentinel,
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 6d72ad7..506789a 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -4,6 +4,7 @@
endif()
set(PYBIND11_TEST_FILES
+ test_alias_initialization.cpp
test_buffers.cpp
test_callbacks.cpp
test_class_args.cpp
diff --git a/tests/test_alias_initialization.cpp b/tests/test_alias_initialization.cpp
new file mode 100644
index 0000000..48e5956
--- /dev/null
+++ b/tests/test_alias_initialization.cpp
@@ -0,0 +1,62 @@
+/*
+ tests/test_alias_initialization.cpp -- test cases and example of different trampoline
+ initialization modes
+
+ Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>, Jason Rhinelander <jason@imaginary.ca>
+
+ All rights reserved. Use of this source code is governed by a
+ BSD-style license that can be found in the LICENSE file.
+*/
+
+#include "pybind11_tests.h"
+
+test_initializer alias_initialization([](py::module &m) {
+ // don't invoke Python dispatch classes by default when instantiating C++ classes that were not
+ // extended on the Python side
+ struct A {
+ virtual ~A() {}
+ virtual void f() { py::print("A.f()"); }
+ };
+
+ struct PyA : A {
+ PyA() { py::print("PyA.PyA()"); }
+ ~PyA() { py::print("PyA.~PyA()"); }
+
+ void f() override {
+ py::print("PyA.f()");
+ PYBIND11_OVERLOAD(void, A, f);
+ }
+ };
+
+ auto call_f = [](A *a) { a->f(); };
+
+ py::class_<A, PyA>(m, "A")
+ .def(py::init<>())
+ .def("f", &A::f);
+
+ m.def("call_f", call_f);
+
+
+ // ... unless we explicitly request it, as in this example:
+ struct A2 {
+ virtual ~A2() {}
+ virtual void f() { py::print("A2.f()"); }
+ };
+
+ struct PyA2 : A2 {
+ PyA2() { py::print("PyA2.PyA2()"); }
+ ~PyA2() { py::print("PyA2.~PyA2()"); }
+ void f() override {
+ py::print("PyA2.f()");
+ PYBIND11_OVERLOAD(void, A2, f);
+ }
+ };
+
+ py::class_<A2, PyA2>(m, "A2")
+ .def(py::init_alias<>())
+ .def("f", &A2::f);
+
+ m.def("call_f", [](A2 *a2) { a2->f(); });
+
+});
+
diff --git a/tests/test_alias_initialization.py b/tests/test_alias_initialization.py
new file mode 100644
index 0000000..b6d9e84
--- /dev/null
+++ b/tests/test_alias_initialization.py
@@ -0,0 +1,80 @@
+import pytest
+import gc
+
+def test_alias_delay_initialization(capture, msg):
+
+ # A only initializes its trampoline class when we inherit from it; if we
+ # just create and use an A instance directly, the trampoline initialization
+ # is bypassed and we only initialize an A() instead (for performance
+ # reasons)
+ from pybind11_tests import A, call_f
+
+ class B(A):
+ def __init__(self):
+ super(B, self).__init__()
+
+ def f(self):
+ print("In python f()")
+
+ # C++ version
+ with capture:
+ a = A()
+ call_f(a)
+ del a
+ gc.collect()
+ assert capture == "A.f()"
+
+ # Python version
+ with capture:
+ b = B()
+ call_f(b)
+ del b
+ gc.collect()
+ assert capture == """
+ PyA.PyA()
+ PyA.f()
+ In python f()
+ PyA.~PyA()
+ """
+
+def test_alias_delay_initialization(capture, msg):
+ from pybind11_tests import A2, call_f
+
+ # A2, unlike the above, is configured to always initialize the alias; while
+ # the extra initialization and extra class layer has small virtual dispatch
+ # performance penalty, it also allows us to do more things with the
+ # trampoline class such as defining local variables and performing
+ # construction/destruction.
+
+ class B2(A2):
+ def __init__(self):
+ super(B2, self).__init__()
+
+ def f(self):
+ print("In python B2.f()")
+
+ # No python subclass version
+ with capture:
+ a2 = A2()
+ call_f(a2)
+ del a2
+ gc.collect()
+ assert capture == """
+ PyA2.PyA2()
+ PyA2.f()
+ A2.f()
+ PyA2.~PyA2()
+ """
+
+ # Python subclass version
+ with capture:
+ b2 = B2()
+ call_f(b2)
+ del b2
+ gc.collect()
+ assert capture == """
+ PyA2.PyA2()
+ PyA2.f()
+ In python B2.f()
+ PyA2.~PyA2()
+ """
diff --git a/tests/test_issues.cpp b/tests/test_issues.cpp
index c5314bc..eb23919 100644
--- a/tests/test_issues.cpp
+++ b/tests/test_issues.cpp
@@ -117,30 +117,6 @@
m2.def("expect_float", [](float f) { return f; });
m2.def("expect_int", [](int i) { return i; });
- // (no id): don't invoke Python dispatch code when instantiating C++
- // classes that were not extended on the Python side
- struct A {
- virtual ~A() {}
- virtual void f() { py::print("A.f()"); }
- };
-
- struct PyA : A {
- PyA() { py::print("PyA.PyA()"); }
-
- void f() override {
- py::print("PyA.f()");
- PYBIND11_OVERLOAD(void, A, f);
- }
- };
-
- auto call_f = [](A *a) { a->f(); };
-
- pybind11::class_<A, std::unique_ptr<A>, PyA>(m2, "A")
- .def(py::init<>())
- .def("f", &A::f);
-
- m2.def("call_f", call_f);
-
try {
py::class_<Placeholder>(m2, "Placeholder");
throw std::logic_error("Expected an exception!");
diff --git a/tests/test_issues.py b/tests/test_issues.py
index 2af6f1c..92b8dcd 100644
--- a/tests/test_issues.py
+++ b/tests/test_issues.py
@@ -79,30 +79,6 @@
"""
assert expect_float(12) == 12
- from pybind11_tests.issues import A, call_f
-
- class B(A):
- def __init__(self):
- super(B, self).__init__()
-
- def f(self):
- print("In python f()")
-
- # C++ version
- with capture:
- a = A()
- call_f(a)
- assert capture == "A.f()"
-
- # Python version
- with capture:
- b = B()
- call_f(b)
- assert capture == """
- PyA.PyA()
- PyA.f()
- In python f()
- """
def test_str_issue(msg):