Send or receive a message with the UCX Active Message API. More...
#include <request_am.h>
Public Member Functions | |
void | cancel () override |
Cancel the request. More... | |
void | populateDelayedSubmission () override |
Populate the internal submission dispatcher. More... | |
void | request () |
Create and submit an active message send request. More... | |
std::shared_ptr< Buffer > | getRecvBuffer () override |
Get the received buffer. More... | |
![]() | |
Request (const Request &)=delete | |
Request & | operator= (Request const &)=delete |
Request (Request &&o)=delete | |
Request & | operator= (Request &&o)=delete |
virtual | ~Request () |
ucxx::Request destructor. 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... | |
![]() | |
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 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 . More... | |
Friends | |
class | internal::RecvAmMessage |
std::shared_ptr< RequestAm > | createRequestAm (std::shared_ptr< Endpoint > endpoint, const std::variant< data::AmSend, data::AmReceive > requestData, const bool enablePythonFuture, RequestCallbackUserFunction callbackFunction, RequestCallbackUserData callbackData) |
Constructor for std::shared_ptr<ucxx::RequestAm> . More... | |
Additional Inherited Members | |
![]() | |
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... | |
![]() | |
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. | |
![]() | |
std::shared_ptr< Component > | _parent {nullptr} |
A reference-counted pointer to the parent. | |
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
.
|
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.
|
overridevirtual |
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
.
nullptr
. Reimplemented from ucxx::Request.
|
overridevirtual |
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.
|
static |
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.
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.
|
friend |
Constructor for std::shared_ptr<ucxx::RequestAm>
.
The constructor for a std::shared_ptr<ucxx::RequestAm>
object, creating an active message 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 if this is a send operation, or consumed if this is a receive operation. Received data is available via the getRecvBuffer()
method if the receive transfer request completed successfully.
ucxx::Error | if endpoint is not a valid std::shared_ptr<ucxx::Endpoint> . |
[in] | endpoint | the parent endpoint. |
[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. |
[in] | callbackFunction | user-defined callback function to call upon completion. |
[in] | callbackData | user-defined data to pass to the callbackFunction . |
shared_ptr<ucxx::RequestAm>
object