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

std::shared_ptr< Request >	amRecv (const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
	Enqueue an active message receive operation. More...

std::shared_ptr< Request >	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. More...

std::shared_ptr< Request >	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. More...

std::shared_ptr< Request >	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. More...

std::shared_ptr< Request >	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. More...

std::shared_ptr< Request >	streamSend (void *buffer, size_t length, const bool enablePythonFuture)
	Enqueue a stream send operation. More...

std::shared_ptr< Request >	streamRecv (void *buffer, size_t length, const bool enablePythonFuture)
	Enqueue a stream receive operation. More...

std::shared_ptr< Request >	tagSend (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< Request >	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. More...

std::shared_ptr< Request >	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. More...

std::shared_ptr< Request >	tagMultiRecv (const Tag tag, const TagMask tagMask, const bool enablePythonFuture)
	Enqueue a multi-buffer tag receive operation. More...

std::shared_ptr< Request >	flush (const bool enablePythonFuture=false, RequestCallbackUserFunction callbackFunction=nullptr, RequestCallbackUserData callbackData=nullptr)
	Enqueue a flush operation. More...

std::shared_ptr< Worker >	getWorker ()
	Get `ucxx::Worker` component from a worker or listener object. More...

std::shared_ptr< Request >	close (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< Component >	getParent () 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< Endpoint >	createEndpointFromHostname (std::shared_ptr< Worker > worker, std::string ipAddress, uint16_t port, bool endpointErrorHandling)
	Constructor for `shared_ptr<ucxx::Endpoint>`. More...

std::shared_ptr< Endpoint >	createEndpointFromConnRequest (std::shared_ptr< Listener > listener, ucp_conn_request_h connRequest, bool endpointErrorHandling)
	Constructor for `shared_ptr<ucxx::Endpoint>`. More...

std::shared_ptr< Endpoint >	createEndpointFromWorkerAddress (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]	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`.

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]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the tag message to be sent.
[in]	memoryType	the memory type of the buffer.
[in]	receiverCallbackInfo	the owner name and unique identifier of the receiver callback.
[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`.

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

◆ 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]	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`.

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

◆ 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]	buffer	a raw pointer to the data to be sent.
[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`.

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]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the tag message to be sent.
[in]	remoteKey	the remote memory key associated with the remote memory address.
[in]	remoteAddrOffset	the destination remote memory address offset where to start reading from, `0` means start writing from beginning of the base address.
[in]	enablePythonFuture	whether 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]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the tag message to be sent.
[in]	remoteAddr	the source remote memory address to read from.
[in]	rkey	the remote memory key associated with the remote memory address.
[in]	enablePythonFuture	whether 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]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the tag message to be sent.
[in]	remoteKey	the remote memory key associated with the remote memory address.
[in]	remoteAddrOffset	the destination remote memory address offset where to start writing to, `0` means start writing from beginning of the base address.
[in]	enablePythonFuture	whether 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]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the tag 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.
[in]	enablePythonFuture	whether 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::ConnectionResetError	if `UCP_ERR_CONNECTION_RESET` occurred.
ucxx::Error	if 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] request raw 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.

◆ 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]	buffer	a raw pointer to pre-allocated memory where resulting data will be stored.
[in]	length	the size in bytes of the tag message to be received.
[in]	enablePythonFuture	whether 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]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the tag message to be sent.
[in]	enablePythonFuture	whether 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]	tag	the tag to match.
[in]	tagMask	the tag mask to use.
[in]	enablePythonFuture	whether 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_error if sizes of buffer, size and isCUDA do not match.

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 of booleans (integers to prevent incoherence with other vector types) indicating whether frame is CUDA, to ensure proper memory allocation by the receiver.
[in]	tag	the tag to match.
[in]	enablePythonFuture	whether 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]	buffer	a raw pointer to pre-allocated memory where resulting data will be stored.
[in]	length	the size in bytes of the tag message to be received.
[in]	tag	the tag to match.
[in]	tagMask	the tag mask to use.
[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`.

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]	buffer	a raw pointer to the data to be sent.
[in]	length	the size in bytes of the tag message to be sent.
[in]	tag	the tag to match.
[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`.

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]	listener	listener from which to create the endpoint.
[in]	connRequest	handle to connection request delivered by a listener callback.
[in]	endpointErrorHandling	whether 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]	worker	parent worker from which to create the endpoint.
[in]	ipAddress	hostname or IP address the listener is bound to.
[in]	port	port the listener is bound to.
[in]	endpointErrorHandling	whether 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]	worker	parent worker from which to create the endpoint.
[in]	address	address of the remote UCX worker
[in]	endpointErrorHandling	whether 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:

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

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ amRecv()

◆ amSend()

◆ cancelInflightRequests()

◆ cancelInflightRequestsBlocking()

◆ close()

◆ closeBlocking()

◆ flush()

◆ getCancelingSize()

◆ getHandle()

◆ getWorker()

◆ isAlive()

◆ memGet() [1/2]

◆ memGet() [2/2]

◆ memPut() [1/2]

◆ memPut() [2/2]

◆ raiseOnError()

◆ removeInflightRequest()

◆ setCloseCallback()

◆ streamRecv()

◆ streamSend()

◆ tagMultiRecv()

◆ tagMultiSend()

◆ tagRecv()

◆ tagSend()

Friends And Related Function Documentation

◆ createEndpointFromConnRequest

◆ createEndpointFromHostname

◆ createEndpointFromWorkerAddress

◆ endpointErrorCallback