All Classes Namespaces Functions Variables Typedefs Enumerations Friends
Public Member Functions | Friends | List of all members
ucxx::Endpoint Class Reference

Component encapsulating a UCP endpoint. More...

#include <endpoint.h>

Inheritance diagram for ucxx::Endpoint:
ucxx::Component

Public Member Functions

 Endpoint (const Endpoint &)=delete
 
Endpointoperator= (Endpoint const &)=delete
 
 Endpoint (Endpoint &&o)=delete
 
Endpointoperator= (Endpoint &&o)=delete
 
ucp_ep_h getHandle ()
 Get the underlying ucp_ep_h handle. More...
 
bool isAlive () const
 Check whether the endpoint is still alive. More...
 
void raiseOnError ()
 Raises an exception if an error occurred. More...
 
void removeInflightRequest (const Request *const request)
 Remove reference to request from internal container. More...
 
size_t cancelInflightRequests ()
 Cancel inflight requests. More...
 
size_t getCancelingSize () const
 Check the number of inflight requests being canceled. More...
 
size_t cancelInflightRequestsBlocking (uint64_t period=0, uint64_t maxAttempts=1)
 Cancel inflight requests. More...
 
void setCloseCallback (EndpointCloseCallbackUserFunction closeCallback, EndpointCloseCallbackUserData closeCallbackArg)
 Register a user-defined callback to call when endpoint closes. More...
 
std::shared_ptr< RequestamSend (void *buffer, const size_t length, const ucs_memory_type_t memoryType, const std::optional< AmReceiverCallbackInfo > receiverCallbackInfo=std::nullopt, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue an active message send operation. More...
 
std::shared_ptr< RequestamRecv (const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue an active message receive operation. More...
 
std::shared_ptr< RequestmemPut (void *buffer, size_t length, uint64_t remote_addr, ucp_rkey_h rkey, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue a memory put operation. More...
 
std::shared_ptr< RequestmemPut (void *buffer, size_t length, std::shared_ptr< ucxx::RemoteKey > remoteKey, uint64_t remoteAddrOffset=0, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue a memory put operation. More...
 
std::shared_ptr< RequestmemGet (void *buffer, size_t length, uint64_t remoteAddr, ucp_rkey_h rkey, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue a memory get operation. More...
 
std::shared_ptr< RequestmemGet (void *buffer, size_t length, std::shared_ptr< ucxx::RemoteKey > remoteKey, uint64_t remoteAddrOffset=0, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue a memory get operation. More...
 
std::shared_ptr< RequeststreamSend (void *buffer, size_t length, const bool enablePythonFuture)
 Enqueue a stream send operation. More...
 
std::shared_ptr< RequeststreamRecv (void *buffer, size_t length, const bool enablePythonFuture)
 Enqueue a stream receive operation. More...
 
std::shared_ptr< RequesttagSend (void *buffer, size_t length, Tag tag, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue a tag send operation. More...
 
std::shared_ptr< RequesttagRecv (void *buffer, size_t length, Tag tag, TagMask tagMask, const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue a tag receive operation. More...
 
std::shared_ptr< RequesttagMultiSend (const std::vector< void * > &buffer, const std::vector< size_t > &size, const std::vector< int > &isCUDA, const Tag tag, const bool enablePythonFuture)
 Enqueue a multi-buffer tag send operation. More...
 
std::shared_ptr< RequesttagMultiRecv (const Tag tag, const TagMask tagMask, const bool enablePythonFuture)
 Enqueue a multi-buffer tag receive operation. More...
 
std::shared_ptr< Requestflush (const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
 Enqueue a flush operation. More...
 
std::shared_ptr< WorkergetWorker ()
 Get ucxx::Worker component from a worker or listener object. More...
 
std::shared_ptr< Requestclose (const bool enablePythonFuture=false, EndpointCloseCallbackUserFunction callbackFunction=nullptr, EndpointCloseCallbackUserData callbackData=nullptr)
 Enqueue a non-blocking endpoint close operation. More...
 
void closeBlocking (uint64_t period=0, uint64_t maxAttempts=1)
 Close the endpoint while keeping the object alive. More...
 
- Public Member Functions inherited from ucxx::Component
void setParent (std::shared_ptr< Component > parent)
 Set the internal parent reference. More...
 
std::shared_ptr< ComponentgetParent () const
 Get the internal parent reference. More...
 

Friends

void endpointErrorCallback (void *arg, ucp_ep_h ep, ucs_status_t status)
 The error callback registered at endpoint creation time. More...
 
std::shared_ptr< EndpointcreateEndpointFromHostname (std::shared_ptr< Worker > worker, std::string ipAddress, uint16_t port, bool endpointErrorHandling)
 Constructor for shared_ptr<ucxx::Endpoint>. More...
 
std::shared_ptr< EndpointcreateEndpointFromConnRequest (std::shared_ptr< Listener > listener, ucp_conn_request_h connRequest, bool endpointErrorHandling)
 Constructor for shared_ptr<ucxx::Endpoint>. More...
 
std::shared_ptr< EndpointcreateEndpointFromWorkerAddress (std::shared_ptr< Worker > worker, std::shared_ptr< Address > address, bool endpointErrorHandling)
 Constructor for shared_ptr<ucxx::Endpoint>. More...
 

Additional Inherited Members

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

Detailed Description

Component encapsulating a UCP endpoint.

The UCP layer provides a handle to access endpoints in form of ucp_ep_h object, this class encapsulates that object and provides methods to simplify its handling.

Member Function Documentation

◆ amRecv()

std::shared_ptr<Request> ucxx::Endpoint::amRecv ( const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue an active message receive operation.

Enqueue an active message receive operation, returning a std::shared_ptr<ucxx::Request> that can be later awaited and checked for errors, making data available via the return value's getRecvBuffer() method once the operation completes successfully. 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 consumed.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
[in]callbackFunctionuser-defined callback function to call upon completion.
[in]callbackDatauser-defined data to pass to the callbackFunction.
Returns
Request to be subsequently checked for the completion state and data.

◆ amSend()

std::shared_ptr<Request> ucxx::Endpoint::amSend ( void *  buffer,
const size_t  length,
const ucs_memory_type_t  memoryType,
const std::optional< AmReceiverCallbackInfo receiverCallbackInfo = std::nullopt,
const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue an active message send operation.

Enqueue an active message send operation, returning a std::shared_ptr<ucxx::Request> 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.

An optional receiverCallbackInfo may be specified, in which case the remote worker obligatorily needs to have registered a callback with the same receiverCallbackInfo in order to execute the callback when the active message is received. When this is specified, amRecv() will NOT match this message, which is instead handled by the remote worker's callback.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to the data to be sent.
[in]lengththe size in bytes of the tag message to be sent.
[in]memoryTypethe memory type of the buffer.
[in]receiverCallbackInfothe owner name and unique identifier of the receiver callback.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
[in]callbackFunctionuser-defined callback function to call upon completion.
[in]callbackDatauser-defined data to pass to the callbackFunction.
Returns
Request to be subsequently checked for the completion and its state.

◆ cancelInflightRequests()

size_t ucxx::Endpoint::cancelInflightRequests ( )

Cancel inflight requests.

Cancel inflight requests, returning the total number of requests that were scheduled for cancelation. After the requests are scheduled for cancelation, the caller must progress the worker and check the result of getCancelingSize(), all requests are only canceled when getCancelingSize() returns 0.

Returns
Number of requests that were scheduled for cancelation.

◆ cancelInflightRequestsBlocking()

size_t ucxx::Endpoint::cancelInflightRequestsBlocking ( uint64_t  period = 0,
uint64_t  maxAttempts = 1 
)

Cancel inflight requests.

Cancel inflight requests and block until all requests complete cancelation, returning the total number of requests that were canceled. This is usually executed by closeBlocking(), when pending requests will no longer be able to complete.

If the parent worker is running a progress thread, a maximum timeout may be specified for which the close operation will wait. This can be particularly important for cases where the progress thread might be attempting to acquire a resource (e.g., the Python GIL) while the current thread owns that resource. In particular for Python, the ~Endpoint() will call this method for which we can't release the GIL when the garbage collector runs and destroys the object.

Parameters
[in]periodmaximum period to wait for a generic pre/post progress thread operation will wait for.
[in]maxAttemptsmaximum number of attempts to close endpoint, only applicable if worker is running a progress thread and period > 0.
Returns
Number of requests that were canceled.

◆ close()

std::shared_ptr<Request> ucxx::Endpoint::close ( const bool  enablePythonFuture = false,
EndpointCloseCallbackUserFunction  callbackFunction = nullptr,
EndpointCloseCallbackUserData  callbackData = nullptr 
)

Enqueue a non-blocking endpoint close operation.

Enqueue a non-blocking endpoint close operation, which will close the endpoint without requiring to destroy the object. This may be useful when other std::shared_ptr<ucxx::Request> objects are still alive, such as inflight transfers.

This method returns a std::shared<ucxx::Request> that can be later awaited and checked for errors. This is a non-blocking operation, and the status of closing the endpoint must be verified from the resulting request object before the std::shared_ptr<ucxx::Endpoint> can be safely destroyed and the UCP endpoint assumed inactive (closed). If the endpoint is already closed or in process of closing, nullptr is returned instead.

If the endpoint was created with error handling support, the error callback will be executed, implying the user-defined callback will also be executed.

If a user-defined callback is specified via the callbackFunction argument then that callback will be executed, if not then the callback registered with setCloseCallback() will be executed, if neither was specified then no user-defined callback will be executed.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the close operation has completed. Requires UCXX Python support.

Warning
Unlike its closeBlocking() counterpart, this method does not cancel any inflight requests prior to submitting the UCP close request. Before scheduling the endpoint close request, the caller must first call cancelInflightRequests() and progress the worker until getCancelingSize() returns 0.
Parameters
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
[in]callbackFunctionuser-defined callback function to call upon completion.
[in]callbackDatauser-defined data to pass to the callbackFunction.
Returns
Request to be subsequently checked for the completion and its state, or nullptr if the endpoint has already closed or is already in process of closing.

◆ closeBlocking()

void ucxx::Endpoint::closeBlocking ( uint64_t  period = 0,
uint64_t  maxAttempts = 1 
)

Close the endpoint while keeping the object alive.

Close the endpoint without requiring to destroy the object, blocking until the operation completes. This may be useful when std::shared_ptr<ucxx::Request> objects are still alive.

If the endpoint was created with error handling support, the error callback will be executed, implying the user-defined callback will also be executed if one was registered with setCloseCallback().

If the parent worker is running a progress thread, a maximum timeout may be specified for which the close operation will wait. This can be particularly important for cases where the progress thread might be attempting to acquire a resource (e.g., the Python GIL) while the current thread owns that resource. In particular for Python, the ~Endpoint() will call this method for which we can't release the GIL when the garbage collector runs and destroys the object.

Parameters
[in]periodmaximum period to wait for a generic pre/post progress thread operation will wait for.
[in]maxAttemptsmaximum number of attempts to close endpoint, only applicable if worker is running a progress thread and period > 0.

◆ flush()

std::shared_ptr<Request> ucxx::Endpoint::flush ( const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue a flush operation.

Enqueue request to flush outstanding AMO (Atomic Memory Operation) and RMA (Remote Memory Access) operations on the endpoint, returning a pointer to a request object that can be later awaited and checked for errors. This is a non-blocking operation, and its status must be verified from the resulting request object to confirm the flush operation has completed successfully.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to the data to be sent.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
[in]callbackFunctionuser-defined callback function to call upon completion.
[in]callbackDatauser-defined data to pass to the callbackFunction.
Returns
Request to be subsequently checked for the completion and its state.

◆ getCancelingSize()

size_t ucxx::Endpoint::getCancelingSize ( ) const

Check the number of inflight requests being canceled.

Check the number of inflight requests that were scheduled for cancelation with cancelInflightRequests() who have not yet completed cancelation. To ensure their cancelation is completed, the worker must be progressed until this method returns 0.

Returns
Number of requests that are in process of cancelation.

◆ getHandle()

ucp_ep_h ucxx::Endpoint::getHandle ( )

Get the underlying ucp_ep_h handle.

Lifetime of the ucp_ep_h handle is managed by the ucxx::Endpoint object and its ownership is non-transferrable. Once the ucxx::Endpoint is destroyed the handle is not valid anymore, it is the user's responsibility to ensure the owner's lifetime while using the handle.

// endpoint is `std::shared_ptr<ucxx::Endpoint>`
ucp_ep_h endpointHandle = endpoint->getHandle();
Returns
The underlying ucp_ep_h handle.

◆ getWorker()

std::shared_ptr<Worker> ucxx::Endpoint::getWorker ( )

Get ucxx::Worker component from a worker or listener object.

A std::shared_ptr<ucxx::Endpoint> needs to be created and registered by std::shared_ptr<ucxx::Worker>, but the endpoint may be a child of a std::shared_ptr<ucxx::Listener> object. For convenience, this method can be used to get the std::shared_ptr<ucxx::Worker> which the endpoint is associated with.

Returns
The std::shared_ptr<ucxx::Worker> which the endpoint is associated with.

◆ isAlive()

bool ucxx::Endpoint::isAlive ( ) const

Check whether the endpoint is still alive.

Check whether the endpoint is still alive, generally true until closeBlocking() is called, close() is called and the returned request completes or the endpoint errors and the error handling procedure is executed. Always true if endpoint error handling is disabled.

Returns
whether the endpoint is still alive if endpoint enables error handling, always returns true if error handling is disabled.

◆ memGet() [1/2]

std::shared_ptr<Request> ucxx::Endpoint::memGet ( void *  buffer,
size_t  length,
std::shared_ptr< ucxx::RemoteKey remoteKey,
uint64_t  remoteAddrOffset = 0,
const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue a memory get operation.

Enqueue a memory operation, returning a std::shared<ucxx::Request> 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 both local and remote data can be released and the local data can be consumed.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to the data to be sent.
[in]lengththe size in bytes of the tag message to be sent.
[in]remoteKeythe remote memory key associated with the remote memory address.
[in]remoteAddrOffsetthe destination remote memory address offset where to start reading from, 0 means start writing from beginning of the base address.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
Returns
Request to be subsequently checked for the completion and its state.

◆ memGet() [2/2]

std::shared_ptr<Request> ucxx::Endpoint::memGet ( void *  buffer,
size_t  length,
uint64_t  remoteAddr,
ucp_rkey_h  rkey,
const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue a memory get operation.

Enqueue a memory operation, returning a std::shared<ucxx::Request> 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 both local and remote data can be released and the local data can be consumed.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to the data to be sent.
[in]lengththe size in bytes of the tag message to be sent.
[in]remoteAddrthe source remote memory address to read from.
[in]rkeythe remote memory key associated with the remote memory address.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
Returns
Request to be subsequently checked for the completion and its state.

◆ memPut() [1/2]

std::shared_ptr<Request> ucxx::Endpoint::memPut ( void *  buffer,
size_t  length,
std::shared_ptr< ucxx::RemoteKey remoteKey,
uint64_t  remoteAddrOffset = 0,
const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue a memory put operation.

Enqueue a memory operation, returning a std::shared<ucxx::Request> 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 both local and remote data can be released and the remote data can be consumed.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to the data to be sent.
[in]lengththe size in bytes of the tag message to be sent.
[in]remoteKeythe remote memory key associated with the remote memory address.
[in]remoteAddrOffsetthe destination remote memory address offset where to start writing to, 0 means start writing from beginning of the base address.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
Returns
Request to be subsequently checked for the completion and its state.

◆ memPut() [2/2]

std::shared_ptr<Request> ucxx::Endpoint::memPut ( void *  buffer,
size_t  length,
uint64_t  remote_addr,
ucp_rkey_h  rkey,
const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue a memory put operation.

Enqueue a memory operation, returning a std::shared<ucxx::Request> 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 both local and remote data can be released and the remote data can be consumed.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to the data to be sent.
[in]lengththe size in bytes of the tag message to be sent.
[in]remoteAddrthe destination remote memory address to write to.
[in]rkeythe remote memory key associated with the remote memory address.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
Returns
Request to be subsequently checked for the completion and its state.

◆ raiseOnError()

void ucxx::Endpoint::raiseOnError ( )

Raises an exception if an error occurred.

Raises an exception if an error occurred and error handling is enabled for the endpoint, no-op otherwise.

Exceptions
ucxx::ConnectionResetErrorif UCP_ERR_CONNECTION_RESET occurred.
ucxx::Errorif any other UCP error occurred.

◆ removeInflightRequest()

void ucxx::Endpoint::removeInflightRequest ( const Request *const  request)

Remove reference to request from internal container.

Remove the reference to a specific request from the internal container. This should be called when a request has completed and the ucxx::Endpoint does not need to keep track of it anymore. The raw pointer to a ucxx::Request is passed here as opposed to the usual std::shared_ptr<ucxx::Request> used elsewhere, this is because the raw pointer address is used as key to the requests reference, and this is called from the object's destructor.

Parameters
[in]requestraw pointer to the request

◆ setCloseCallback()

void ucxx::Endpoint::setCloseCallback ( EndpointCloseCallbackUserFunction  closeCallback,
EndpointCloseCallbackUserData  closeCallbackArg 
)

Register a user-defined callback to call when endpoint closes.

Register a user-defined callback and argument that is later called immediately after the endpoint closes. The callback is executed either if the endpoint closed successfully after completing and disconnecting from the remote endpoint, but more importantly when any error occurs, allowing the application to be notified immediately after such an event occurred.

Exceptions
std::runtime_errorif the endpoint is closing or has already closed and this is not removing the close callback (setting both closeCallback and closeCallbackArg to nullptr)
Parameters
[in]closeCallbackstd::function to a function definition return void and receiving a single opaque pointer.
[in]closeCallbackArgpointer to optional user-allocated callback argument.

◆ streamRecv()

std::shared_ptr<Request> ucxx::Endpoint::streamRecv ( void *  buffer,
size_t  length,
const bool  enablePythonFuture 
)

Enqueue a stream receive operation.

Enqueue a stream receive operation, returning a std::shared<ucxx::Request> 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 consumed.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to pre-allocated memory where resulting data will be stored.
[in]lengththe size in bytes of the tag message to be received.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
Returns
Request to be subsequently checked for the completion and its state.

◆ streamSend()

std::shared_ptr<Request> ucxx::Endpoint::streamSend ( void *  buffer,
size_t  length,
const bool  enablePythonFuture 
)

Enqueue a stream send operation.

Enqueue a stream send operation, returning a std::shared<ucxx::Request> 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.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to the data to be sent.
[in]lengththe size in bytes of the tag message to be sent.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
Returns
Request to be subsequently checked for the completion and its state.

◆ tagMultiRecv()

std::shared_ptr<Request> ucxx::Endpoint::tagMultiRecv ( const Tag  tag,
const TagMask  tagMask,
const bool  enablePythonFuture 
)

Enqueue a multi-buffer tag receive operation.

Enqueue a multi-buffer tag receive operation, returning a std::shared<ucxx::RequestTagMulti> that can be later awaited and checked for errors. This is a non-blocking operation, and because the receiver has no a priori knowledge of the data being received, memory allocations are automatically handled internally. The receiver must have the same capabilities of the sender, so that if the sender is compiled with RMM support to allow for CUDA transfers, the receiver must have the ability to understand and allocate CUDA memory.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]tagthe tag to match.
[in]tagMaskthe tag mask to use.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
Returns
Request to be subsequently checked for the completion and its state.

◆ tagMultiSend()

std::shared_ptr<Request> ucxx::Endpoint::tagMultiSend ( const std::vector< void * > &  buffer,
const std::vector< size_t > &  size,
const std::vector< int > &  isCUDA,
const Tag  tag,
const bool  enablePythonFuture 
)

Enqueue a multi-buffer tag send operation.

Enqueue a multi-buffer tag send operation, returning a std::shared<ucxx::RequestTagMulti> 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.

The primary use of multi-buffer transfers is in Python where we want to reduce the amount of futures needed to watch for, thus reducing Python overhead. However, this may be used as a convenience implementation for transfers that require multiple frames, internally this is implemented as one or more tagSend calls sending headers (depending on the number of frames being transferred), followed by one tagSend for each data frame.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Exceptions
std::runtime_errorif sizes of buffer, size and isCUDA do not match.
Parameters
[in]buffera vector of raw pointers to the data frames to be sent.
[in]sizea vector of size in bytes of each frame to be sent.
[in]isCUDAa vector of booleans (integers to prevent incoherence with other vector types) indicating whether frame is CUDA, to ensure proper memory allocation by the receiver.
[in]tagthe tag to match.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
Returns
Request to be subsequently checked for the completion and its state.

◆ tagRecv()

std::shared_ptr<Request> ucxx::Endpoint::tagRecv ( void *  buffer,
size_t  length,
Tag  tag,
TagMask  tagMask,
const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue a tag receive operation.

Enqueue a tag receive operation, returning a std::shared<ucxx::Request> 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 consumed.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to pre-allocated memory where resulting data will be stored.
[in]lengththe size in bytes of the tag message to be received.
[in]tagthe tag to match.
[in]tagMaskthe tag mask to use.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
[in]callbackFunctionuser-defined callback function to call upon completion.
[in]callbackDatauser-defined data to pass to the callbackFunction.
Returns
Request to be subsequently checked for the completion and its state.

◆ tagSend()

std::shared_ptr<Request> ucxx::Endpoint::tagSend ( void *  buffer,
size_t  length,
Tag  tag,
const bool  enablePythonFuture = false,
RequestCallbackUserFunction  callbackFunction = nullptr,
RequestCallbackUserData  callbackData = nullptr 
)

Enqueue a tag send operation.

Enqueue a tag send operation, returning a std::shared<ucxx::Request> 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.

Using a Python future may be requested by specifying enablePythonFuture. If a Python future is requested, the Python application must then await on this future to ensure the transfer has completed. Requires UCXX Python support.

Parameters
[in]buffera raw pointer to the data to be sent.
[in]lengththe size in bytes of the tag message to be sent.
[in]tagthe tag to match.
[in]enablePythonFuturewhether a python future should be created and subsequently notified.
[in]callbackFunctionuser-defined callback function to call upon completion.
[in]callbackDatauser-defined data to pass to the callbackFunction.
Returns
Request to be subsequently checked for the completion and its state.

Friends And Related Function Documentation

◆ createEndpointFromConnRequest

std::shared_ptr<Endpoint> createEndpointFromConnRequest ( std::shared_ptr< Listener listener,
ucp_conn_request_h  connRequest,
bool  endpointErrorHandling 
)
friend

Constructor for shared_ptr<ucxx::Endpoint>.

The constructor for a shared_ptr<ucxx::Endpoint> object from a ucp_conn_request_h, as delivered by a ucxx::Listener connection callback.

// listener is `std::shared_ptr<ucxx::Listener>`, with a `ucp_conn_request_h` delivered
// by a `ucxx::Listener` connection callback.
auto endpoint = listener->createEndpointFromConnRequest(connRequest, true);
// Equivalent to line above
// auto endpoint = ucxx::createEndpointFromConnRequest(listener, connRequest, true);
Parameters
[in]listenerlistener from which to create the endpoint.
[in]connRequesthandle to connection request delivered by a listener callback.
[in]endpointErrorHandlingwhether to enable endpoint error handling.
Returns
The shared_ptr<ucxx::Endpoint> object

◆ createEndpointFromHostname

std::shared_ptr<Endpoint> createEndpointFromHostname ( std::shared_ptr< Worker worker,
std::string  ipAddress,
uint16_t  port,
bool  endpointErrorHandling 
)
friend

Constructor for shared_ptr<ucxx::Endpoint>.

The constructor for a shared_ptr<ucxx::Endpoint> object, connecting to a listener from the given hostname or IP address and port pair.

// worker is `std::shared_ptr<ucxx::Worker>`, with a presumed listener on
// "localhost:12345"
auto endpoint = worker->createEndpointFromHostname("localhost", 12345, true);
// Equivalent to line above
// auto endpoint = ucxx::createEndpointFromHostname(worker, "localhost", 12345, true);
Parameters
[in]workerparent worker from which to create the endpoint.
[in]ipAddresshostname or IP address the listener is bound to.
[in]portport the listener is bound to.
[in]endpointErrorHandlingwhether to enable endpoint error handling.
Returns
The shared_ptr<ucxx::Endpoint> object

◆ createEndpointFromWorkerAddress

std::shared_ptr<Endpoint> createEndpointFromWorkerAddress ( std::shared_ptr< Worker worker,
std::shared_ptr< Address address,
bool  endpointErrorHandling 
)
friend

Constructor for shared_ptr<ucxx::Endpoint>.

The constructor for a shared_ptr<ucxx::Endpoint> object from a shared_ptr<ucxx::Address>.

// worker is `std::shared_ptr<ucxx::Worker>`, address is `std::shared_ptr<ucxx::Address>`
auto endpoint = worker->createEndpointFromWorkerAddress(address, true);
// Equivalent to line above
// auto endpoint = ucxx::createEndpointFromWorkerAddress(worker, address, true);
Parameters
[in]workerparent worker from which to create the endpoint.
[in]addressaddress of the remote UCX worker
[in]endpointErrorHandlingwhether to enable endpoint error handling.
Returns
The shared_ptr<ucxx::Endpoint> object

◆ endpointErrorCallback

void endpointErrorCallback ( void *  arg,
ucp_ep_h  ep,
ucs_status_t  status 
)
friend

The error callback registered at endpoint creation time.

When the endpoint is created with error handling support this method is registered as the callback to be called when the endpoint is closing, it is responsible for checking the closing status and update internal state accordingly. If error handling support is not active, this method is not registered nor called.

The signature for this method must match ucp_err_handler_cb_t.


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