Add a scope guard call policy

`m.def("foo", foo, py::call_guard<T>());` is equivalent to:

```c++
Return wrap_foo(Args...) {
    T guard{};
    return foo(std::forward<Args>(args)...);
}
```

Author: dean0x7d

include/pybind11/attr.h

@@ -67,6 +67,17 @@ struct metaclass {
 /// Annotation to mark enums as an arithmetic type
 struct arithmetic { };
 
+/// A call policy which places a guard variable (of type T) around the function call
+template <typename T>
+struct call_guard {
+    static_assert(std::is_default_constructible<T>::value,
+                  "The guard type must be default constructible");
+
+    using type = T;
+};
+
+template <> struct call_guard<void> { using type = detail::void_type; };
+
 /// @} annotations
 
 NAMESPACE_BEGIN(detail)
@@ -374,6 +385,9 @@ struct process_attribute<metaclass> : process_attribute_default<metaclass> {
 template <>
 struct process_attribute<arithmetic> : process_attribute_default<arithmetic> {};
 
+template <typename T>
+struct process_attribute<call_guard<T>> : process_attribute_default<call_guard<T>> {};
+
 /***
  * Process a keep_alive call policy -- invokes keep_alive_impl during the
  * pre-call handler if both Nurse, Patient != 0 and use the post-call handler
@@ -410,6 +424,13 @@ template <typename... Args> struct process_attributes {
     }
 };
 
+template <typename T>
+using is_call_guard = is_<call_guard, T>;
+
+/// Extract the `T` from the first `call_guard<T>` in `Extras...` (or `void_type` if none found)
+template <typename... Extra>
+using extract_call_guard_t = typename first_of_t<is_call_guard, call_guard<void>, Extra...>::type;
+
 /// Check the number of named arguments at compile time
 template <typename... Extra,
           size_t named = constexpr_sum(std::is_base_of<arg, Extra>::value...),

include/pybind11/cast.h

@@ -1383,14 +1383,14 @@ class argument_loader {
         return load_impl_sequence(call, indices{});
     }
 
-    template <typename Return, typename Func>
+    template <typename Return, typename Guard, typename Func>
     enable_if_t<!std::is_void<Return>::value, Return> call(Func &&f) {
-        return call_impl<Return>(std::forward<Func>(f), indices{});
+        return call_impl<Return>(std::forward<Func>(f), indices{}, Guard{});
     }
 
-    template <typename Return, typename Func>
+    template <typename Return, typename Guard, typename Func>
     enable_if_t<std::is_void<Return>::value, void_type> call(Func &&f) {
-        call_impl<Return>(std::forward<Func>(f), indices{});
+        call_impl<Return>(std::forward<Func>(f), indices{}, Guard{});
         return void_type();
     }
 
@@ -1406,8 +1406,8 @@ class argument_loader {
         return true;
     }
 
-    template <typename Return, typename Func, size_t... Is>
-    Return call_impl(Func &&f, index_sequence<Is...>) {
+    template <typename Return, typename Func, size_t... Is, typename Guard>
+    Return call_impl(Func &&f, index_sequence<Is...>, Guard &&) {
         return std::forward<Func>(f)(cast_op<Args>(std::get<Is>(value))...);
     }
 

include/pybind11/common.h

@@ -536,9 +536,13 @@ using is_template_base_of = decltype(is_template_base_of_impl<Base>::check((remo
 struct is_template_base_of : decltype(is_template_base_of_impl<Base>::check((remove_cv_t<T>*)nullptr)) { };
 #endif
 
+/// Check if T is an instantiation of the template `Class`. For example:
+/// `is_<std::shared_ptr, T>` is true if `T == std::shared_ptr<U>` where U can be anything.
+template <template<typename...> class Class, typename T> struct is_ : std::false_type { };
+template <template<typename...> class C, typename... Us> struct is_<C, C<Us...>> : std::true_type { };
+
 /// Check if T is std::shared_ptr<U> where U can be anything
-template <typename T> struct is_shared_ptr : std::false_type { };
-template <typename U> struct is_shared_ptr<std::shared_ptr<U>> : std::true_type { };
+template <typename T> using is_shared_ptr = is_<std::shared_ptr, T>;
 
 /// Ignore that a variable is unused in compiler warnings
 inline void ignore_unused(const int *) { }

include/pybind11/pybind11.h

@@ -143,8 +143,11 @@ class cpp_function : public function {
             /* Override policy for rvalues -- usually to enforce rvp::move on an rvalue */
             const auto policy = detail::return_value_policy_override<Return>::policy(call.func.policy);
 
+            /* Function scope guard -- defaults to the compile-to-nothing `void_type` */
+            using Guard = detail::extract_call_guard_t<Extra...>;
+
             /* Perform the function call */
-            handle result = cast_out::cast(args_converter.template call<Return>(cap->f),
+            handle result = cast_out::cast(args_converter.template call<Return, Guard>(cap->f),
                                            policy, call.parent);
 
             /* Invoke call policy post-call hook */

tests/test_keep_alive.cpp

@@ -38,3 +38,36 @@ test_initializer keep_alive([](py::module &m) {
     py::class_<Child>(m, "Child")
         .def(py::init<>());
 });
+
+struct CustomGuard {
+    static bool enabled;
+
+    CustomGuard() { enabled = true; }
+    ~CustomGuard() { enabled = false; }
+
+    static const char *report_status() { return enabled ? "guarded" : "unguarded"; }
+};
+
+bool CustomGuard::enabled = false;
+
+test_initializer call_guard([](py::module &pm) {
+    auto m = pm.def_submodule("call_policies");
+
+    m.def("unguarded_call", &CustomGuard::report_status);
+    m.def("guarded_call", &CustomGuard::report_status, py::call_guard<CustomGuard>());
+
+#if defined(WITH_THREAD) && !defined(PYPY_VERSION)
+    // `py::call_guard<py::gil_scoped_release>()` should work in PyPy as well,
+    // but it's unclear how to test it without `PyGILState_GetThisThreadState`.
+    auto report_gil_status = []() {
+        auto is_gil_held = false;
+        if (auto tstate = py::detail::get_thread_state_unchecked())
+            is_gil_held = (tstate == PyGILState_GetThisThreadState());
+
+        return is_gil_held ? "GIL held" : "GIL released";
+    };
+
+    m.def("with_gil", report_gil_status);
+    m.def("without_gil", report_gil_status, py::call_guard<py::gil_scoped_release>());
+#endif
+});

tests/test_keep_alive.py

@@ -95,3 +95,14 @@ def test_return_none(capture):
         del p
         pytest.gc_collect()
     assert capture == "Releasing parent."
+
+
+def test_call_guard():
+    from pybind11_tests import call_policies
+
+    assert call_policies.unguarded_call() == "unguarded"
+    assert call_policies.guarded_call() == "guarded"
+
+    if hasattr(call_policies, "with_gil"):
+        assert call_policies.with_gil() == "GIL held"
+        assert call_policies.without_gil() == "GIL released"