All Classes Namespaces Functions Variables Typedefs Enumerations Friends
Public Member Functions | Friends | List of all members
ucxx::MemoryHandle Class Reference

Component holding a UCP memory handle. More...

#include <memory_handle.h>

Inheritance diagram for ucxx::MemoryHandle:
ucxx::Component

Public Member Functions

 MemoryHandle (const MemoryHandle &)=delete
 
MemoryHandleoperator= (MemoryHandle const &)=delete
 
 MemoryHandle (MemoryHandle &&o)=delete
 
MemoryHandleoperator= (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< RemoteKeycreateRemoteKey ()
 
- Public Member Functions inherited from ucxx::Component
void setParent (std::shared_ptr< Component > parent)
 Set the internal parent reference. More...
 
std::shared_ptr< ComponentgetParent () const
 Get the internal parent reference. More...
 

Friends

std::shared_ptr< MemoryHandlecreateMemoryHandle (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::Errorif either ucp_mem_map or ucp_mem_query fail.
Parameters
[in]contextparent context where to map memory.
[in]sizethe minimum size of the memory allocation
[in]bufferthe pointer to an existing allocation or nullptr to allocate a new memory region.
[in]memoryTypethe 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: