Send or receive a message with the UCX Stream API. More...

#include <request_stream.h>

Inheritance diagram for ucxx::RequestStream:

Public Member Functions
virtual void	populateDelayedSubmission ()
	Populate the internal submission dispatcher. More...

void	request ()
	Create and submit a stream request. More...

void	callback (void *request, ucs_status_t status, size_t length)
	Implementation of the stream receive request callback. More...

Public Member Functions inherited from ucxx::Request
	Request (const Request &)=delete

Request &	operator= (Request const &)=delete

	Request (Request &&o)=delete

Request &	operator= (Request &&o)=delete

virtual	~Request ()
	`ucxx::Request` destructor. More...

virtual void	cancel ()
	Cancel the request. More...

ucs_status_t	getStatus ()
	Return the status of the request. More...

void *	getFuture ()
	Return the future used to check on state. More...

void	checkError ()
	Check whether the request completed with an error. More...

bool	isCompleted ()
	Check whether the request has already completed. More...

void	callback (void *request, ucs_status_t status)
	Callback executed by UCX when request is completed. More...

const std::string &	getOwnerString () const
	Get formatted string with owner type and handle address. More...

virtual std::shared_ptr< Buffer >	getRecvBuffer ()
	Get the received buffer. More...

Public Member Functions inherited from ucxx::Component
void	setParent (std::shared_ptr< Component > parent)
	Set the internal parent reference. More...

std::shared_ptr< Component >	getParent () const
	Get the internal parent reference. More...

Static Public Member Functions
static void	streamSendCallback (void request, ucs_status_t status, void arg)
	Callback executed by UCX when a stream send request is completed. More...

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

Friends
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>`. More...

Additional Inherited Members
Protected Member Functions inherited from ucxx::Request
	Request (std::shared_ptr< Component > endpointOrWorker, const data::RequestData requestData, const std::string operationName, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
	Protected constructor of an abstract `ucxx::Request`. More...

void	process ()
	Perform initial processing of the request to determine if immediate completion. More...

void	setStatus (ucs_status_t status)
	Set the request status and notify Python future. More...

Protected Attributes inherited from ucxx::Request
ucs_status_t	_status {UCS_INPROGRESS}
	Requests status.

std::string	_status_msg {}
	Human-readable status message.

void *	_request {nullptr}
	Pointer to UCP request.

std::shared_ptr< Future >	_future {nullptr}
	Future to notify upon completion.

RequestCallbackUserFunction	_callback {nullptr}
	Completion callback.

RequestCallbackUserData	_callbackData {nullptr}
	Completion callback data.

std::shared_ptr< Worker >	_worker
	Worker that generated request (if not from endpoint) More...

std::shared_ptr< Endpoint >	_endpoint
	Endpoint that generated request (if not from worker) More...

std::string	_ownerString
	String to print owner (endpoint or worker) when logging. More...

data::RequestData	_requestData {}
	The operation-specific data to be used in the request.

std::string	_operationName
	Human-readable operation name, mostly used for log messages. More...

std::recursive_mutex	_mutex {}
	Mutex to prevent checking status while it's being set.

bool	_enablePythonFuture {true}
	Whether Python future is enabled for this request.

Protected Attributes inherited from ucxx::Component
std::shared_ptr< Component >	_parent {nullptr}
	A reference-counted pointer to the parent.

Detailed Description

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.

Member Function Documentation

◆ callback()

void ucxx::RequestStream::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

[in]	request	the UCX request pointer.
[in]	status	the completion status of the request.
[in]	length	length of message received used to verify for truncation.

◆ populateDelayedSubmission()

virtual void ucxx::RequestStream::populateDelayedSubmission ( )

virtual

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.

Implements ucxx::Request.

◆ request()

void ucxx::RequestStream::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.

◆ streamRecvCallback()

static void ucxx::RequestStream::streamRecvCallback	(	void *	request,
		ucs_status_t	status,
		size_t	length,
		void *	arg
	)

static

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

[in]	request	the UCX request pointer.
[in]	status	the completion status of the request.
[in]	length	length of message received used to verify for truncation.
[in]	arg	the pointer to the `ucxx::Request` object that created the transfer, effectively `this` pointer as seen by `request()`.

◆ streamSendCallback()

static void ucxx::RequestStream::streamSendCallback	(	void *	request,
		ucs_status_t	status,
		void *	arg
	)

static

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

[in]	request	the UCX request pointer.
[in]	status	the completion status of the request.
[in]	arg	the pointer to the `ucxx::Request` object that created the transfer, effectively `this` pointer as seen by `request()`.

Friends And Related Function Documentation

◆ createRequestStream

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

friend

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

[in]	endpoint	the `std::shared_ptr<Endpoint>` parent component
[in]	requestData	container of the specified message type, including all type-specific data.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.

Returns: The shared_ptr<ucxx::RequestStream> object

The documentation for this class was generated from the following file:

/__w/ucxx/ucxx/cpp/include/ucxx/request_stream.h

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ callback()

◆ populateDelayedSubmission()

◆ request()

◆ streamRecvCallback()

◆ streamSendCallback()

Friends And Related Function Documentation

◆ createRequestStream