cuda.core.PinnedMemoryResource#

class cuda.core.PinnedMemoryResource(options=None)#

A host-pinned memory resource managing a stream-ordered memory pool.

Parameters:

options (PinnedMemoryResourceOptions) –

Memory resource creation options.

If set to None, the memory resource uses the driver’s current stream-ordered memory pool. If no memory pool is set as current, the driver’s default memory pool is used.

If not set to None, a new memory pool is created, which is owned by the memory resource.

When using an existing (current or default) memory pool, the returned host-pinned memory resource does not own the pool (is_handle_owned is False), and closing the resource has no effect.

Notes

To create an IPC-Enabled memory resource (MR) that is capable of sharing allocations between processes, specify ipc_enabled=True in the initializer option. When IPC is enabled and numa_id is not specified, the NUMA node is automatically derived from the current CUDA device’s host_numa_id attribute, which requires an active CUDA context. If numa_id is explicitly set, that value is used regardless of ipc_enabled.

See DeviceMemoryResource for more details on IPC usage patterns.

Methods

__init__(*args, **kwargs)#
allocate(
self,
size_t size,
stream: Stream | GraphBuilder | None = None,
) → Buffer#

Allocate a buffer of the requested size.

Parameters:

  • size (int) – The size of the buffer to allocate, in bytes.

  • stream (Stream | GraphBuilder, optional) – The stream on which to perform the allocation asynchronously. If None, an internal stream is used.

Returns:

The allocated buffer object, which is accessible on the device that this memory resource was created for.

Return type:

Buffer

close(self)#

Close the memory resource and destroy the associated memory pool if owned.

deallocate(
self,
ptr: DevicePointerT,
size_t size,
stream: Stream | GraphBuilder | None = None,
)#

Deallocate a buffer previously allocated by this resource.

Parameters:

  • ptr (DevicePointerT) – The pointer or handle to the buffer to deallocate.

  • size (int) – The size of the buffer to deallocate, in bytes.

  • stream (Stream | GraphBuilder, optional) – The stream on which to perform the deallocation asynchronously. If the buffer is deallocated without an explicit stream, the allocation stream is used.

classmethod from_allocation_handle(
cls,
alloc_handle: int | IPCAllocationHandle,
) → PinnedMemoryResource#

Create a host-pinned memory resource from an allocation handle.

Construct a new PinnedMemoryResource instance that imports a memory pool from a shareable handle. The memory pool is marked as owned.

Parameters:

alloc_handle (int | IPCAllocationHandle) – The shareable handle of the host-pinned memory resource to import. If an integer is supplied, it must represent a valid platform-specific handle. It is the caller’s responsibility to close that handle.

Return type:

A new host-pinned memory resource instance with the imported handle.

static from_registry(
uuid: uuid.UUID,
) → PinnedMemoryResource#

Obtain a registered mapped memory resource.

Raises:

RuntimeError – If no mapped memory resource is found in the registry.

get_allocation_handle(
self,
) → IPCAllocationHandle#

Export the memory pool handle to be shared (requires IPC).

The handle can be used to share the memory pool with other processes. The handle is cached in this MemoryResource and owned by it.

Return type:

The shareable handle for the memory pool.

register(
self,
uuid: uuid.UUID,
) → PinnedMemoryResource#

Register a mapped memory resource.

Returns:

  • The registered mapped memory resource. If one was previously registered

  • with the given key, it is returned.

Attributes

attributes#

_MemPoolAttributes

Memory pool attributes.

Type:

_MemPool.attributes

device_id#

int

Return -1. Pinned memory is host memory and is not associated with a specific device.

Type:

PinnedMemoryResource.device_id

handle#

object

Handle to the underlying memory pool.

Type:

_MemPool.handle

is_device_accessible#

bool

Return True. This memory resource provides device-accessible buffers.

Type:

PinnedMemoryResource.is_device_accessible

is_handle_owned#

bool

Whether the memory resource handle is owned. If False, close has no effect.

Type:

_MemPool.is_handle_owned

is_host_accessible#

bool

Return True. This memory resource provides host-accessible buffers.

Type:

PinnedMemoryResource.is_host_accessible

is_ipc_enabled#

bool

Whether this memory resource has IPC enabled.

Type:

_MemPool.is_ipc_enabled

is_mapped#

bool

Whether this is a mapping of an IPC-enabled memory resource from another process. If True, allocation is not permitted.

Type:

_MemPool.is_mapped

numa_id#

int

The host NUMA node ID used for pool placement, or -1 for OS-managed placement.

Type:

PinnedMemoryResource.numa_id

uuid#

uuid.UUID | None

A universally unique identifier for this memory resource. Meaningful only for IPC-enabled memory resources.

Type:

_MemPool.uuid