docs(cuda.core): add deallocation stream transfer example

Show how to move a Buffer between streams with an event so its eventual deallocation remains correctly ordered.

Author: Andy-Jost

cuda_core/cuda/core/_memory/_buffer.pyx

@@ -745,10 +745,9 @@ cdef tuple Buffer_coerce_batch(object buffers, str what, str single_hint):
 
 cdef inline void Buffer_set_deallocation_stream(Buffer self, object stream):
     """Validate and replace a live buffer's deallocation recipe."""
-    cdef Stream s
     if not self._h_ptr:
         raise RuntimeError("Cannot set the deallocation stream on a closed Buffer")
-    s = Stream_accept(stream)
+    cdef Stream s = Stream_accept(stream)
     _apply_deallocation_stream(self._h_ptr, s._h_stream)
 
 

cuda_core/docs/source/api.rst

@@ -81,7 +81,9 @@ A :class:`Buffer` records the stream that will order its eventual deallocation.
 Use :meth:`Buffer.set_deallocation_stream` to replace that stream without
 closing the buffer. Changing the recorded stream does not synchronize streams;
 the caller must order allocation and every access before the deallocation,
-using events or other CUDA synchronization mechanisms as needed.
+using events or other CUDA synchronization mechanisms as needed. See
+:cuda-core-example:`buffer_deallocation_stream.py <buffer_deallocation_stream.py>`
+for a complete example.
 
 
 CUDA compilation toolchain

cuda_core/docs/source/examples.rst

@@ -39,6 +39,13 @@ Linking and graphs
 - :cuda-core-example:`cuda_graphs.py <cuda_graphs.py>`
   captures and replays a multi-kernel CUDA graph to reduce launch overhead.
 
+Memory management
+-----------------
+
+- :cuda-core-example:`buffer_deallocation_stream.py <buffer_deallocation_stream.py>`
+  transfers a buffer between streams and safely changes the stream that orders
+  its deallocation.
+
 Interoperability and memory access
 ----------------------------------
 

cuda_core/examples/buffer_deallocation_stream.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# ################################################################################
+#
+# This example transfers a buffer from a producer stream to a consumer stream.
+# An event orders the consumer after the producer. The buffer then records the
+# consumer stream for its eventual deallocation.
+#
+# ################################################################################
+
+# /// script
+# dependencies = ["cuda_bindings", "cuda_core"]
+# ///
+
+import ctypes
+
+from cuda.core import Device, LegacyPinnedMemoryResource
+
+
+def produce_data(device, stream, size, value):
+    """Allocate and fill a buffer on the producer stream."""
+    buffer = device.allocate(size, stream=stream)
+    buffer.fill(value, stream=stream)
+    ready = stream.record()
+    return buffer, ready
+
+
+def consume_data(buffer, ready, output, stream):
+    """Submit consumer work and transfer the deallocation stream."""
+    stream.wait(ready)
+    buffer.set_deallocation_stream(stream)
+    buffer.copy_to(output, stream=stream)
+
+
+def main():
+    device = Device()
+    device.set_current()
+    producer_stream = device.create_stream()
+    consumer_stream = device.create_stream()
+    pinned_mr = LegacyPinnedMemoryResource()
+
+    size = 4096
+    value = 42
+    buffer = None
+    ready = None
+    output = None
+
+    try:
+        output = pinned_mr.allocate(size)
+        buffer, ready = produce_data(device, producer_stream, size, value)
+        consume_data(buffer, ready, output, consumer_stream)
+
+        # No stream argument is needed. The buffer now records consumer_stream.
+        # The free operation runs after the copy on that stream.
+        buffer.close()
+        buffer = None
+        consumer_stream.sync()
+
+        result = ctypes.string_at(int(output.handle), output.size)
+        assert result == bytes([value]) * size
+        print("Buffer deallocation stream transfer completed.")
+    finally:
+        if buffer is not None:
+            buffer.close()
+        if output is not None:
+            output.close()
+        if ready is not None:
+            ready.close()
+        consumer_stream.close()
+        producer_stream.close()
+
+
+if __name__ == "__main__":
+    main()