Remote Memory Access Request

2026-03-31

6 min read time

Applies to Linux

The ucxx::RequestMem class implements non-blocking remote memory access (RMA) operations. RMA allows direct memory read/write operations on a remote process’s memory without involving the remote CPU, using memory handles and remote keys.

#include <ucxx/request_mem.h>

namespace ucxx

class RequestMem : public ucxx::Request

Send or receive a message with the UCX RMA API.

Send or receive a message with the UCX RMA API, using non-blocking UCP calls ucp_put_nbx or ucp_get_nbx.

Public Functions

virtual void populateDelayedSubmission(

)

Populate the internal submission dispatcher.

The ucxx::Request utilizes ucxx::DelayedSubmission to manage when the request will be dispatched. This method is registered as a callback in the worker, that may choose to either execute (submit) it immediately or delay for the next iteration of its progress loop, depending on the progress mode in use by the worker.

See ucxx::DelayedSubmission::DelayedSubmission() for more details.

void request(

)

Create and submit a memory get or put request.

This is the method that should be called to actually submit memory request get or put request. It is meant to be called from populateDelayedSubmission(), which is decided at the discretion of std::shared_ptr<ucxx::Worker>. See populateDelayedSubmission() for more details.

Public Static Functions

static void memPutCallback(

void *request,

ucs_status_t status,

void *arg

)

Callback executed by UCX when a memory put request is completed.

Callback executed by UCX when a memory put request is completed, that will dispatch ucxx::Request::callback().

Warning

This is not intended to be called by the user, but it currently needs to be a public method so that UCX may access it. In future changes this will be moved to an internal object and remove this method from the public API.

Parameters:

• request – [in] the UCX request pointer.

• status – [in] the completion status of the request.

• arg – [in] the pointer to the ucxx::Request object that created the transfer, effectively this pointer as seen by request().

static void memGetCallback(

void *request,

ucs_status_t status,

void *arg

)

Callback executed by UCX when a memory get request is completed.

Callback executed by UCX when a memory get request is completed, that will dispatch ucxx::Request::callback().

Warning

This is not intended to be called by the user, but it currently needs to be a public method so that UCX may access it. In future changes this will be moved to an internal object and remove this method from the public API.

Parameters:

• request – [in] the UCX request pointer.

• status – [in] the completion status of the request.

• arg – [in] the pointer to the ucxx::Request object that created the transfer, effectively this pointer as seen by request().

Friends

friend std::shared_ptr<RequestMem> createRequestMem(

std::shared_ptr<Endpoint> endpoint,

const std::variant<data::MemPut, data::MemGet> requestData,

const bool enablePythonFuture,

RequestCallbackUserFunction callbackFunction,

RequestCallbackUserData callbackData

)

Constructor for std::shared_ptr<ucxx::RequestMem>.

The constructor for a std::shared_ptr<ucxx::RequestMem> object, creating a get or put request, returning a pointer to a request object that can be later awaited and checked for errors. This is a non-blocking operation, and the status of the transfer must be verified from the resulting request object before both the local and remote data can be released and the local data (on get operations) or remote data (on put operations) can be consumed.

Note

If a callbackFunction is specified, the lifetime of callbackData and of any other objects used in the scope of callbackFunction must be guaranteed by the caller until it executes or isCompleted() becomes true. The callbackFunction executes in the thread progressing the ucxx::Worker, unless the request completes immediately, in which case the callback will also execute immediately within the calling thread and before the method returns.

Throws:

ucxx::Error – if endpointOrWorker is not a valid std::shared_ptr<ucxx::Endpoint> or std::shared_ptr<ucxx::Worker>.

Parameters:

• endpoint – [in] the std::shared_ptr<Endpoint> parent component.

• requestData – [in] container of the specified message type, including all type-specific data.

• enablePythonFuture – [in] whether a python future should be created and subsequently notified.

• callbackFunction – [in] user-defined callback function to call upon completion.

• callbackData – [in] user-defined data to pass to the callbackFunction.

Returns:

The shared_ptr<ucxx::RequestMem> object

Factory Functions

#include <ucxx/constructors.h>

std::shared_ptr<RequestMem> ucxx::createRequestMem(

std::shared_ptr<Endpoint> endpoint,

const std::variant<data::MemPut, data::MemGet> requestData,

const bool enablePythonFuture,

RequestCallbackUserFunction callbackFunction,

RequestCallbackUserData callbackData

)

The constructor for a std::shared_ptr<ucxx::RequestMem> object, creating a get or put request, returning a pointer to a request object that can be later awaited and checked for errors. This is a non-blocking operation, and the status of the transfer must be verified from the resulting request object before both the local and remote data can be released and the local data (on get operations) or remote data (on put operations) can be consumed.

Note

If a callbackFunction is specified, the lifetime of callbackData and of any other objects used in the scope of callbackFunction must be guaranteed by the caller until it executes or isCompleted() becomes true. The callbackFunction executes in the thread progressing the ucxx::Worker, unless the request completes immediately, in which case the callback will also execute immediately within the calling thread and before the method returns.

Throws:

ucxx::Error – if endpointOrWorker is not a valid std::shared_ptr<ucxx::Endpoint> or std::shared_ptr<ucxx::Worker>.

Parameters:

• endpoint – [in] the std::shared_ptr<Endpoint> parent component.

• requestData – [in] container of the specified message type, including all type-specific data.

• enablePythonFuture – [in] whether a python future should be created and subsequently notified.

• callbackFunction – [in] user-defined callback function to call upon completion.

• callbackData – [in] user-defined data to pass to the callbackFunction.

Returns:

The shared_ptr<ucxx::RequestMem> object