Remote Key

Remote Key#

2026-03-31

5 min read time

Applies to Linux

The ucxx::RemoteKey class wraps a UCP remote key (ucp_rkey_h). Remote keys are used in RMA operations to access memory on a remote process. They are obtained by packing a memory handle on the remote side and unpacking it locally.

#include <ucxx/remote_key.h>

namespace ucxx

class RemoteKey : public ucxx::Component #

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.

Public Functions

ucp_rkey_h 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.

size_t 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.

uint64_t 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.

SerializedRemoteKey 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

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

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

Throws:: ucxx::Error – if ucp_rkey_pack fails.
Parameters:: memoryHandle – [in] the memory handle mapped on the local process.
Returns:: The shared_ptr<ucxx::RemoteKey> object

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

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

Throws:

ucxx::Error – if ucp_ep_rkey_unpack fails.

Parameters:

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

Factory Functions#

#include <ucxx/constructors.h>

std::shared_ptr<RemoteKey> ucxx::createRemoteKeyFromMemoryHandle( std::shared_ptr<MemoryHandle> memoryHandle )#