Request

Request#

2026-03-31

13 min read time

Applies to Linux

This page provides C++ class references for the request types in the ucxx library. Requests represent non-blocking communication operations. Each request type corresponds to a different UCX communication pattern: tag, stream, active message, remote memory access, flush, and endpoint close.

Base Request#

#include <ucxx/request.h>

namespace ucxx

class Request : public ucxx::Component#

Base type for a UCXX transfer request.

Base type for one of the multiple UCXX transfer requests. Encapsulates information such as the UCP request pointer, the current status, a future to notify and a callback to execute upon completion, as well operation-specific data and to maintain a reference to its parent until completion.

Subclassed by ucxx::RequestAm, ucxx::RequestEndpointClose, ucxx::RequestFlush, ucxx::RequestMem, ucxx::RequestStream, ucxx::RequestTag, ucxx::RequestTagMulti

Public Functions

virtual ~Request(
)#

ucxx::Request destructor.

Removes its own reference from its parent’s inflight messages collection and free internal resources.

virtual void cancel(
)#

Cancel the request.

Cancel the request. Often called by the error handler or parent’s object destructor but may be called by the user to cancel the request as well.

ucs_status_t getStatus(
)#

Return the status of the request.

Return a ucs_status_t that may be used for more fine-grained error handling than relying on checkError() alone, which does not currently implement all error statuses supported by UCX.

Returns:

the current status of the request.

void *getFuture(
)#

Return the future used to check on state.

If the object has enabled Python future support, return the future that can be awaited from Python, returns nullptr otherwise.

Returns:

the Python future object or nullptr.

void checkError(
)#

Check whether the request completed with an error.

Check whether the request has completed with an error, if an error occurred an exception is raised, but if the request has completed or is in progress this call will act as a no-op. To verify whether the request is in progress either isCompleted() or getStatus() should be checked.

Throws:

  • <tt>ucxx::CanceledError</tt> – if the request was canceled.

  • <tt>ucxx::MessageTruncatedError</tt> – if the message was truncated.

  • <tt>ucxx::Error</tt> – if another error occurred.

bool isCompleted(
)#

Check whether the request has already completed.

Check whether the request has already completed. The status of the request must be verified with getStatus() before consumption.

Returns:

whether the request has completed.

void callback(
void *request,
ucs_status_t status
)#

Callback executed by UCX when request is completed.

Generic callback executed by UCX when a request is completed, used to set the status of the request and free any resources associated with it.

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.

virtual void populateDelayedSubmission(
) = 0#

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.

const std::string &getOwnerString(
) const#

Get formatted string with owner type and handle address.

Get a formatted string with owner type (worker or endpoint) and its respective handle address. This is meant to get logging information for a request’s callback, which is not a member attribute of ucxx::Request or derived class, but a static method or external function instead.

Returns:

the formatted string containing the owner type and its handle.

virtual std::shared_ptr<Buffer> getRecvBuffer(
)#

Get the received buffer.

This method is used to get the received buffer for applicable derived classes (e.g., RequestAm receive operations), in all other cases this will return nullptr. Before getting the received buffer it’s necessary to check that the request completed successfully either by validating getStatus() == UCS_OK or by checking the request completed with isCompleted() == true and that it did not error with checkError(), if any of those is unsuccessful this call returns nullptr.

Returns:

The received buffer (if applicable) or nullptr.

Request Data#

#include <ucxx/request_data.h>

namespace ucxx

namespace ucxx
namespace data#

Typedefs

using RequestData = std::variant<std::monostate, AmSend, AmReceive, EndpointClose, Flush, MemPut, MemGet, StreamSend, StreamReceive, TagSend, TagReceive, TagMultiSend, TagMultiReceive>#

Functions

template<class ...Ts>
dispatch(
Ts...
) -> dispatch<Ts...>#
template<class T>
RequestData getRequestData(
T t
)#
class AmSend#
#include <request_data.h>

Data for an Active Message send.

Type identifying an Active Message send operation and containing data specific to this request type.

Public Functions

explicit AmSend(
const decltype(_buffer) buffer,
const decltype(_length) length,
const decltype(_memoryType) memoryType = UCS_MEMORY_TYPE_HOST,
const decltype(_receiverCallbackInfo) receiverCallbackInfo = std::nullopt
)#

Constructor for Active Message-specific send data.

Construct an object containing Active Message-specific send data.

Parameters:

  • buffer – [in] a raw pointer to the data to be sent.

  • length – [in] the size in bytes of the message to be sent.

  • memoryType – [in] the memory type of the buffer.

  • receiverCallbackInfo – [in] the owner name and unique identifier of the receiver callback.

AmSend(
) = delete#

Public Members

const void *const _buffer = {nullptr}#

The raw pointer where data to be sent is stored.

const size_t _length = {0}#

The length of the message.

const ucs_memory_type_t _memoryType = {UCS_MEMORY_TYPE_HOST}#

Memory type used on the operation.

const std::optional<AmReceiverCallbackInfo> _receiverCallbackInfo{std::nullopt}#

Owner name and unique identifier of the receiver callback.

class AmReceive#
#include <request_data.h>

Data for an Active Message receive.

Type identifying an Active Message receive operation and containing data specific to this request type.

Public Functions

AmReceive(
)#

Constructor for Active Message-specific receive data.

Construct an object containing Active Message-specific receive data. Currently no specific data to receive Active Message is supported, but this class exists to act as an operation identifier, providing interface compatibility.

Public Members

std::shared_ptr<::ucxx::Buffer> _buffer = {nullptr}#

The AM received message buffer.

class EndpointClose#
#include <request_data.h>

Data for an endpoint close operation.

Type identifying an endpoint close operation and containing data specific to this request type.

Public Functions

explicit EndpointClose(
const decltype(_force) force
)#

Constructor for endpoint close-specific data.

Construct an object containing endpoint close-specific data.

Parameters:

force – [in] force endpoint close if true, flush otherwise.

EndpointClose(
) = delete#

Public Members

const bool _force = {false}#

Whether to force endpoint closing.

class Flush#
#include <request_data.h>

Data for a flush operation.

Type identifying a flush operation and containing data specific to this request type.

Public Functions

Flush()#

Constructor for flush-specific data.

Construct an object containing flush-specific data.

class MemPut#
#include <request_data.h>

Data for a memory send.

Type identifying a memory send operation and containing data specific to this request type.

Public Functions

explicit MemPut(
const decltype(_buffer) buffer,
const decltype(_length) length,
const decltype(_remoteAddr) remoteAddr,
const decltype(_rkey) rkey
)#

Constructor for memory-specific data.

Construct an object containing memory-specific data.

Parameters:

  • buffer – [in] a raw pointer to the data to be sent.

  • length – [in] the size in bytes of the tag message to be sent.

  • remoteAddr – [in] the destination remote memory address to write to.

  • rkey – [in] the remote memory key associated with the remote memory address.

MemPut(
) = delete#

Public Members

const void *const _buffer = {nullptr}#

The raw pointer where data to be sent is stored.

const size_t _length = {0}#

The length of the message.

const uint64_t _remoteAddr = {0}#

Remote memory address to write to.

const ucp_rkey_h _rkey = {}#

UCX remote key associated with the remote memory address.

class MemGet#
#include <request_data.h>

Data for a memory receive.

Type identifying a memory receive operation and containing data specific to this request type.

Public Functions

explicit MemGet(
decltype(_buffer) buffer,
const decltype(_length) length,
const decltype(_remoteAddr) remoteAddr,
const decltype(_rkey) rkey
)#

Constructor for memory-specific data.

Construct an object containing memory-specific data.

Parameters:

  • buffer – [out] a raw pointer to the received data.

  • length – [in] the size in bytes of the tag message to be received.

  • remoteAddr – [in] the source remote memory address to read from.

  • rkey – [in] the remote memory key associated with the remote memory address.

MemGet(
) = delete#

Public Members

void *_buffer = {nullptr}#

The raw pointer where received data should be stored.

const size_t _length = {0}#

The length of the message.

const uint64_t _remoteAddr = {0}#

Remote memory address to read from.

const ucp_rkey_h _rkey = {}#

UCX remote key associated with the remote memory address.

class StreamSend#
#include <request_data.h>

Data for a Stream send.

Type identifying a Stream send operation and containing data specific to this request type.

Public Functions

explicit StreamSend(
const decltype(_buffer) buffer,
const decltype(_length) length
)#

Constructor for stream-specific data.

Construct an object containing stream-specific data.

Parameters:

  • buffer – [in] a raw pointer to the data to be sent.

  • length – [in] the size in bytes of the tag message to be sent.

StreamSend(
) = delete#

Public Members

const void *const _buffer = {nullptr}#

The raw pointer where data to be sent is stored.

const size_t _length = {0}#

The length of the message.

class StreamReceive#
#include <request_data.h>

Data for an Stream receive.

Type identifying an Stream receive operation and containing data specific to this request type.

Public Functions

explicit StreamReceive(
decltype(_buffer) buffer,
const decltype(_length) length
)#

Constructor for stream-specific data.

Construct an object containing stream-specific data.

Parameters:

  • buffer – [out] a raw pointer to the received data.

  • length – [in] the size in bytes of the tag message to be received.

StreamReceive(
) = delete#

Public Members

void *_buffer = {nullptr}#

The raw pointer where received data should be stored.

const size_t _length = {0}#

The expected messaged length.

size_t _lengthReceived = {0}#

The actual received message length.

class TagSend#
#include <request_data.h>

Data for a Tag send.

Type identifying a Tag send operation and containing data specific to this request type.

Public Functions

explicit TagSend(
const decltype(_buffer) buffer,
const decltype(_length) length,
const decltype(_tag) tag
)#

Constructor for tag-specific data.

Construct an object containing tag-specific data.

Parameters:

  • buffer – [in] a raw pointer to the data to be sent.

  • length – [in] the size in bytes of the tag message to be sent.

  • tag – [in] the tag to match.

TagSend(
) = delete#

Public Members

const void *const _buffer = {nullptr}#

The raw pointer where data to be sent is stored.

const size_t _length = {0}#

The length of the message.

const ::ucxx::Tag _tag = {0}#

Tag to match.

class TagReceive#
#include <request_data.h>

Data for a Tag receive.

Type identifying a Tag receive operation and containing data specific to this request type.

Public Functions

explicit TagReceive(
decltype(_buffer) buffer,
const decltype(_length) length,
const decltype(_tag) tag,
const decltype(_tagMask) tagMask
)#

Constructor for tag-specific data.

Construct an object containing send tag-specific data.

Parameters:

  • buffer – [out] a raw pointer to the received data.

  • length – [in] the size in bytes of the tag message to be received.

  • tag – [in] the tag to match.

  • tagMask – [in] the tag mask to use (only used for receive operations).

TagReceive(
) = delete#

Public Members

void *_buffer = {nullptr}#

The raw pointer where received data should be stored.

const size_t _length = {0}#

The length of the message.

const ::ucxx::Tag _tag = {0}#

Tag to match.

const ::ucxx::TagMask _tagMask = {0}#

Tag mask to use.

class TagMultiSend#
#include <request_data.h>

Data for a multi-buffer Tag send.

Type identifying a multi-buffer Tag send operation and containing data specific to this request type.

Public Functions

explicit TagMultiSend(
const decltype(_buffer) &buffer,
const decltype(_length) &length,
const decltype(_isCUDA) &isCUDA,
const decltype(_tag) tag
)#

Constructor for send multi-buffer tag-specific data.

Construct an object containing tag/multi-buffer tag-specific data.

Parameters:

  • buffer – [in] a raw pointers to the data to be sent.

  • length – [in] the size in bytes of the tag messages to be sent.

  • isCUDA – [in] flags indicating whether buffers being sent are CUDA.

  • tag – [in] the tags to match.

TagMultiSend(
) = delete#

Public Members

const std::vector<const void*> _buffer = {}#

Raw pointers where data to be sent is stored.

const std::vector<size_t> _length = {}#

Lengths of messages.

const std::vector<int> _isCUDA = {}#

Flags indicating whether the buffer is CUDA or not.

const ::ucxx::Tag _tag = {0}#

Tag to match.

class TagMultiReceive#
#include <request_data.h>

Data for a multi-buffer Tag receive.

Type identifying a multi-buffer Tag receive operation and containing data specific to this request type.

Public Functions

explicit TagMultiReceive(
const decltype(_tag) tag,
const decltype(_tagMask) tagMask
)#

Constructor for receive multi-buffer tag-specific data.

Construct an object containing receive multi-buffer tag-specific data.

Parameters:

  • tag – [in] the tag to match.

  • tagMask – [in] the tag mask to use (only used for receive operations).

TagMultiReceive(
) = delete#

Public Members

const ::ucxx::Tag _tag = {0}#

Tag to match.

const ::ucxx::TagMask _tagMask = {0}#

Tag mask to use.

template<class ...Ts>
struct dispatch : public ucxx::data::Ts

Request Types: