Base type for a UCXX transfer request. More...

#include <request.h>

Inheritance diagram for ucxx::Request:

Public Member Functions
	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...

virtual void	populateDelayedSubmission ()=0
	Populate the internal submission dispatcher. 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...

Protected Member Functions
	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
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.

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

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

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

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

RequestCallbackUserFunction	_callback {nullptr}
	Completion callback.

RequestCallbackUserData	_callbackData {nullptr}
	Completion callback data.

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

Detailed Description

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.

Constructor & Destructor Documentation

◆ Request()

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

Protected constructor of an abstract ucxx::Request.

Construct an abstract request, registering the request to the appropriate parent (either an endpoint or a worker) so that it may be canceled if necessary. This constructor is also responsible for populating a ucxx::DelayedSubmission object that will effectively dispatch the request when appropriate (either immediately or a the next worker progress iteration), as well as create Python futures that can be later awaited in Python asynchronous code.

Parameters

[in]	endpointOrWorker	the parent component, which may either be a `std::shared_ptr<Endpoint>` or `std::shared_ptr<Worker>`.
[in]	requestData	the operation-specific data to be used in the request.
[in]	operationName	a human-readable operation name to help identifying requests by their types when UCXX logging is enabled.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.

◆ ~Request()

virtual ucxx::Request::~Request ( )

virtual

ucxx::Request destructor.

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

Member Function Documentation

◆ callback()

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

[in]	request	the UCX request pointer.
[in]	status	the completion status of the request.

◆ cancel()

virtual void ucxx::Request::cancel ( )

virtual

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.

Reimplemented in ucxx::RequestTagMulti, and ucxx::RequestAm.

◆ checkError()

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

Exceptions

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

◆ getFuture()

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

◆ getOwnerString()

const std::string& ucxx::Request::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.

◆ getRecvBuffer()

virtual std::shared_ptr<Buffer> ucxx::Request::getRecvBuffer ( )

virtual

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.

Reimplemented in ucxx::RequestAm.

◆ getStatus()

ucs_status_t ucxx::Request::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.

◆ isCompleted()

bool ucxx::Request::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.

◆ populateDelayedSubmission()

virtual void ucxx::Request::populateDelayedSubmission ( )

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

Implemented in ucxx::RequestTagMulti, ucxx::RequestAm, ucxx::RequestTag, ucxx::RequestStream, ucxx::RequestMem, ucxx::RequestFlush, and ucxx::RequestEndpointClose.

◆ process()

void ucxx::Request::process ( )

protected

Perform initial processing of the request to determine if immediate completion.

Perform initial processing of the requeste, determining whether it completed immediately, in which case it will set its status and call a user-defined callback (when registered by the derived class), otherwise do nothing until the UCX operation completes and the internal callback is executed to finally set its state.

◆ setStatus()

void ucxx::Request::setStatus ( ucs_status_t status )

protected

Set the request status and notify Python future.

Set the request status and notify the Python future of the status change if the object was created with Python support. Intended to be called only once when the request status changes to its final state.

Parameters

[in] status the status of the request to be set.

Member Data Documentation

◆ _endpoint

std::shared_ptr<Endpoint> ucxx::Request::_endpoint

protected

Initial value:

{

nullptr}

Endpoint that generated request (if not from worker)

◆ _operationName

std::string ucxx::Request::_operationName

protected

Initial value:

{

"request_undefined"}

Human-readable operation name, mostly used for log messages.

◆ _ownerString

std::string ucxx::Request::_ownerString

protected

Initial value:

{

"undetermined owner"}

String to print owner (endpoint or worker) when logging.

◆ _worker

std::shared_ptr<Worker> ucxx::Request::_worker

protected

Initial value:

{

nullptr}

Worker that generated request (if not from endpoint)

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

/__w/ucxx/ucxx/cpp/include/ucxx/request.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Request()

◆ ~Request()

Member Function Documentation

◆ callback()

◆ cancel()

◆ checkError()

◆ getFuture()

◆ getOwnerString()

◆ getRecvBuffer()

◆ getStatus()

◆ isCompleted()

◆ populateDelayedSubmission()

◆ process()

◆ setStatus()

Member Data Documentation

◆ _endpoint

◆ _operationName

◆ _ownerString

◆ _worker