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, the location type is automatically set to CU_MEM_LOCATION_TYPE_HOST_NUMA instead of CU_MEM_LOCATION_TYPE_HOST, with location ID 0.

Note: IPC support for pinned memory requires a single NUMA node. A warning is issued if multiple NUMA nodes are detected.

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 device 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