Introduce return_value_policy::trampoline_reference

... to explicitly indicate a call from a trampoline dispatcher method.
In this case, the C++ objects should be always passed by (modifyable)
reference if required by the wrapped API.
const references (or pointers) are still copied.

Author: rhaschke

include/pybind11/detail/common.h

@@ -434,7 +434,11 @@ enum class return_value_policy : uint8_t {
         collected while Python is still using the child. More advanced
         variations of this scheme are also possible using combinations of
         return_value_policy::reference and the keep_alive call policy */
-    reference_internal
+    reference_internal,
+
+    /*  This internally-only used policy applies to C++ arguments passed
+        to virtual methods overridden in Python to allow reference passing. */
+    automatic_override
 };
 
 PYBIND11_NAMESPACE_BEGIN(detail)

include/pybind11/detail/smart_holder_type_casters.h

@@ -479,6 +479,8 @@ struct smart_holder_type_caster : smart_holder_type_caster_load<T>,
     // is redundant: T& automatically casts to T const&
 
     static handle cast(T const *src, return_value_policy policy, handle parent) {
+        if (policy == return_value_policy::automatic_override)
+            policy = return_value_policy::reference;
         auto st = type_caster_base<T>::src_and_type(src);
         return cast_const_raw_ptr( // Originally type_caster_generic::cast.
             st.first,
@@ -716,8 +718,8 @@ struct smart_holder_type_caster<std::unique_ptr<T, D>> : smart_holder_type_caste
             return none().release();
         if (policy == return_value_policy::automatic)
             policy = return_value_policy::reference_internal;
-        else if (policy == return_value_policy::reference && !parent)
-            ; // passing from trampoline dispatcher: no parent available
+        else if (policy == return_value_policy::automatic_override)
+            ;
         else if (policy != return_value_policy::reference_internal)
             throw cast_error(
                 "Invalid return_value_policy: unique_ptr const& expects reference_internal");

include/pybind11/detail/type_caster_base.h

@@ -899,6 +899,8 @@ template <typename type> class type_caster_base : public type_caster_generic {
     }
 
     static handle cast(const itype *src, return_value_policy policy, handle parent) {
+        if (policy == return_value_policy::automatic_override)
+            policy = return_value_policy::reference;
         auto st = src_and_type(src);
         return type_caster_generic::cast(
             st.first, policy, parent, st.second,

include/pybind11/pytypes.h

@@ -105,9 +105,9 @@ class object_api : public pyobject_tag {
         function will throw a `cast_error` exception. When the Python function
         call fails, a `error_already_set` exception is thrown.
     \endrst */
-    template <return_value_policy policy = return_value_policy::reference, typename... Args>
+    template <return_value_policy policy = return_value_policy::automatic_override, typename... Args>
     object operator()(Args &&...args) const;
-    template <return_value_policy policy = return_value_policy::reference, typename... Args>
+    template <return_value_policy policy = return_value_policy::automatic_override, typename... Args>
     PYBIND11_DEPRECATED("call(...) was deprecated in favor of operator()(...)")
         object call(Args&&... args) const;