cuda.core.ManagedBuffer#

class cuda.core.ManagedBuffer#

Managed (unified) memory buffer with a property-style advice API.

Returned by ManagedMemoryResource.allocate(), or wrap an existing managed-memory pointer with ManagedBuffer.from_handle().

Examples

>>> buf = mr.allocate(size)
>>> buf.read_mostly = True
>>> buf.preferred_location = Device(0)
>>> buf.accessed_by.add(Device(1))
>>> buf.prefetch(Device(0), stream=stream)

Note

On CUDA 13 builds, preferred_location round-trips full NUMA information. On CUDA 12 builds, Host(numa_id=...) and Host.numa_current() are rejected with TypeError at the call boundary — only Device(...) and the generic Host() are accepted. Use Host() to target the host on CUDA 12.

Methods

__init__(*args, **kwargs)#
close(self, stream: Stream | GraphBuilder | None = None)#

Deallocate this buffer asynchronously on the given stream.

This buffer is released back to their memory resource asynchronously on the given stream.

Parameters:

stream (Stream | GraphBuilder, optional) – The stream object to use for asynchronous deallocation. If None, the deallocation stream stored in the handle is used.

copy_from(
self,
Buffer src: Buffer,
*,
stream: Stream | GraphBuilder,
)#

Copy from the src buffer to this buffer asynchronously on the given stream.

Parameters:

  • src (Buffer) – Source buffer to copy data from

  • stream (Stream | GraphBuilder) – Keyword argument specifying the stream for the asynchronous copy

copy_to(
self,
Buffer dst: Buffer = None,
*,
stream: Stream | GraphBuilder,
) → Buffer#

Copy from this buffer to the dst buffer asynchronously on the given stream.

Copies the data from this buffer to the provided dst buffer. If the dst buffer is not provided, then a new buffer is first allocated using the associated memory resource before the copy.

Parameters:

  • dst (Buffer, optional) – Destination buffer to copy data to. If not provided, a new buffer is allocated using this buffer’s memory resource.

  • stream (Stream | GraphBuilder) – Keyword argument specifying the stream for the asynchronous copy

discard(*, stream: Stream | GraphBuilder) → None#

Discard this range’s resident pages on stream (CUDA 13+).

discard_prefetch(
location: Device | Host,
*,
stream: Stream | GraphBuilder,
) → None#

Discard this range and prefetch to location on stream (CUDA 13+).

fill(
self,
value: int | BufferProtocol,
*,
stream: Stream | GraphBuilder,
)#

Fill this buffer with a repeating byte pattern.

Parameters:
Raises:

  • TypeError – If value is not an int and does not support the buffer protocol.

  • ValueError – If value byte length is not 1, 2, or 4. If buffer size is not divisible by value byte length.

  • OverflowError – If int value is outside [0, 256).

classmethod from_handle(
ptr,
size: int,
mr: MemoryResource | None = None,
owner: object | None = None,
) → ManagedBuffer#

Wrap an existing managed-memory pointer in a ManagedBuffer.

Use this when you have an externally-allocated managed pointer and want the property-style advice API (read_mostly, preferred_location, accessed_by).

Parameters:

  • ptr (DevicePointerT) – Pointer to a managed allocation.

  • size (int) – Allocation size in bytes.

  • mr (MemoryResource, optional) – Memory resource that owns ptr. When provided, its deallocate is called when the buffer is closed.

  • owner (object, optional) – An object that keeps the underlying allocation alive. owner and mr cannot both be specified.

classmethod from_ipc_descriptor(
cls,
mr: DeviceMemoryResource | PinnedMemoryResource,
IPCBufferDescriptor ipc_descriptor: IPCBufferDescriptor,
*,
Stream stream: Stream,
) → Buffer#

Import a buffer that was exported from another process.

Parameters:

  • mr (DeviceMemoryResource | PinnedMemoryResource) – The IPC-enabled memory resource matching the exporting process.

  • ipc_descriptor (IPCBufferDescriptor) – The descriptor exported from another process.

  • stream (Stream) – Keyword-only. The stream used for asynchronous deallocation when the buffer is closed or garbage collected.

prefetch(
location: Device | Host,
*,
stream: Stream | GraphBuilder,
) → None#

Prefetch this range to location on stream.

Attributes

accessed_by#

Live set-like view of set_accessed_by locations.

device_id#

int

Return the device ordinal of this buffer.

Type:

Buffer.device_id

handle#

DevicePointerType

Return the buffer handle object.

Caution

This handle is a Python object. To get the memory address of the underlying C handle, call int(Buffer.handle).

Type:

Buffer.handle

ipc_descriptor#

IPCBufferDescriptor

Descriptor for sharing this buffer with other processes.

Type:

Buffer.ipc_descriptor

is_device_accessible#

bool

Return True if this buffer can be accessed by the GPU, otherwise False.

Type:

Buffer.is_device_accessible

is_host_accessible#

bool

Return True if this buffer can be accessed by the CPU, otherwise False.

Type:

Buffer.is_host_accessible

is_managed#

bool

Return True if this buffer is CUDA managed (unified) memory, otherwise False.

Type:

Buffer.is_managed

is_mapped#

bool

Return True if this buffer is mapped into the process via IPC.

Type:

Buffer.is_mapped

memory_resource#

MemoryResource

Return the memory resource associated with this buffer.

Type:

Buffer.memory_resource

owner#

object

Return the object holding external allocation.

Type:

Buffer.owner

preferred_location#

Currently applied set_preferred_location target, or None.

On CUDA 13 builds, fully round-trips Host(numa_id=N). On CUDA 12 the legacy attribute carries only a device ordinal (or -1 for host), so Host(numa_id=N) set via the setter round-trips back as Host().

read_mostly#

Whether set_read_mostly advice is currently applied.

size#

int

Return the memory size of this buffer.

Type:

Buffer.size