ucxx::Endpoint Class Reference

Component encapsulating a UCP endpoint. More...

#include <endpoint.h>

Inheritance diagram for ucxx::Endpoint:

Public Member Functions
	Endpoint (const Endpoint &)=delete
Endpoint &	operator= (Endpoint const &)=delete
	Endpoint (Endpoint &&o)=delete
Endpoint &	operator= (Endpoint &&o)=delete
ucp_ep_h	getHandle ()
	Get the underlying ucp_ep_h handle.
bool	isAlive () const
	Check whether the endpoint is still alive.
void	raiseOnError ()
	Raises an exception if an error occurred.
void	removeInflightRequest (std::shared_ptr< Request > request)
	Remove reference to request from internal container.
size_t	cancelInflightRequests ()
	Cancel inflight requests.
size_t	getCancelingSize () const
	Check the number of inflight requests being canceled.
size_t	cancelInflightRequestsBlocking (uint64_t period=0, uint64_t maxAttempts=1)
	Cancel inflight requests.
void	setCloseCallback (EndpointCloseCallbackUserFunction closeCallback, EndpointCloseCallbackUserData closeCallbackArg)
	Register a user-defined callback to call when endpoint closes.
RequestAmBuilder	amSendBuilder (const void *const buffer, const size_t length, const ucs_memory_type_t memoryType)
	Create a builder for an active message send operation.
RequestAmBuilder	amSendBuilder (const void *const buffer, const size_t length, const AmSendParams ¶ms)
	Create a builder for an active message send operation with explicit policy parameters.
RequestAmBuilder	amSendBuilder (std::vector< ucp_dt_iov_t > iov, const AmSendParams ¶ms)
	Create a builder for an active message send operation with IOV datatype.
RequestAmBuilder	amRecvBuilder ()
	Create a builder for an active message receive operation.
RequestMemBuilder	memPutBuilder (const void *const buffer, size_t length, uint64_t remoteAddr, ucp_rkey_h rkey)
	Create a builder for a memory put operation.
RequestMemBuilder	memPutBuilder (const void *const buffer, size_t length, std::shared_ptr< ucxx::RemoteKey > remoteKey)
	Create a builder for a memory put operation.
RequestMemBuilder	memGetBuilder (void *buffer, size_t length, uint64_t remoteAddr, ucp_rkey_h rkey)
	Create a builder for a memory get operation.
RequestMemBuilder	memGetBuilder (void *buffer, size_t length, std::shared_ptr< ucxx::RemoteKey > remoteKey)
	Create a builder for a memory get operation.
RequestStreamBuilder	streamSendBuilder (const void *const buffer, size_t length)
	Create a builder for a stream send operation.
RequestStreamBuilder	streamRecvBuilder (void *buffer, size_t length)
	Create a builder for a stream receive operation.
RequestTagBuilder	tagSendBuilder (const void *const buffer, size_t length, Tag tag)
	Create a builder for a tag send operation.
RequestTagBuilder	tagRecvBuilder (void *buffer, size_t length, Tag tag, TagMask tagMask)
	Create a builder for a tag receive operation.
RequestTagMultiBuilder	tagMultiSendBuilder (const std::vector< const void * > &buffer, const std::vector< size_t > &size, const std::vector< int > &isCUDA, const Tag tag)
	Create a builder for a multi-buffer tag send operation.
RequestTagMultiBuilder	tagMultiRecvBuilder (const Tag tag, const TagMask tagMask)
	Create a builder for a multi-buffer tag receive operation.
RequestFlushBuilder	flushBuilder ()
	Create a builder for a flush operation.
std::shared_ptr< Worker >	getWorker ()
	Get ucxx::Worker component from a worker or listener object.
RemoteKeyBuilder	remoteKeyBuilder (SerializedRemoteKey serializedRemoteKey)
	Create a builder for a remote key from serialized data.
RequestEndpointCloseBuilder	closeBuilder ()
	Create a builder for a non-blocking endpoint close operation.
void	closeBlocking (uint64_t period=0, uint64_t maxAttempts=1)
	Close the endpoint while keeping the object alive.
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.

Friends
class	RequestEndpointCloseBuilder
	Allow the endpoint close builder to preserve endpoint close state.
class	detail::ConstructorFactory
void	endpointErrorCallback (void *arg, ucp_ep_h ep, ucs_status_t status)
	The error callback registered at endpoint creation time.
void	detail::registerInflightRequest (std::shared_ptr< Component > component, std::shared_ptr< Request > req)
	Allow request builders to register newly-created requests.

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

amRecvBuilder()

RequestAmBuilder ucxx::Endpoint::amRecvBuilder ( )

nodiscard

Create a builder for an active message receive operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Returns

Builder to configure optional parameters and submit the request.

amSendBuilder() [1/3]

RequestAmBuilder ucxx::Endpoint::amSendBuilder ( const void *const buffer, const size_t length, const AmSendParams & params )

nodiscard

Create a builder for an active message send operation with explicit policy parameters.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the message to be sent.
[in]	params	active message send parameters.

Returns

Builder to configure optional parameters and submit the request.

amSendBuilder() [2/3]

RequestAmBuilder ucxx::Endpoint::amSendBuilder ( const void *const buffer, const size_t length, const ucs_memory_type_t memoryType )

nodiscard

Create a builder for an active message send operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the message to be sent.
[in]	memoryType	the memory type of the buffer.

Returns

Builder to configure optional parameters and submit the request.

amSendBuilder() [3/3]

RequestAmBuilder ucxx::Endpoint::amSendBuilder ( std::vector< ucp_dt_iov_t > iov, const AmSendParams & params )

nodiscard

Create a builder for an active message send operation with IOV datatype.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	iov	vector of IOV segments to be sent.
[in]	params	active message send parameters. Datatype must be UCP_DATATYPE_IOV.

Returns

Builder to configure optional parameters and submit the request.

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]	period	maximum period to wait for a generic pre/post progress thread operation will wait for.
[in]	maxAttempts	maximum 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.

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, first canceling inflight requests and then waiting for the close operation to complete when possible. 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, period and maxAttempts bound how long this method waits for progress-thread submission and completion checks. If close completion cannot be observed before all attempts expire, the endpoint status is set to UCS_ERR_ENDPOINT_TIMEOUT before returning. Any UCP endpoint close request handle returned by ucp_ep_close_nbx() is released before this method returns.

Parameters

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

closeBuilder()

RequestEndpointCloseBuilder ucxx::Endpoint::closeBuilder ( )

nodiscard

Create a builder for a non-blocking endpoint close operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Returns

Builder to configure optional parameters and submit the close request.

flushBuilder()

RequestFlushBuilder ucxx::Endpoint::flushBuilder ( )

nodiscard

Create a builder for a flush operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Returns

Builder to configure optional parameters and submit the request.

getCancelingSize()

size_t ucxx::Endpoint::getCancelingSize ( ) const

nodiscard

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 ( )

nodiscard

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 ( )

nodiscard

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

nodiscard

Check whether the endpoint is still alive.

Check whether the endpoint is still alive, generally true until closeBlocking() is called, a request submitted by closeBuilder() 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.

memGetBuilder() [1/2]

RequestMemBuilder ucxx::Endpoint::memGetBuilder ( void * buffer, size_t length, std::shared_ptr< ucxx::RemoteKey > remoteKey )

nodiscard

Create a builder for a memory get operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to the data to be received.
[in]	length	the size in bytes of the message to be received.
[in]	remoteKey	the remote memory key associated with the remote memory address.

Returns

Builder to configure optional parameters and submit the request.

memGetBuilder() [2/2]

RequestMemBuilder ucxx::Endpoint::memGetBuilder ( void * buffer, size_t length, uint64_t remoteAddr, ucp_rkey_h rkey )

nodiscard

Create a builder for a memory get operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to the data to be received.
[in]	length	the size in bytes of the message to be received.
[in]	remoteAddr	the source remote memory address to read from.
[in]	rkey	the remote memory key associated with the remote memory address.

Returns

Builder to configure optional parameters and submit the request.

memPutBuilder() [1/2]

RequestMemBuilder ucxx::Endpoint::memPutBuilder ( const void *const buffer, size_t length, std::shared_ptr< ucxx::RemoteKey > remoteKey )

nodiscard

Create a builder for a memory put operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the message to be sent.
[in]	remoteKey	the remote memory key associated with the remote memory address.

Returns

Builder to configure optional parameters and submit the request.

memPutBuilder() [2/2]

RequestMemBuilder ucxx::Endpoint::memPutBuilder ( const void *const buffer, size_t length, uint64_t remoteAddr, ucp_rkey_h rkey )

nodiscard

Create a builder for a memory put operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the message to be sent.
[in]	remoteAddr	the destination remote memory address to write to.
[in]	rkey	the remote memory key associated with the remote memory address.

Returns

Builder to configure optional parameters and submit the request.

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::ConnectionResetError	if UCP_ERR_CONNECTION_RESET occurred.
ucxx::Error	if any other UCP error occurred.

remoteKeyBuilder()

RemoteKeyBuilder ucxx::Endpoint::remoteKeyBuilder ( SerializedRemoteKey serializedRemoteKey )

nodiscard

Create a builder for a remote key from serialized data.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion unpacks the remote key using this endpoint.

Parameters

[in]

serializedRemoteKey

serialized remote key data.

Returns

Builder to create the remote key.

removeInflightRequest()

void ucxx::Endpoint::removeInflightRequest

(

std::shared_ptr< Request >

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.

Parameters

[in]

request

shared 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_error

if 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]	closeCallback	std::function to a function definition return void and receiving a single opaque pointer.
[in]	closeCallbackArg	pointer to optional user-allocated callback argument.

streamRecvBuilder()

RequestStreamBuilder ucxx::Endpoint::streamRecvBuilder ( void * buffer, size_t length )

nodiscard

Create a builder for a stream receive operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to pre-allocated memory where resulting data will be stored.
[in]	length	the size in bytes of the message to be received.

Returns

Builder to configure optional parameters and submit the request.

streamSendBuilder()

RequestStreamBuilder ucxx::Endpoint::streamSendBuilder ( const void *const buffer, size_t length )

nodiscard

Create a builder for a stream send operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the message to be sent.

Returns

Builder to configure optional parameters and submit the request.

tagMultiRecvBuilder()

RequestTagMultiBuilder ucxx::Endpoint::tagMultiRecvBuilder ( const Tag tag, const TagMask tagMask )

nodiscard

Create a builder for a multi-buffer tag receive operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	tag	the tag to match.
[in]	tagMask	the tag mask to use.

Returns

Builder to configure optional parameters and submit the request.

tagMultiSendBuilder()

RequestTagMultiBuilder ucxx::Endpoint::tagMultiSendBuilder ( const std::vector< const void * > & buffer, const std::vector< size_t > & size, const std::vector< int > & isCUDA, const Tag tag )

nodiscard

Create a builder for a multi-buffer tag send operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request. Completion makes the local buffers safe to reuse, but does not confirm that the peer received every frame. Applications requiring peer delivery before a force-close must use an application-level acknowledgement.

Parameters

[in]	buffer	a vector of raw pointers to the data frames to be sent.
[in]	size	a vector of size in bytes of each frame to be sent.
[in]	isCUDA	a vector indicating whether each frame is CUDA memory.
[in]	tag	the tag to match.

Returns

Builder to configure optional parameters and submit the request.

tagRecvBuilder()

RequestTagBuilder ucxx::Endpoint::tagRecvBuilder ( void * buffer, size_t length, Tag tag, TagMask tagMask )

nodiscard

Create a builder for a tag receive operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request.

Parameters

[in]	buffer	a raw pointer to pre-allocated memory where resulting data will be stored.
[in]	length	the size in bytes of the message to be received.
[in]	tag	the tag to match.
[in]	tagMask	the tag mask to use.

Returns

Builder to configure optional parameters and submit the request.

tagSendBuilder()

RequestTagBuilder ucxx::Endpoint::tagSendBuilder ( const void *const buffer, size_t length, Tag tag )

nodiscard

Create a builder for a tag send operation.

Calling this method only creates the builder. Finalizing it with .build() or implicit conversion submits the request. Completion makes the local buffer safe to reuse, but does not confirm that the peer received the message. Applications requiring peer delivery before a force-close must use an application-level acknowledgement.

Parameters

[in]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the message to be sent.
[in]	tag	the tag to match.

Returns

Builder to configure optional parameters and submit the request.

Friends And Related Symbol Documentation

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:

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