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.

Author: rhaschke

include/pybind11/detail/common.h

@@ -402,7 +402,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/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;