ucxx::MemoryHandle Class Reference

Component holding a UCP memory handle. More...

#include <memory_handle.h>

Inheritance diagram for ucxx::MemoryHandle:

Public Member Functions
	MemoryHandle (const MemoryHandle &)=delete
MemoryHandle &	operator= (MemoryHandle const &)=delete
	MemoryHandle (MemoryHandle &&o)=delete
MemoryHandle &	operator= (MemoryHandle &&o)=delete
ucp_mem_h	getHandle ()
	Get the underlying ucp_mem_h handle. More...
size_t	getSize () const
	Get the size of the memory allocation. More...
uint64_t	getBaseAddress ()
	Get the base address of the memory allocation. More...
ucs_memory_type_t	getMemoryType ()
std::shared_ptr< RemoteKey >	createRemoteKey ()
Public Member Functions inherited from ucxx::Component
void	setParent (std::shared_ptr< Component > parent)
	Set the internal parent reference. More...
std::shared_ptr< Component >	getParent () const
	Get the internal parent reference. More...

Friends
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>. More...

Additional Inherited Members
Protected Attributes inherited from ucxx::Component
std::shared_ptr< Component >	_parent {nullptr}
	A reference-counted pointer to the parent.

Detailed Description

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.

Member Function Documentation

getBaseAddress()

uint64_t ucxx::MemoryHandle::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.

getHandle()

ucp_mem_h ucxx::MemoryHandle::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.

getSize()

size_t ucxx::MemoryHandle::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.

Friends And Related Function Documentation

createMemoryHandle

std::shared_ptr<MemoryHandle> createMemoryHandle ( std::shared_ptr< Context >  context, const size_t  size, void *  buffer, const ucs_memory_type_t  memoryType  )

friend

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)
// );

Exceptions

ucxx::Error

if either ucp_mem_map or ucp_mem_query fail.

Parameters

[in]	context	parent context where to map memory.
[in]	size	the minimum size of the memory allocation
[in]	buffer	the pointer to an existing allocation or nullptr to allocate a new memory region.
[in]	memoryType	the type of memory the handle points to.

Returns

The shared_ptr<ucxx::MemoryHandle> object

---

The documentation for this class was generated from the following file:

• /__w/ucxx/ucxx/cpp/include/ucxx/memory_handle.h