Stream Request

Stream Request#

2026-03-31

5 min read time

Applies to Linux

The ucxx::RequestStream class implements non-blocking stream-based send and receive operations using the UCX Stream API. Stream communication provides ordered, byte-stream semantics over an endpoint.

#include <ucxx/request_stream.h>

namespace ucxx

class RequestStream : public ucxx::Request#

Send or receive a message with the UCX Stream API.

Send or receive a message with the UCX Stream API, using non-blocking UCP calls ucp_stream_send_nbx or ucp_stream_recv_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 stream request.

This is the method that should be called to actually submit a stream 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.

void callback(
void *request,
ucs_status_t status,
size_t length
)#

Implementation of the stream receive request callback.

Implementation of the stream receive request callback. Verify whether the message was truncated and set that state if necessary, and finally 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.

  • length – [in] length of message received used to verify for truncation.

Public Static Functions

static void streamSendCallback(
void *request,
ucs_status_t status,
void *arg
)#

Callback executed by UCX when a stream send request is completed.

Callback executed by UCX when a stream send 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 streamRecvCallback(
void *request,
ucs_status_t status,
size_t length,
void *arg
)#

Callback executed by UCX when a stream receive request is completed.

Callback executed by UCX when a stream receive request is completed, that will dispatch ucxx::RequestStream::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.

  • length – [in] length of message received used to verify for truncation.

  • 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<RequestStream> createRequestStream(
std::shared_ptr<Endpoint> endpoint,
const std::variant<data::StreamSend, data::StreamReceive> requestData,
const bool enablePythonFuture
)#

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

The constructor for a std::shared_ptr<ucxx::RequestStream> object, creating a send or receive stream 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 the data can be released (for a send operation) or consumed (for a receive operation).

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.

Returns:

The shared_ptr<ucxx::RequestStream> object

Factory Functions#

#include <ucxx/constructors.h>

std::shared_ptr<RequestStream> ucxx::createRequestStream(
std::shared_ptr<Endpoint> endpoint,
const std::variant<data::StreamSend, data::StreamReceive> requestData,
const bool enablePythonFuture
)#

The constructor for a std::shared_ptr<ucxx::RequestStream> object, creating a send or receive stream 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 the data can be released (for a send operation) or consumed (for a receive operation).

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.

Returns:

The shared_ptr<ucxx::RequestStream> object