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

Component holding a UCP rkey (remote key). More...

#include <remote_key.h>

Inheritance diagram for ucxx::RemoteKey:
ucxx::Component

Public Member Functions

ucp_rkey_h getHandle ()
 Get the underlying ucp_rkey_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...
 
SerializedRemoteKey serialize () const
 Serialize the remote key. More...
 
- 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< RemoteKeycreateRemoteKeyFromMemoryHandle (std::shared_ptr< MemoryHandle > memoryHandle)
 Constructor for std::shared_ptr<ucxx::RemoteKey> from local memory handle. More...
 
std::shared_ptr< RemoteKeycreateRemoteKeyFromSerialized (std::shared_ptr< Endpoint > endpoint, SerializedRemoteKey serializedRemoteKey)
 Constructor for std::shared_ptr<ucxx::RemoteKey> from remote. 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 rkey (remote key).

To provide RMA (Remote Memory Access) to memory handles, UCP packs their information in the form of ucp_rkey_h (remote key, or rkey for short). This class encapsulates that object and provides methods to simplify its handling, both locally and remotely including (de-)serialization for transfers over the wire and reconstruction of the object on the remote process.

Member Function Documentation

◆ getBaseAddress()

uint64_t ucxx::RemoteKey::getBaseAddress ( )

Get the base address of the memory allocation.

Get the base address of the memory allocation the remote key packs, 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.

// remoteKey is `std::shared_ptr<ucxx::RemoteKey>`
auto remoteMemoryBaseAddress = remoteKey->getBaseAddress();
Returns
The base address of the memory allocation.

◆ getHandle()

ucp_rkey_h ucxx::RemoteKey::getHandle ( )

Get the underlying ucp_rkey_h handle.

Lifetime of the ucp_rkey_h handle is managed by the ucxx::RemoteKey object and its ownership is non-transferrable. Once the ucxx::RemoteKey is destroyed the handle becomes invalid and so does the address to the remote memory handle it points to, it is the user's responsibility to ensure the owner's lifetime while using the handle.

// remoteKey is `std::shared_ptr<ucxx::RemoteKey>`
auto remoteKeyHandle = remoteKey->getHandle();
Returns
The underlying ucp_mem_h handle.

◆ getSize()

size_t ucxx::RemoteKey::getSize ( ) const

Get the size of the memory allocation.

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

// remoteKey is `std::shared_ptr<ucxx::RemoteKey>`
auto remoteMemorySize = remoteKey->getSize();
Returns
The size of the memory allocation.

◆ serialize()

SerializedRemoteKey ucxx::RemoteKey::serialize ( ) const

Serialize the remote key.

Serialize the remote key to allow over-the-wire transfer and subsequent reconstruction of the object in the remote process.

// remoteKey is `std::shared_ptr<ucxx::RemoteKey>`
auto serializedRemoteKey = remoteKey->serialize();
Returns
The serialized remote key.

Friends And Related Function Documentation

◆ createRemoteKeyFromMemoryHandle

std::shared_ptr<RemoteKey> createRemoteKeyFromMemoryHandle ( std::shared_ptr< MemoryHandle memoryHandle)
friend

Constructor for std::shared_ptr<ucxx::RemoteKey> from local memory handle.

The constructor for a std::shared_ptr<ucxx::RemoteKey> object from a local std::shared_ptr<ucxx::MemoryHandle>, mapping a local memory buffer to be made accessible from a remote endpoint to perform RMA (Remote Memory Access) on the memory.

// `memoryHandle` is `std::shared_ptr<ucxx::MemoryHandle>`
auto remoteKey = memoryHandle->createRemoteKey();
// Equivalent to line above
// auto remoteKey = ucxx::createRemoteKeyFromMemoryHandle(memoryHandle);
Exceptions
ucxx::Errorif ucp_rkey_pack fails.
Parameters
[in]memoryHandlethe memory handle mapped on the local process.
Returns
The shared_ptr<ucxx::RemoteKey> object

◆ createRemoteKeyFromSerialized

std::shared_ptr<RemoteKey> createRemoteKeyFromSerialized ( std::shared_ptr< Endpoint endpoint,
SerializedRemoteKey  serializedRemoteKey 
)
friend

Constructor for std::shared_ptr<ucxx::RemoteKey> from remote.

The constructor for a std::shared_ptr<ucxx::RemoteKey> object from a serialized std::shared_ptr<ucxx::RemoteKey>, mapping a remote memory buffer to be made accessible via a local endpoint to perform RMA (Remote Memory Access) on the memory.

// `serializedRemoteKey` is `ucxx::SerializedRemoteKey>`, created on a remote worker
// after a call to `ucxx::RemoteKey::serialize()` and transferred over-the-wire.
auto remoteKey = ucxx::createRemoteKeyFromSerialized(serializedRemoteKey);
// Equivalent to line above
// auto remoteKey = ucxx::createRemoteKeyFromMemoryHandle(memoryHandle);
std::shared_ptr< RemoteKey > createRemoteKeyFromSerialized(std::shared_ptr< Endpoint > endpoint, SerializedRemoteKey serializedRemoteKey)
Exceptions
ucxx::Errorif ucp_ep_rkey_unpack fails.
Parameters
[in]endpointthe std::shared_ptr<Endpoint> parent component.
[in]serializedRemoteKeythe remote key that was serialized by the owner of the memory handle and transferred over-the-wire for reconstruction and remote access.
Returns
The shared_ptr<ucxx::RemoteKey> object

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