pybind11/example
Jason Rhinelander ed14879a19 Move support for return values of called Python functions
Currently pybind11 always translates values returned by Python functions
invoked from C++ code by copying, even when moving is feasible--and,
more importantly, even when moving is required.

The first, and relatively minor, concern is that moving may be
considerably more efficient for some types.  The second problem,
however, is more serious: there's currently no way python code can
return a non-copyable type to C++ code.

I ran into this while trying to add a PYBIND11_OVERLOAD of a virtual
method that returns just such a type: it simply fails to compile because
this:

    overload = ...
    overload(args).template cast<ret_type>();

involves a copy: overload(args) returns an object instance, and the
invoked object::cast() loads the returned value, then returns a copy of
the loaded value.

We can, however, safely move that returned value *if* the object has the
only reference to it (i.e. if ref_count() == 1) and the object is
itself temporary (i.e. if it's an rvalue).

This commit does that by adding an rvalue-qualified object::cast()
method that allows the returned value to be move-constructed out of the
stored instance when feasible.

This basically comes down to three cases:

- For objects that are movable but not copyable, we always try the move,
  with a runtime exception raised if this would involve moving a value
  with multiple references.
- When the type is both movable and non-trivially copyable, the move
  happens only if the invoked object has a ref_count of 1, otherwise the
  object is copied.  (Trivially copyable types are excluded from this
  case because they are typically just collections of primitive types,
  which can be copied just as easily as they can be moved.)
- Non-movable and trivially copy constructible objects are simply
  copied.

This also adds examples to example-virtual-functions that shows both a
non-copyable object and a movable/copyable object in action: the former
raises an exception if returned while holding a reference, the latter
invokes a move constructor if unreferenced, or a copy constructor if
referenced.

Basically this allows code such as:

    class MyClass(Pybind11Class):
        def somemethod(self, whatever):
            mt = MovableType(whatever)
            # ...
            return mt

which allows the MovableType instance to be returned to the C++ code
via its move constructor.

Of course if you attempt to violate this by doing something like:

    self.value = MovableType(whatever)
    return self.value

you get an exception--but right now, the pybind11-side of that code
won't compile at all.
2016-08-08 13:47:37 -04:00
..
CMakeLists.txt Improve CI test coverage: eigen, numpy and C++14 2016-07-30 17:18:33 +02:00
eigen.cpp Eigen support for special matrix objects 2016-08-04 15:24:41 -04:00
eigen.py Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
eigen.ref Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
example-arg-keywords-and-defaults.cpp Use generic arg names for functions without explicitly named arguments 2016-08-04 23:45:24 +02:00
example-arg-keywords-and-defaults.py Use generic arg names for functions without explicitly named arguments 2016-08-04 23:45:24 +02:00
example-arg-keywords-and-defaults.ref Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
example-buffers.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-buffers.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-buffers.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-callbacks.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-callbacks.py Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
example-callbacks.ref Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
example-constants-and-functions.cpp Fix scoped enums and add scoped enum example 2016-08-04 00:01:39 -04:00
example-constants-and-functions.py Only support ==/!= int on unscoped enums 2016-08-04 00:21:37 -04:00
example-constants-and-functions.ref Only support ==/!= int on unscoped enums 2016-08-04 00:21:37 -04:00
example-custom-exceptions.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-custom-exceptions.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-custom-exceptions.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-eval_call.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-eval.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-eval.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-eval.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-inheritance.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-inheritance.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-inheritance.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-keep-alive.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-keep-alive.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-keep-alive.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-methods-and-attributes.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-methods-and-attributes.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-methods-and-attributes.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-modules.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-modules.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-modules.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-numpy-vectorize.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-numpy-vectorize.py Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
example-numpy-vectorize.ref Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
example-opaque-types.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-opaque-types.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-opaque-types.ref Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
example-operator-overloading.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-operator-overloading.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-operator-overloading.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-pickling.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-pickling.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-pickling.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-python-types.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-python-types.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-python-types.ref Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
example-sequences-and-iterators.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-sequences-and-iterators.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-sequences-and-iterators.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-smart-ptr.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-smart-ptr.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-smart-ptr.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-stl-binder-vector.cpp minor namespace change in example 2016-07-19 17:35:09 +02:00
example-stl-binder-vector.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-stl-binder-vector.ref Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example-virtual-functions.cpp Move support for return values of called Python functions 2016-08-08 13:47:37 -04:00
example-virtual-functions.py Move support for return values of called Python functions 2016-08-08 13:47:37 -04:00
example-virtual-functions.ref Move support for return values of called Python functions 2016-08-08 13:47:37 -04:00
example.cpp Rename examples files, as per #288 2016-07-18 16:43:18 -04:00
example.h last breaking change: be consistent about the project name 2015-10-15 18:23:56 +02:00
issues.cpp Fix #283: don't print first arg of constructor 2016-07-17 17:47:05 -04:00
issues.py Fix #283: don't print first arg of constructor 2016-07-17 17:47:05 -04:00
issues.ref Adopt PEP 484 type hints for C++ types exported to Python 2016-08-04 23:47:07 +02:00
object.h Initial commit 2015-07-09 15:27:32 +02:00
run_test.py Rename examples files, as per #288 2016-07-18 16:43:18 -04:00