Add memoryview_scoped_release to manage short-lived memoryviews

Author: virtuald

docs/advanced/pycpp/numpy.rst

@@ -417,6 +417,23 @@ managed by Python. The user is responsible for managing the lifetime of the
 buffer. Using a ``memoryview`` created in this way after deleting the buffer in
 C++ side results in undefined behavior.
 
+To prevent undefined behavior, you can call the ``release`` function on a
+``memoryview``. After ``release`` is called, any further operation on the view
+will raise a ``ValueError``. For short lived buffers, consider using
+``memoryview_scoped_release`` to release the memoryview:
+
+.. code-block:: cpp
+
+    {
+        auto view = py::memoryview::from_memory(buffer, size);
+        py::memoryview_scoped_release release(view);
+
+        some_function(view);
+    }
+
+    // operations on the memoryview after this scope exits will raise a
+    // ValueError exception
+
 We can also use ``memoryview::from_memory`` for a simple 1D contiguous buffer:
 
 .. code-block:: cpp

include/pybind11/pybind11.h

@@ -2174,6 +2174,21 @@ class gil_scoped_acquire { };
 class gil_scoped_release { };
 #endif
 
+#if PY_VERSION_HEX >= 0x03020000
+/// Release the underlying buffer exposed by the memoryview object when this
+/// object goes out of scope. Any further operation on the view raises a
+/// ValueError.
+///
+/// Only available in Python 3.2+
+class memoryview_scoped_release {
+public:
+    explicit memoryview_scoped_release(memoryview view) : m_view(view) {}
+    ~memoryview_scoped_release() { m_view.attr("release")(); }
+private:
+    memoryview m_view;
+};
+#endif
+
 error_already_set::~error_already_set() {
     if (m_type) {
         gil_scoped_acquire gil;

include/pybind11/pytypes.h

@@ -1421,7 +1421,8 @@ class memoryview : public object {
         This method is meant for providing a ``memoryview`` for C/C++ buffer not
         managed by Python. The caller is responsible for managing the lifetime
         of ``ptr`` and ``format``, which MUST outlive the memoryview constructed
-        here.
+        here. Consider using ``memoryview_scoped_release`` to manage the lifetime
+        for short-lived memoryview objects.
 
         See also: Python C API documentation for `PyMemoryView_FromBuffer`_.
 
@@ -1475,6 +1476,8 @@ class memoryview : public object {
         This method is meant for providing a ``memoryview`` for C/C++ buffer not
         managed by Python. The caller is responsible for managing the lifetime
         of ``mem``, which MUST outlive the memoryview constructed here.
+        Consider using ``memoryview_scoped_release`` to manage the lifetime
+        for short-lived memoryview objects.
 
         This method is not available in Python 2.
 

tests/test_pytypes.cpp

@@ -410,4 +410,14 @@ TEST_SUBMODULE(pytypes, m) {
 
     // test_builtin_functions
     m.def("get_len", [](py::handle h) { return py::len(h); });
+
+#if PY_VERSION_HEX >= 0x03020000
+    m.def("test_memoryview_scoped_release", [](py::function f) {
+        const char* buf = "\x42";
+        auto view = py::memoryview::from_memory(buf, 1);
+        py::memoryview_scoped_release release(view);
+        f(view);
+    });
+#endif
+
 }

tests/test_pytypes.py

@@ -486,3 +486,17 @@ def test_builtin_functions():
         "object of type 'generator' has no len()",
         "'generator' has no length",
     ]  # PyPy
+
+
+@pytest.mark.skipif(sys.version_info < (3, 2), reason="API not available")
+def test_memoryview_scoped_release():
+    class C:
+        def fn(self, view):
+            self.view = view
+            assert bytes(view) == b"\x42"
+
+    c = C()
+    m.test_memoryview_scoped_release(c.fn)
+    assert hasattr(c, "view")
+    with pytest.raises(ValueError):
+        bytes(c.view)