Request#
2026-07-06
13 min read time
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::Requestdestructor.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_tthat may be used for more fine-grained error handling than relying oncheckError()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
nullptrotherwise.- 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()orgetStatus()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(
Populate the internal submission dispatcher.
The
ucxx::Requestutilizesucxx::DelayedSubmissionto 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(
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::Requestor 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.,
RequestAmreceive operations), in all other cases this will returnnullptr. Before getting the received buffer it’s necessary to check that the request completed successfully either by validatinggetStatus() == UCS_OKor by checking the request completed withisCompleted() == trueand that it did not error withcheckError(), if any of those is unsuccessful this call returnsnullptr.- Returns:
The received buffer (if applicable) or
nullptr.
- virtual std::string getRecvHeader(
Get the received user header.
This method is used to get the user-defined header bytes for applicable derived classes (e.g.,
RequestAmreceive operations), in all other cases this will return an empty string.- Returns:
The received user header (if applicable) or an empty string.
- Attributes queryAttributes(
Get the requests’s attributes.
Returns the request attributes as a struct. The owning
ucxx::Workermust have been created with request attributes querying enabled (seeucxx::experimental::WorkerBuilder::requestAttributes()); otherwise the attributes are never populated and this method throws. Querying the underlying UCP request is an implementation detail performed eagerly when the request is submitted. All non-status fields exposed by UCP are queried, usegetStatus()to obtain the status.- Throws:
ucxx::UnsupportedError – if the owning worker was not built with request attributes querying enabled. Requires
Workercreated withucxx::experimental::WorkerBuilder::requestAttributes(true).ucxx::NoElemError – if attributes are unavailable for this specific request: either because UCX took an inline-completion path that produced no UCP request to query, or because the request has not completed yet. Callers can distinguish the latter from the former by checking
isCompleted().
- Returns:
An
Attributescontaining the request attributes.
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, TagReceiveWithHandle, TagMultiSend, TagMultiReceive>#
Functions
-
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 AmSendParams ¶ms = AmSendParams{}
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.
params – [in] send parameters controlling datatype/flags/policies.
- explicit AmSend(
- decltype(_iov) iov,
- const AmSendParams ¶ms = AmSendParams{}
Constructor for Active Message-specific send data using IOV datatype.
Construct an object containing Active Message-specific send data for
UCP_DATATYPE_IOV.- Parameters:
iov – [in] vector of IOV segments to send.
params – [in] send parameters controlling datatype/flags/policies.
- AmSend(
Public Members
-
const void *const _buffer = {nullptr}#
The raw pointer where data to be sent is stored.
-
const size_t _length = {0}#
Message length in bytes (contiguous datatype only).
-
const std::vector<ucp_dt_iov_t> _iov = {}#
Segments for IOV datatype.
-
const size_t _count = {0}#
Count passed to
ucp_am_send_nbx: byte count for contiguous, number of IOV segments for IOV.
-
const uint32_t _flags = {UCP_AM_SEND_FLAG_REPLY}#
UCP AM send flags.
-
const ucp_datatype_t _datatype = {ucp_dt_make_contig(1)}#
UCP datatype.
-
const ucs_memory_type_t _memoryType = {UCS_MEMORY_TYPE_HOST}#
Memory type used on the operation.
-
const AmSendMemoryTypePolicy _memoryTypePolicy{AmSendMemoryTypePolicy::FallbackToHost}#
Receiver allocation policy.
-
const std::optional<AmReceiverCallbackInfo> _receiverCallbackInfo{std::nullopt}#
Owner name and unique identifier of the receiver callback.
-
const std::vector<std::byte> _userHeader = {}#
Opaque user-defined header bytes.
-
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.
-
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(
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.
-
Flush()#
-
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(
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(
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.
-
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.
-
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.
-
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(
-
class TagReceiveWithHandle#
- #include <request_data.h>
Data for a Tag receive using a message handle.
Type identifying a Tag receive operation using a message handle and containing data specific to this request type.
Public Functions
- decltype(_buffer) buffer,
- std::shared_ptr<TagProbeInfo> probeInfo
Constructor for tag receive with handle-specific data.
Construct an object containing tag receive with handle-specific data.
- Parameters:
buffer – [out] a raw pointer to the received data. The buffer must be large enough to hold the message data, otherwise the behavior is undefined. The buffer must be pre-allocated.
probeInfo – [in] the TagProbeInfo object containing message length and handle.
- TagReceiveWithHandle(
-
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(
-
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( )#
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(
-
using RequestData = std::variant<std::monostate, AmSend, AmReceive, EndpointClose, Flush, MemPut, MemGet, StreamSend, StreamReceive, TagSend, TagReceive, TagReceiveWithHandle, TagMultiSend, TagMultiReceive>#
-
namespace data#