Memory Handle

2026-03-31

6 min read time

Applies to Linux

The ucxx::MemoryHandle class wraps a UCP memory handle (ucp_mem_h). Memory handles are used to register memory regions for remote memory access (RMA) operations. A memory handle can either allocate new memory or map an existing buffer for RMA.

#include <ucxx/memory_handle.h>

namespace ucxx

class MemoryHandle : public ucxx::Component

Component holding a UCP memory handle.

The UCP layer provides RMA (Remote Memory Access) to memory handles that it controls in form of ucp_mem_h object, this class encapsulates that object and provides methods to simplify its handling.

Public Functions

ucp_mem_h getHandle(

)

Get the underlying ucp_mem_h handle.

Lifetime of the ucp_mem_h handle is managed by the ucxx::MemoryHandle object and its ownership is non-transferrable. Once the ucxx::MemoryHandle is destroyed the memory is unmapped and the handle is not valid anymore, it is the user’s responsibility to ensure the owner’s lifetime while using the handle.

// memoryHandle is `std::shared_ptr<ucxx::MemoryHandle>`
ucp_mem_h ucpMemoryHandle = memoryHandle->getHandle();

Returns:

The underlying ucp_mem_h handle.

size_t getSize(

) const

Get the size of the memory allocation.

Get the size of the memory allocation, which is at least the number of bytes specified with the size argument passed to createMemoryHandle().

// memoryHandle is `std::shared_ptr<ucxx::MemoryHandle>`
auto memorySize = memoryHandle->getSize();

Returns:

The size of the memory allocation.

uint64_t getBaseAddress(

)

Get the base address of the memory allocation.

Get the base address of the memory allocation, which is going to be used as the remote address to put or get memory via the ucxx::Endpoint::memPut() or ucxx::Endpoint::memGet() methods.

// memoryHandle is `std::shared_ptr<ucxx::MemoryHandle>`
auto memoryBase Address = memoryHandle->getBaseAddress();

Returns:

The base address of the memory allocation.

ucs_memory_type_t getMemoryType(

)

Get the memory type of the allocation.

Get the memory type of the allocation, which indicates whether the memory is host memory or device memory (i.e., CUDA).

Returns:

The memory type of the allocation.

std::shared_ptr<RemoteKey> createRemoteKey(

)

Create a remote key for the memory allocation.

Create a remote key that can be used by a remote endpoint to access this memory allocation. The remote key is required for remote memory access operations.

Returns:

A shared pointer to the created remote key.

Friends

friend std::shared_ptr<MemoryHandle> createMemoryHandle(

std::shared_ptr<Context> context,

const size_t size,

void *buffer,

const ucs_memory_type_t memoryType

)

Constructor for shared_ptr<ucxx::MemoryHandle>.

The constructor for a shared_ptr<ucxx::MemoryHandle> object, mapping a memory buffer with UCP to provide RMA (Remote Memory Access) to.

The allocation requires a size and a buffer. The buffer provided may be either a nullptr, in which case UCP will allocate a new memory region for it, or an already existing allocation, in which case UCP will only map it for RMA and it’s the caller’s responsibility to keep buffer alive until this object is destroyed. When the UCP allocates buffer (i.e., when the value passed is nullptr), the actual size of the allocation may be larger than requested, and can later be found calling the getSize() method, if a preallocated buffer is passed getSize() will return the same value specified for size.

// `context` is `std::shared_ptr<ucxx::Context>`
// Allocate a 128-byte buffer with UCP.
auto memoryHandle = context->createMemoryHandle(128, nullptr);

// Equivalent to line above
// auto memoryHandle = ucxx::createMemoryHandle(context, 128, nullptr);

// Map an existing 128-byte buffer with UCP.
size_t allocationSize = 128;
auto buffer = new uint8_t[allocationSize];
auto memoryHandleFromBuffer = context->createMemoryHandle(
   allocationSize * sizeof(*buffer), reinterpret_cast<void*>(buffer)
);

// Equivalent to line above
// auto memoryHandleFromBuffer = ucxx::createMemoryHandle(
//    context, allocationSize * sizeof(*buffer), reinterpret_cast<void*>(buffer)
// );

Throws:

ucxx::Error – if either ucp_mem_map or ucp_mem_query fail.

Parameters:

• context – [in] parent context where to map memory.

• size – [in] the minimum size of the memory allocation

• buffer – [in] the pointer to an existing allocation or nullptr to allocate a new memory region.

• memoryType – [in] the type of memory the handle points to.

Returns:

The shared_ptr<ucxx::MemoryHandle> object

Factory Functions

#include <ucxx/constructors.h>

std::shared_ptr<MemoryHandle> ucxx::createMemoryHandle(

std::shared_ptr<Context> context,

const size_t size,

void *buffer = nullptr,

const ucs_memory_type_t memoryType = UCS_MEMORY_TYPE_HOST

)

The constructor for a shared_ptr<ucxx::MemoryHandle> object, mapping a memory buffer with UCP to provide RMA (Remote Memory Access) to.

The allocation requires a size and a buffer. The buffer provided may be either a nullptr, in which case UCP will allocate a new memory region for it, or an already existing allocation, in which case UCP will only map it for RMA and it’s the caller’s responsibility to keep buffer alive until this object is destroyed. When the UCP allocates buffer (i.e., when the value passed is nullptr), the actual size of the allocation may be larger than requested, and can later be found calling the getSize() method, if a preallocated buffer is passed getSize() will return the same value specified for size.

// `context` is `std::shared_ptr<ucxx::Context>`
// Allocate a 128-byte buffer with UCP.
auto memoryHandle = context->createMemoryHandle(128, nullptr);

// Equivalent to line above
// auto memoryHandle = ucxx::createMemoryHandle(context, 128, nullptr);

// Map an existing 128-byte buffer with UCP.
size_t allocationSize = 128;
auto buffer = new uint8_t[allocationSize];
auto memoryHandleFromBuffer = context->createMemoryHandle(
   allocationSize * sizeof(*buffer), reinterpret_cast<void*>(buffer)
);

// Equivalent to line above
// auto memoryHandleFromBuffer = ucxx::createMemoryHandle(
//    context, allocationSize * sizeof(*buffer), reinterpret_cast<void*>(buffer)
// );

Throws:

ucxx::Error – if either ucp_mem_map or ucp_mem_query fail.

Parameters:

• context – [in] parent context where to map memory.

• size – [in] the minimum size of the memory allocation

• buffer – [in] the pointer to an existing allocation or nullptr to allocate a new memory region.

• memoryType – [in] the type of memory the handle points to.

Returns:

The shared_ptr<ucxx::MemoryHandle> object