ucxx::RemoteKey Class Reference

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

#include <remote_key.h>

Inheritance diagram for ucxx::RemoteKey:

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< Component >	getParent () const
	Get the internal parent reference. More...

Friends
std::shared_ptr< RemoteKey >	createRemoteKeyFromMemoryHandle (std::shared_ptr< MemoryHandle > memoryHandle)
	Constructor for std::shared_ptr<ucxx::RemoteKey> from local memory handle. More...
std::shared_ptr< RemoteKey >	createRemoteKeyFromSerialized (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::Error

if ucp_rkey_pack fails.

Parameters

[in]

memoryHandle

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

Exceptions

ucxx::Error

if ucp_ep_rkey_unpack fails.

Parameters

[in]	endpoint	the std::shared_ptr<Endpoint> parent component.
[in]	serializedRemoteKey	the 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:

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