ucxx::RequestAm Class Reference

Send or receive a message with the UCX Active Message API. More...

#include <request_am.h>

Inheritance diagram for ucxx::RequestAm:

Public Member Functions
void	cancel () override
	Cancel the request.
void	request ()
	Create and submit an active message send request.
std::shared_ptr< Buffer >	getRecvBuffer () override
	Get the received buffer.
std::string	getRecvHeader () override
	Get the received user header.
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.
ucs_status_t	getStatus ()
	Return the status of the request.
void *	getFuture ()
	Return the future used to check on state.
void	checkError ()
	Check whether the request completed with an error.
bool	isCompleted ()
	Check whether the request has already completed.
void	callback (void *request, ucs_status_t status)
	Callback executed by UCX when request is completed.
void	populateDelayedSubmission ()
	Populate the internal submission dispatcher.
const std::string &	getOwnerString () const
	Get formatted string with owner type and handle address.
Attributes	queryAttributes ()
	Get the requests's attributes.
Public Member Functions inherited from ucxx::Component
void	setParent (std::shared_ptr< Component > parent)
	Set the internal parent reference.
std::shared_ptr< Component >	getParent () const
	Get the internal parent reference.

Static Public Member Functions
static ucs_status_t	recvCallback (void *arg, const void *header, size_t header_length, void *data, size_t length, const ucp_am_recv_param_t *param)
	Receive callback registered by ucxx::Worker.

Friends
class	internal::RecvAmMessage
class	detail::ConstructorFactory

Additional Inherited Members
Protected Member Functions inherited from ucxx::Request
	Request (std::shared_ptr< Component > endpointOrWorker, const data::RequestData requestData, std::string operationName, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
	Protected constructor of an abstract ucxx::Request.
void	process ()
	Perform initial processing of the request to determine if immediate completion.
void	setStatus (ucs_status_t status)
	Set the request status and notify Python future.
void	publishRequest (void *request)
	Publish the UCP request handle and capture its attributes.
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.
std::shared_ptr< Worker >	_worker
	Worker that generated request (if not from endpoint).
std::shared_ptr< Endpoint >	_endpoint
	Endpoint that generated request (if not from worker).
std::string	_ownerString
	String to print owner (endpoint or worker) when logging.
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.
bool	_enablePythonFuture {true}
	Whether Python future is enabled for this request.
RequestCallbackUserFunction	_callback {nullptr}
	Completion callback.
RequestCallbackUserData	_callbackData {nullptr}
	Completion callback data.
Attributes	_requestAttr {}
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 Active Message API.

Send or receive a message with the UCX Active Message API, using non-blocking UCP calls ucp_am_send_nbx or ucp_am_recv_data_nbx.

Member Function Documentation

cancel()

void ucxx::RequestAm::cancel ( )

overridevirtual

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

getRecvBuffer()

std::shared_ptr< Buffer > ucxx::RequestAm::getRecvBuffer ( )

nodiscardoverridevirtual

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

getRecvHeader()

std::string ucxx::RequestAm::getRecvHeader ( )

nodiscardoverridevirtual

Get the received user header.

This method is used to get the user-defined header bytes for applicable derived classes (e.g., RequestAm receive operations), in all other cases this will return an empty string.

Returns

The received user header (if applicable) or an empty string.

Reimplemented from ucxx::Request.

recvCallback()

ucs_status_t ucxx::RequestAm::recvCallback ( void * arg, const void * header, size_t header_length, void * data, size_t length, const ucp_am_recv_param_t * param )

staticnodiscard

Receive callback registered by ucxx::Worker.

This is the receive callback registered by the ucxx::Worker to handle incoming active messages. For each incoming active message, a proper buffer will be allocated based on the header sent by the remote endpoint using the default allocator or one registered by the user via ucxx::Worker::registerAmAllocator(). Following that, the message is immediately received onto the buffer and a UCS_OK or the proper error status is set onto the RequestAm that is returned to the user, or will be later handled by another callback when the message is ready. If the callback is executed when a user has already requested received of the active message, the buffer and status will be set on the earliest request, otherwise a new request is created and saved in a pool that will be already populated and ready for consumption or waiting for the internal callback when requested.

This is always called by ucp_worker_progress(), and thus will happen in the same thread that is called from, when using the worker progress thread, this is called from the progress thread.

param[in,out] arg pointer to the AmData object held by the ucxx::Worker who registered this callback. param[in] header pointer to the header containing the sender buffer's memory type. param[in] header_length length in bytes of the receive header. param[in] data pointer to the buffer containing the remote endpoint's send data. param[in] length the length in bytes of the message to be received. param[in] param UCP parameters of the active message being received.

request()

void ucxx::RequestAm::request

(

)

Create and submit an active message send request.

This is the method that should be called to actually submit an active message send 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.

---

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

• /__w/ucxx/ucxx/cpp/include/ucxx/request_am.h