Repository navigation
Inconsistent lifetime management across from_handle / from_* APIs #1989
Description
Summary
Audit of all public from_handle / from_* methods in cuda.core reveals several inconsistencies in how lifetime management is exposed to users. These should be resolved before the 1.0 stable release.
Inventory
| Class | Method | Ownership Model |
|---|---|---|
Stream |
from_handle(handle) |
Always non-owning (borrowed) |
Kernel |
from_handle(handle, mod=) |
Non-owning ref; optional _keepalive holds ObjectCode |
Buffer |
from_handle(ptr, size, mr=, owner=) |
3 modes: non-owning / mr-deallocates / owner-ref |
Event |
from_ipc_descriptor(...) |
Owns imported event |
Buffer |
from_ipc_descriptor(...) |
Owns imported buffer |
GraphicsResource |
from_gl_buffer(...) / from_gl_image(...) |
Owns GL registration |
DeviceMemoryResource |
from_allocation_handle(...) / from_registry(uuid) |
Owns imported pool / retrieves existing |
PinnedMemoryResource |
from_allocation_handle(...) / from_registry(uuid) |
Owns imported pool / retrieves existing |
ObjectCode |
from_cubin/ptx/ltoir/fatbin/object/library() |
Owns module data |
StridedMemoryView |
from_dlpack/cai/array_interface/buffer/any_interface() |
Always non-owning (view) |
Inconsistencies
1. Stream.from_handle cannot opt into keeping an owner alive
Buffer.from_handleacceptsowner=to hold a Python reference and prevent GC of the foreign allocator.Kernel.from_handleacceptsmod=to hold a reference and prevent GC of the parentObjectCode/library.Stream.from_handlehas no equivalent parameter. It creates a borrowed stream with no way for the user to tie lifetime to an owner object.
The internal machinery already supports this — create_stream_handle_with_owner() in C++ accepts a Python owner and does Py_INCREF/DECREF. But from_handle() only passes the ephemeral _stream_holder wrapper as the owner, not the user's actual owner object.
Suggestion: Add an owner parameter to Stream.from_handle, consistent with Buffer.from_handle.
2. Event has no public from_handle()
Stream,Kernel, andBufferall expose publicfrom_handle()for wrapping foreign CUDA handles.Eventonly hasfrom_ipc_descriptor(). There is an internal_from_handle()(cdef), but no public way to wrap a foreignCUevent.
Suggestion: Add Event.from_handle(handle) for symmetry, with the same borrowed/non-owning semantics.
3. Kernel.from_handle docstring doesn't clearly document ownership
Stream.from_handledocstring explicitly says: "Stream lifetime is not managed, foreign object must remain alive while this stream is active."Buffer.from_handledocstring explicitly documents all three ownership modes and when the pointer is/isn't freed.Kernel.from_handledocstring mentionsmod"provides library lifetime for foreign kernels" but doesn't clearly state that the kernel handle itself is non-owning and won't be destroyed on close/GC.
Suggestion: Improve the Kernel.from_handle docstring to match the clarity of the other two.
Additional observation
All from_handle() methods use @staticmethod, while from_ipc_descriptor() / from_gl_*() / from_allocation_handle() use @classmethod. This may be intentional (the latter group uses cls for subclassing support), but worth confirming as a deliberate convention and documenting if so.
-- Leo's bot
Activity
leofang commentedon Apr 29, 2026
Related: #1187
leofang commentedon Apr 29, 2026
@mdboom @Andy-Jost can either of you take this one too? 😛
Andy-Jost commentedon Apr 29, 2026
Agreed this is inconsistent and messy. We should provide a uniform way of building core objects from external resources.
The specific fixes outlined are purely additive, so I'd say lower priority for v1.0 release.
Andy-Jost commentedon Apr 29, 2026
The
@staticmethod/@classmethodinconsistency might be related to #1671 and #1660leofang commentedon Apr 29, 2026
Oh, you meant no breaking change is needed? In that case let me set it to P1.
mdboom commentedon Apr 30, 2026
But from a user/API perspective that shouldn't matter, right? (Ignoring users who subclass our classes).
refactor(cuda.core): narrow Buffer.from_handle to Buffer-only (R3)
Andy-Jost commentedon May 4, 2026
When updating
*_with_ownerfunctions to support Python ownership, consider #1976 (comment)Andy-Jost commentedon May 4, 2026
Yes, this is an implementation detail only.
Add managed-memory advise, prefetch, and discard-prefetch free functi…
Andy-Jost commentedon Aug 3, 2026
A fourth inconsistency in the same family:
Buffer.from_handle(ptr, size, mr=mr)hands ownership to a memory resource with no way to name the stream that will order the eventualmr.deallocate(), even thoughstreamhas been required onallocate/deallocatesince 1.0.0 — PR #2455 adds an optionalstreamargument that defaults to the current default stream.Andy-Jost commentedon Aug 3, 2026
Follow-up: once the optional
streamargument has shipped,Buffer.from_handle(mr=...)should emit aDeprecationWarningwhenstreamis omitted, so a future major version can require it likeallocate/deallocate.