Classes
class	Address
	Component encapsulating the address of a UCP worker. More...

class	Buffer
	A simple object to simplify managing buffers. More...

class	HostBuffer
	A simple object containing a host buffer. More...

class	Component
	A UCXX component class to prevent early destruction of parent object. More...

class	Config
	Component encapsulating the UCP configuration. More...

class	Context
	Component encapsulating the UCP context. More...

class	BaseDelayedSubmissionCollection
	Base type for a collection of delayed submissions. More...

class	RequestDelayedSubmissionCollection
	A collection of delayed request submissions. More...

class	GenericDelayedSubmissionCollection
	A collection of delayed submissions of generic callbacks. More...

class	DelayedSubmissionCollection
	A collection of delayed submissions of multiple types. More...

struct	EpParamsDeleter
	Deleter for a endpoint parameters object. More...

class	Endpoint
	Component encapsulating a UCP endpoint. More...

class	Error
	The base class for all UCX exceptions. More...

class	NoMessageError
	The exception for `UCS_ERR_NO_MESSAGE`. More...

class	NoResourceError
	The exception for `UCS_ERR_NO_RESOURCE`. More...

class	IOError
	The exception for `UCS_ERR_IO_ERROR`. More...

class	NoMemoryError
	The exception for `UCS_ERR_NO_MEMORY`. More...

class	InvalidParamError
	The exception for `UCS_ERR_INVALID_PARAM`. More...

class	UnreachableError
	The exception for `UCS_ERR_UNREACHABLE`. More...

class	InvalidAddrError
	The exception for `UCS_ERR_INVALID_ADDR`. More...

class	NotImplementedError
	The exception for `UCS_ERR_NOT_IMPLEMENTED`. More...

class	MessageTruncatedError
	The exception for `UCS_ERR_MESSAGE_TRUNCATED`. More...

class	NoProgressError
	The exception for `UCS_ERR_NO_PROGRESS`. More...

class	BufferTooSmallError
	The exception for `UCS_ERR_BUFFER_TOO_SMALL`. More...

class	NoElemError
	The exception for `UCS_ERR_NO_ELEM`. More...

class	SomeConnectsFailedError
	The exception for `UCS_ERR_SOME_CONNECTS_FAILED`. More...

class	NoDeviceError
	The exception for `UCS_ERR_NO_DEVICE`. More...

class	BusyError
	The exception for `UCS_ERR_BUSY`. More...

class	CanceledError
	The exception for `UCS_ERR_CANCELED`. More...

class	ShmemSegmentError
	The exception for `UCS_ERR_SHMEM_SEGMENT`. More...

class	AlreadyExistsError
	The exception for `UCS_ERR_ALREADY_EXISTS`. More...

class	OutOfRangeError
	The exception for `UCS_ERR_OUT_OF_RANGE`. More...

class	TimedOutError
	The exception for `UCS_ERR_TIMED_OUT`. More...

class	ExceedsLimitError
	The exception for `UCS_ERR_EXCEEDS_LIMIT`. More...

class	UnsupportedError
	The exception for `UCS_ERR_UNSUPPORTED`. More...

class	RejectedError
	The exception for `UCS_ERR_REJECTED`. More...

class	NotConnectedError
	The exception for `UCS_ERR_NOT_CONNECTED`. More...

class	ConnectionResetError
	The exception for `UCS_ERR_CONNECTION_RESET`. More...

class	FirstLinkFailureError
	The exception for `UCS_ERR_FIRST_LINK_FAILURE`. More...

class	LastLinkFailureError
	The exception for `UCS_ERR_LAST_LINK_FAILURE`. More...

class	FirstEndpointFailureError
	The exception for `UCS_ERR_FIRST_ENDPOINT_FAILURE`. More...

class	EndpointTimeoutError
	The exception for `UCS_ERR_ENDPOINT_TIMEOUT`. More...

class	LastEndpointFailureError
	The exception for `UCS_ERR_LAST_ENDPOINT_FAILURE`. More...

class	Future
	Represent a future that may be notified by a specialized notifier. More...

class	Header
	A serializable object containing metadata of multiple buffers. More...

struct	TrackedRequests
	A container for the different types of tracked requests. More...

class	InflightRequests
	Handle tracked requests. More...

class	Listener
	Component encapsulating a UCP listener. More...

class	MemoryHandle
	Component holding a UCP memory handle. More...

class	Notifier
	Notifier for status of futures. More...

class	RemoteKey
	Component holding a UCP rkey (remote key). More...

class	Request
	Base type for a UCXX transfer request. More...

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

class	RequestEndpointClose
	Send or receive a message with the UCX Tag API. More...

class	RequestFlush
	Flush a UCP endpoint or worker. More...

class	RequestMem

class	RequestStream
	Send or receive a message with the UCX Stream API. More...

class	RequestTag
	Send or receive a message with the UCX Tag API. More...

struct	BufferRequest
	Container for data required by a `ucxx::RequestTagMulti`. More...

class	RequestTagMulti
	Send or receive multiple messages with the UCX Tag API. More...

class	TagRecvInfo
	Information about probed tag message. More...

class	AmReceiverCallbackInfo
	Information of an Active Message receiver callback. More...

class	Worker
	Component encapsulating a UCP worker. More...

class	WorkerProgressThread
	A thread to progress a `ucxx::Worker`. More...

Typedefs
typedef std::function< void()>	DelayedSubmissionCallbackType
	A user-defined function to execute as part of delayed submission callback. More...

typedef uint64_t	ItemIdType

typedef std::map< const Request *const, std::shared_ptr< Request > >	InflightRequestsMap
	An inflight request map. More...

typedef struct ucxx::TrackedRequests	TrackedRequests
	A container for the different types of tracked requests. More...

typedef std::unique_ptr< TrackedRequests >	TrackedRequestsPtr
	Pre-defined type for a pointer to a container of tracked requests. More...

typedef size_t	SerializedRemoteKeyHash

typedef std::shared_ptr< BufferRequest >	BufferRequestPtr
	Pre-defined type for a pointer to an `ucxx::BufferRequest`. More...

typedef std::shared_ptr< RequestTagMulti >	RequestTagMultiPtr
	Pre-defined type for a pointer to an `ucxx::RequestTagMulti`. More...

typedef std::unordered_map< std::string, std::string >	ConfigMap
	A UCP configuration map. More...

typedef std::function< void(ucs_status_t, std::shared_ptr< void >)>	RequestCallbackUserFunction
	A user-defined function to execute as part of a `ucxx::Request` callback. More...

typedef std::shared_ptr< void >	RequestCallbackUserData
	Data for the user-defined function provided to the `ucxx::Request` callback. More...

typedef RequestCallbackUserFunction	EndpointCloseCallbackUserFunction
	A user-defined function to execute after an endpoint closes. More...

typedef RequestCallbackUserData	EndpointCloseCallbackUserData
	Data for the user-defined function provided to endpoint close callback. More...

typedef std::function< std::shared_ptr< Buffer >size_t)>	AmAllocatorType
	Custom Active Message allocator type. More...

typedef std::function< void(std::shared_ptr< Request >, ucp_ep_h)>	AmReceiverCallbackType
	Active Message receiver callback. More...

typedef std::string	AmReceiverCallbackOwnerType
	Active Message receiver callback owner name. More...

typedef uint64_t	AmReceiverCallbackIdType
	Active Message receiver callback identifier. More...

typedef const std::string	AmReceiverCallbackInfoSerialized

typedef const std::string	SerializedRemoteKey

typedef std::function< void(void)>	SignalWorkerFunction
	A user-defined function used to wake the worker. More...

typedef std::function< void(void *)>	ProgressThreadStartCallback
	A user-defined function to execute at the start of the progress thread. More...

typedef void *	ProgressThreadStartCallbackArg
	Data for the user-defined function provided to progress thread start callback. More...

Enumerations
enum class	BufferType { Host = 0 , RMM , Invalid }
	The type of a buffer. More...

enum class	RequestNotifierThreadState { NotRunning = 0 , Running , Stopping }
	The state of the notifier thread. More...

enum class	RequestNotifierWaitState { Ready = 0 , Timeout , Shutdown }
	The state with which a wait operation completed. More...

enum	ucxx_log_level_t { UCXX_LOG_LEVEL_FATAL , UCXX_LOG_LEVEL_ERROR , UCXX_LOG_LEVEL_WARN , UCXX_LOG_LEVEL_DIAG , UCXX_LOG_LEVEL_INFO , UCXX_LOG_LEVEL_DEBUG , UCXX_LOG_LEVEL_TRACE , UCXX_LOG_LEVEL_TRACE_REQ , UCXX_LOG_LEVEL_TRACE_DATA , UCXX_LOG_LEVEL_TRACE_ASYNC , UCXX_LOG_LEVEL_TRACE_FUNC , UCXX_LOG_LEVEL_TRACE_POLL , UCXX_LOG_LEVEL_LAST , UCXX_LOG_LEVEL_PRINT }
	Available logging levels. More...

enum class	TransferDirection { Send = 0 , Receive }
	The direction of a UCXX transfer. More...

enum	Tag : ucp_tag_t
	Strong type for a UCP tag. More...

enum	TagMask : ucp_tag_t
	Strong type for a UCP tag mask. More...

Functions
std::shared_ptr< Buffer >	allocateBuffer (BufferType bufferType, const size_t size)
	Allocate a buffer of specified type and size. More...

std::shared_ptr< Address >	createAddressFromWorker (std::shared_ptr< Worker > worker)

std::shared_ptr< Address >	createAddressFromString (std::string addressString)

std::shared_ptr< Context >	createContext (const ConfigMap ucxConfig, const uint64_t featureFlags)

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

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

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

std::shared_ptr< Listener >	createListener (std::shared_ptr< Worker > worker, uint16_t port, ucp_listener_conn_callback_t callback, void *callbackArgs)

std::shared_ptr< Worker >	createWorker (std::shared_ptr< Context > context, const bool enableDelayedSubmission, const bool enableFuture)

std::shared_ptr< MemoryHandle >	createMemoryHandle (std::shared_ptr< Context > context, const size_t size, void *buffer=nullptr, const ucs_memory_type_t memoryType=UCS_MEMORY_TYPE_HOST)

std::shared_ptr< RemoteKey >	createRemoteKeyFromMemoryHandle (std::shared_ptr< MemoryHandle > memoryHandle)

std::shared_ptr< RemoteKey >	createRemoteKeyFromSerialized (std::shared_ptr< Endpoint > endpoint, SerializedRemoteKey serializedRemoteKey)

std::shared_ptr< RequestAm >	createRequestAm (std::shared_ptr< Endpoint > endpoint, const std::variant< data::AmSend, data::AmReceive > requestData, const bool enablePythonFuture, RequestCallbackUserFunction callbackFunction, RequestCallbackUserData callbackData)

std::shared_ptr< RequestEndpointClose >	createRequestEndpointClose (std::shared_ptr< Endpoint > endpoint, const data::EndpointClose requestData, const bool enablePythonFuture, RequestCallbackUserFunction callbackFunction, RequestCallbackUserData callbackData)

std::shared_ptr< RequestFlush >	createRequestFlush (std::shared_ptr< Component > endpointOrWorker, const data::Flush requestData, const bool enablePythonFuture, RequestCallbackUserFunction callbackFunction, RequestCallbackUserData callbackData)

std::shared_ptr< RequestStream >	createRequestStream (std::shared_ptr< Endpoint > endpoint, const std::variant< data::StreamSend, data::StreamReceive > requestData, const bool enablePythonFuture)

std::shared_ptr< RequestTag >	createRequestTag (std::shared_ptr< Component > endpointOrWorker, const std::variant< data::TagSend, data::TagReceive > requestData, const bool enablePythonFuture, RequestCallbackUserFunction callbackFunction, RequestCallbackUserData callbackData)

std::shared_ptr< RequestMem >	createRequestMem (std::shared_ptr< Endpoint > endpoint, const std::variant< data::MemPut, data::MemGet > requestData, const bool enablePythonFuture, RequestCallbackUserFunction callbackFunction, RequestCallbackUserData callbackData)

std::shared_ptr< RequestTagMulti >	createRequestTagMulti (std::shared_ptr< Endpoint > endpoint, const std::variant< data::TagMultiSend, data::TagMultiReceive > requestData, const bool enablePythonFuture)

void	parseLogLevel ()
	Parse the active log level. More...

void	waitSingleRequest (std::shared_ptr< Worker > worker, std::shared_ptr< Request > request)
	Wait for a single request to complete. More...

void	waitRequests (std::shared_ptr< Worker > worker, std::vector< std::shared_ptr< Request >> requests)
	Wait for a multiple requests to complete. More...

Variables
const size_t	HeaderFramesSize
	The number of buffers contained in a single `ucxx::Header` object. More...

ucs_log_component_config_t	ucxx_log_component_config
	The UCXX log level component configuration. More...

const std::unordered_map< std::string, ucxx_log_level_t >	logLevelNames
	Map of log level names to their respective types. More...

const char	logLevelNameDefault [] = "WARN"
	The name of the default log level. More...

const ucs_log_level_t	logLevelDefault = (ucs_log_level_t)logLevelNames.at(logLevelNameDefault)
	The type of the default log level. More...

Detailed Description

Typedef Documentation

◆ AmAllocatorType

typedef std::function<std::shared_ptr<Buffer>size_t)> ucxx::AmAllocatorType

Custom Active Message allocator type.

Type for a custom Active Message allocator that can be registered by a user so that the Active Message receiver can allocate a buffer of such type upon receiving message.

◆ AmReceiverCallbackIdType

typedef uint64_t ucxx::AmReceiverCallbackIdType

Active Message receiver callback identifier.

A 64-bit unsigned integer unique identifier type of an Active Message receiver callback.

◆ AmReceiverCallbackOwnerType

typedef std::string ucxx::AmReceiverCallbackOwnerType

Active Message receiver callback owner name.

A string containing the owner's name of an Active Message receiver callback. The owner should be a reasonably unique name, usually identifying the application, to allow other applications to coexist and register their own receiver callbacks.

◆ AmReceiverCallbackType

typedef std::function<void(std::shared_ptr<Request>, ucp_ep_h)> ucxx::AmReceiverCallbackType

Active Message receiver callback.

Type for a custom Active Message receiver callback, executed by the remote worker upon Active Message request completion. The first parameter is the request that completed, the second is the handle of the UCX endpoint of the sender.

◆ BufferRequestPtr

typedef std::shared_ptr<BufferRequest> ucxx::BufferRequestPtr

Pre-defined type for a pointer to an ucxx::BufferRequest.

A pre-defined type for a pointer to a ucxx::BufferRequest, used as a convenience type.

◆ ConfigMap

typedef std::unordered_map<std::string, std::string> ucxx::ConfigMap

A UCP configuration map.

A UCP configuration map, with keys being the configuration name and value being the actual value set.

◆ DelayedSubmissionCallbackType

typedef std::function<void()> ucxx::DelayedSubmissionCallbackType

A user-defined function to execute as part of delayed submission callback.

A user-defined function to execute in the scope of a ucxx::DelayedSubmission, allowing execution of custom code upon the completion of the delayed submission.

◆ EndpointCloseCallbackUserData

typedef RequestCallbackUserData ucxx::EndpointCloseCallbackUserData

Data for the user-defined function provided to endpoint close callback.

Data passed to the user-defined function provided to the endpoint close callback, which the custom user-defined function may act upon.

◆ EndpointCloseCallbackUserFunction

typedef RequestCallbackUserFunction ucxx::EndpointCloseCallbackUserFunction

A user-defined function to execute after an endpoint closes.

A user-defined function to execute after an endpoint closes, allowing execution of custom code after such event.

◆ InflightRequestsMap

typedef std::map<const Request* const, std::shared_ptr<Request> > ucxx::InflightRequestsMap

An inflight request map.

A map of inflight requests, where keys are a unique identifier of the request and value is the reference-counted ucxx::Request.

◆ ProgressThreadStartCallback

typedef std::function<void(void*)> ucxx::ProgressThreadStartCallback

A user-defined function to execute at the start of the progress thread.

A user-defined function to execute at the start of the progress thread, used for example to ensure resources are properly set for the thread, such as a CUDA context.

◆ ProgressThreadStartCallbackArg

typedef void* ucxx::ProgressThreadStartCallbackArg

Data for the user-defined function provided to progress thread start callback.

Data passed to the user-defined function provided to the callback executed when the progress thread starts, which the custom user-defined function may act upon.

◆ RequestCallbackUserData

typedef std::shared_ptr<void> ucxx::RequestCallbackUserData

Data for the user-defined function provided to the ucxx::Request callback.

Data passed to the user-defined function provided to the ucxx::Request callback, which the custom user-defined function may act upon.

◆ RequestCallbackUserFunction

typedef std::function<void(ucs_status_t, std::shared_ptr<void>)> ucxx::RequestCallbackUserFunction

A user-defined function to execute as part of a ucxx::Request callback.

A user-defined function to execute as part of a ucxx::Request callback, allowing execution of custom code upon request completion.

◆ RequestTagMultiPtr

typedef std::shared_ptr<RequestTagMulti> ucxx::RequestTagMultiPtr

Pre-defined type for a pointer to an ucxx::RequestTagMulti.

A pre-defined type for a pointer to a ucxx::RequestTagMulti, used as a convenience type.

◆ SignalWorkerFunction

typedef std::function<void(void)> ucxx::SignalWorkerFunction

A user-defined function used to wake the worker.

A user-defined function signaling worker to wake the progress event.

◆ TrackedRequests

typedef struct ucxx::TrackedRequests ucxx::TrackedRequests

A container for the different types of tracked requests.

A container encapsulating the different types of handled tracked requests, currently those still valid (inflight), and those scheduled for cancelation (canceling).

◆ TrackedRequestsPtr

typedef std::unique_ptr<TrackedRequests> ucxx::TrackedRequestsPtr

Pre-defined type for a pointer to a container of tracked requests.

A pre-defined type for a pointer to a container of tracked requests, used as a convenience type.

Enumeration Type Documentation

◆ BufferType

enum ucxx::BufferType

strong

The type of a buffer.

The type of a buffer that can be used to match among the different supported types.

◆ RequestNotifierThreadState

enum ucxx::RequestNotifierThreadState

strong

The state of the notifier thread.

The current state of the notifier thread.

◆ RequestNotifierWaitState

enum ucxx::RequestNotifierWaitState

strong

The state with which a wait operation completed.

The state with which a blocking call to wait for the request notifier completed.

◆ Tag

enum ucxx::Tag : ucp_tag_t

Strong type for a UCP tag.

Strong type for a UCP tag, preventing accidental mixing with wrong types, especially useful to prevent passing an argument in wrong order.

◆ TagMask

enum ucxx::TagMask : ucp_tag_t

Strong type for a UCP tag mask.

Strong type for a UCP tag mask, preventing accidental mixing with wrong types, especially useful to prevent passing an argument in wrong order.

◆ TransferDirection

enum ucxx::TransferDirection

strong

The direction of a UCXX transfer.

The direction of a UCXX transfer, can be either Send or Receive.

◆ ucxx_log_level_t

enum ucxx::ucxx_log_level_t

Available logging levels.

Available logging levels that are used to enable specific log types based on user's configuration and also to define appropriate functions to be used in UCXX code to log only when the appropriate level is enabled.

Function Documentation

◆ allocateBuffer()

std::shared_ptr<Buffer> ucxx::allocateBuffer	(	BufferType	bufferType,
		const size_t	size
	)

Allocate a buffer of specified type and size.

Allocate a buffer of the specified type and size pair, returning the ucxx::Buffer object wrapped in a std::shared_ptr.

Parameters

[in]	bufferType	the type of buffer to allocate.
[in]	size	the size (in bytes) of the buffer to allocate.

Returns: the std::shared_ptr to the allocated buffer.

◆ createAddressFromString()

std::shared_ptr<Address> ucxx::createAddressFromString ( std::string addressString )

The constructor for a shared_ptr<ucxx::Address> object from the address extracted as string from a remote std::shared_ptr<ucxx::Worker>.

Parameters

[in] addressString the string from which to create the address.

Returns: The shared_ptr<ucxx::Address> object.

◆ createAddressFromWorker()

std::shared_ptr<Address> ucxx::createAddressFromWorker ( std::shared_ptr< Worker > worker )

The constructor for a shared_ptr<ucxx::Address> object from a std::shared_ptr<ucxx::Worker> to obtain its address.

Parameters

[in] worker parent worker from which to get the address.

Returns: The shared_ptr<ucxx::Address> object.

◆ createContext()

std::shared_ptr<Context> ucxx::createContext	(	const ConfigMap	ucxConfig,
		const uint64_t	featureFlags
	)

The constructor for a shared_ptr<ucxx::Context> object. The default constructor is made private to ensure all UCXX objects are shared pointers for correct lifetime management.

auto context = ucxx::createContext({}, UCP_FEATURE_WAKEUP | UCP_FEATURE_TAG);

ucxx::createContext

std::shared_ptr< Context > createContext(const ConfigMap ucxConfig, const uint64_t featureFlags)

Parameters

[in]	ucxConfig	configurations overriding `UCX_*` defaults and environment variables.
[in]	featureFlags	feature flags to be used at UCP context construction time.

Returns: The shared_ptr<ucxx::Context> object

◆ createEndpointFromConnRequest()

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

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> ucxx::createEndpointFromHostname	(	std::shared_ptr< Worker >	worker,
		std::string	ipAddress,
		uint16_t	port,
		bool	endpointErrorHandling
	)

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> ucxx::createEndpointFromWorkerAddress	(	std::shared_ptr< Worker >	worker,
		std::shared_ptr< Address >	address,
		bool	endpointErrorHandling
	)

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

◆ createListener()

std::shared_ptr<Listener> ucxx::createListener	(	std::shared_ptr< Worker >	worker,
		uint16_t	port,
		ucp_listener_conn_callback_t	callback,
		void *	callbackArgs
	)

The constructor for a shared_ptr<ucxx::Listener> object. The default constructor is made private to ensure all UCXX objects are shared pointers for correct lifetime management.

typedef struct ClientContext {
  std::shared_ptr<ucxx::Endpoint> endpoint{nullptr};
  std::shared_ptr<ucxx::Listener> listener{nullptr};
} ClientContextType;
 
void myCallback(ucp_conn_request_h connRequest, void* arg) {
  ClientContextType clientContext = (ClientContextType*);
  clientContext->endpoint =
    clientContext->listener->createEndpointFromConnRequest(connRequest);
}
 
ClientContext clientContext;
 
// worker is `std::shared_ptr<ucxx::Worker>`
auto listener = worker->createListener(12345, myCallback, clientContext);
clientContext->listener = listener;
 
// Equivalent to line above
// auto listener = ucxx::createListener(worker, 12345, myCallback, clientContext);

Parameters

[in]	worker	the worker from which to create the listener.
[in]	port	the port which the listener should be bound to.
[in]	callback	user-defined callback to be executed on incoming client connections.
[in]	callbackArgs	argument to be passed to the callback.

Returns: The shared_ptr<ucxx::Listener> object.

◆ createMemoryHandle()

std::shared_ptr<MemoryHandle> ucxx::createMemoryHandle	(	std::shared_ptr< Context >	context,
		const size_t	size,
		void *	buffer = `nullptr`,
		const ucs_memory_type_t	memoryType = `UCS_MEMORY_TYPE_HOST`
	)

The constructor for a shared_ptr<ucxx::MemoryHandle> object, mapping a memory buffer with UCP to provide RMA (Remote Memory Access) to.

The allocation requires a size and a buffer. The buffer provided may be either a nullptr, in which case UCP will allocate a new memory region for it, or an already existing allocation, in which case UCP will only map it for RMA and it's the caller's responsibility to keep buffer alive until this object is destroyed. When the UCP allocates buffer (i.e., when the value passed is nullptr), the actual size of the allocation may be larger than requested, and can later be found calling the getSize() method, if a preallocated buffer is passed getSize() will return the same value specified for size.

// `context` is `std::shared_ptr<ucxx::Context>`
// Allocate a 128-byte buffer with UCP.
auto memoryHandle = context->createMemoryHandle(128, nullptr);
 
// Equivalent to line above
// auto memoryHandle = ucxx::createMemoryHandle(context, 128, nullptr);
 
// Map an existing 128-byte buffer with UCP.
size_t allocationSize = 128;
auto buffer = new uint8_t[allocationSize];
auto memoryHandleFromBuffer = context->createMemoryHandle(
   allocationSize * sizeof(*buffer), reinterpret_cast<void*>(buffer)
);
 
// Equivalent to line above
// auto memoryHandleFromBuffer = ucxx::createMemoryHandle(
//    context, allocationSize * sizeof(*buffer), reinterpret_cast<void*>(buffer)
// );

Exceptions

ucxx::Error if either ucp_mem_map or ucp_mem_query fail.

Parameters

[in]	context	parent context where to map memory.
[in]	size	the minimum size of the memory allocation
[in]	buffer	the pointer to an existing allocation or `nullptr` to allocate a new memory region.
[in]	memoryType	the type of memory the handle points to.

Returns: The shared_ptr<ucxx::MemoryHandle> object

◆ createRemoteKeyFromMemoryHandle()

std::shared_ptr<RemoteKey> ucxx::createRemoteKeyFromMemoryHandle ( std::shared_ptr< MemoryHandle > memoryHandle )

The constructor for a std::shared_ptr<ucxx::RemoteKey> object from a local std::shared_ptr<ucxx::MemoryHandle>, mapping a local memory buffer to be made accessible from a remote endpoint to perform RMA (Remote Memory Access) on the memory.

// `memoryHandle` is `std::shared_ptr<ucxx::MemoryHandle>`
auto remoteKey = memoryHandle->createRemoteKey();
 
// Equivalent to line above
// auto remoteKey = ucxx::createRemoteKeyFromMemoryHandle(memoryHandle);

Exceptions

ucxx::Error if ucp_rkey_pack fails.

Parameters

[in] memoryHandle the memory handle mapped on the local process.

Returns: The shared_ptr<ucxx::RemoteKey> object

◆ createRemoteKeyFromSerialized()

std::shared_ptr<RemoteKey> ucxx::createRemoteKeyFromSerialized	(	std::shared_ptr< Endpoint >	endpoint,
		SerializedRemoteKey	serializedRemoteKey
	)

The constructor for a std::shared_ptr<ucxx::RemoteKey> object from a serialized std::shared_ptr<ucxx::RemoteKey>, mapping a remote memory buffer to be made accessible via a local endpoint to perform RMA (Remote Memory Access) on the memory.

// `serializedRemoteKey` is `ucxx::SerializedRemoteKey>`, created on a remote worker
// after a call to `ucxx::RemoteKey::serialize()` and transferred over-the-wire.
auto remoteKey = ucxx::createRemoteKeyFromSerialized(serializedRemoteKey);
 
// Equivalent to line above
// auto remoteKey = ucxx::createRemoteKeyFromMemoryHandle(memoryHandle);

Exceptions

ucxx::Error if ucp_ep_rkey_unpack fails.

Parameters

[in]	endpoint	the `std::shared_ptr<Endpoint>` parent component.
[in]	serializedRemoteKey	the remote key that was serialized by the owner of the memory handle and transferred over-the-wire for reconstruction and remote access.

Returns: The shared_ptr<ucxx::RemoteKey> object

◆ createRequestAm()

std::shared_ptr<RequestAm> ucxx::createRequestAm	(	std::shared_ptr< Endpoint >	endpoint,
		const std::variant< data::AmSend, data::AmReceive >	requestData,
		const bool	enablePythonFuture,
		RequestCallbackUserFunction	callbackFunction,
		RequestCallbackUserData	callbackData
	)

The constructor for a std::shared_ptr<ucxx::RequestAm> object, creating an active message request, returning a pointer to a request object that can be later awaited and checked for errors. This is a non-blocking operation, and the status of the transfer must be verified from the resulting request object before the data can be released if this is a send operation, or consumed if this is a receive operation. Received data is available via the getRecvBuffer() method if the receive transfer request completed successfully.

Exceptions

ucxx::Error if endpoint is not a valid std::shared_ptr<ucxx::Endpoint>.

Parameters

[in]	endpoint	the parent endpoint.
[in]	requestData	container of the specified message type, including all type-specific data.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.
[in]	callbackFunction	user-defined callback function to call upon completion.
[in]	callbackData	user-defined data to pass to the `callbackFunction`.

Returns: The shared_ptr<ucxx::RequestAm> object

◆ createRequestEndpointClose()

std::shared_ptr<RequestEndpointClose> ucxx::createRequestEndpointClose	(	std::shared_ptr< Endpoint >	endpoint,
		const data::EndpointClose	requestData,
		const bool	enablePythonFuture,
		RequestCallbackUserFunction	callbackFunction,
		RequestCallbackUserData	callbackData
	)

The constructor for a std::shared_ptr<ucxx::RequestEndpointClose> object, creating a request to close a UCP endpoint, returning a pointer to the 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 close operation has completed successfully.

Exceptions

ucxx::Error endpoint is not a valid std::shared_ptr<ucxx::Endpoint>.

Parameters

[in]	endpoint	the `std::shared_ptr<Endpoint>` parent component.
[in]	requestData	container of the specified message type, including all type-specific data.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.
[in]	callbackFunction	user-defined callback function to call upon completion.
[in]	callbackData	user-defined data to pass to the `callbackFunction`.

Returns: The shared_ptr<ucxx::RequestEndpointClose> object.

◆ createRequestFlush()

std::shared_ptr<RequestFlush> ucxx::createRequestFlush	(	std::shared_ptr< Component >	endpointOrWorker,
		const data::Flush	requestData,
		const bool	enablePythonFuture,
		RequestCallbackUserFunction	callbackFunction,
		RequestCallbackUserData	callbackData
	)

The constructor for a std::shared_ptr<ucxx::RequestFlush> object, creating a request to flush outstanding AMO (Atomic Memory Operation) and RMA (Remote Memory Access) operations on a UCP endpoint or worker, 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.

Exceptions

ucxx::Error endpointOrWorker is not a valid std::shared_ptr<ucxx::Endpoint> or std::shared_ptr<ucxx::Worker>.

Parameters

[in]	endpointOrWorker	the parent component, which may either be a `std::shared_ptr<Endpoint>` or `std::shared_ptr<Worker>`.
[in]	requestData	container of the specified message type, including all type-specific data.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.
[in]	callbackFunction	user-defined callback function to call upon completion.
[in]	callbackData	user-defined data to pass to the `callbackFunction`.

Returns: The shared_ptr<ucxx::RequestFlush> object

◆ createRequestMem()

std::shared_ptr<RequestMem> ucxx::createRequestMem	(	std::shared_ptr< Endpoint >	endpoint,
		const std::variant< data::MemPut, data::MemGet >	requestData,
		const bool	enablePythonFuture,
		RequestCallbackUserFunction	callbackFunction,
		RequestCallbackUserData	callbackData
	)

The constructor for a std::shared_ptr<ucxx::RequestMem> object, creating a get or put request, returning a pointer to a request object that can be later awaited and checked for errors. This is a non-blocking operation, and the status of the transfer must be verified from the resulting request object before both the local and remote data can be released and the local data (on get operations) or remote data (on put operations) can be consumed.

Exceptions

ucxx::Error if endpointOrWorker is not a valid std::shared_ptr<ucxx::Endpoint> or std::shared_ptr<ucxx::Worker>.

Parameters

[in]	endpointOrWorker	the parent component, which may either be a `std::shared_ptr<Endpoint>` or `std::shared_ptr<Worker>`.
[in]	requestData	container of the specified message type, including all type-specific data.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.
[in]	callbackFunction	user-defined callback function to call upon completion.
[in]	callbackData	user-defined data to pass to the `callbackFunction`.

Returns: The shared_ptr<ucxx::RequestTag> object

◆ createRequestStream()

std::shared_ptr<RequestStream> ucxx::createRequestStream	(	std::shared_ptr< Endpoint >	endpoint,
		const std::variant< data::StreamSend, data::StreamReceive >	requestData,
		const bool	enablePythonFuture
	)

The constructor for a std::shared_ptr<ucxx::RequestStream> object, creating a send or receive stream request, returning a pointer to a request object that can be later awaited and checked for errors. This is a non-blocking operation, and the status of the transfer must be verified from the resulting request object before the data can be released (for a send operation) or consumed (for a receive operation).

Parameters

[in]	endpoint	the `std::shared_ptr<Endpoint>` parent component
[in]	requestData	container of the specified message type, including all type-specific data.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.

Returns: The shared_ptr<ucxx::RequestStream> object

◆ createRequestTag()

std::shared_ptr<RequestTag> ucxx::createRequestTag	(	std::shared_ptr< Component >	endpointOrWorker,
		const std::variant< data::TagSend, data::TagReceive >	requestData,
		const bool	enablePythonFuture,
		RequestCallbackUserFunction	callbackFunction,
		RequestCallbackUserData	callbackData
	)

The constructor for a std::shared_ptr<ucxx::RequestTag> object, creating a send or receive tag request, returning a pointer to a request object that can be later awaited and checked for errors. This is a non-blocking operation, and the status of the transfer must be verified from the resulting request object before the data can be released (for a send operation) or consumed (for a receive operation).

Exceptions

ucxx::Error if send is true and endpointOrWorker is not a std::shared_ptr<ucxx::Endpoint>.

Parameters

[in]	endpointOrWorker	the parent component, which may either be a `std::shared_ptr<Endpoint>` or `std::shared_ptr<Worker>`.
[in]	requestData	container of the specified message type, including all type-specific data.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.
[in]	callbackFunction	user-defined callback function to call upon completion.
[in]	callbackData	user-defined data to pass to the `callbackFunction`.

Returns: The shared_ptr<ucxx::RequestTag> object

◆ createRequestTagMulti()

std::shared_ptr<RequestTagMulti> ucxx::createRequestTagMulti	(	std::shared_ptr< Endpoint >	endpoint,
		const std::variant< data::TagMultiSend, data::TagMultiReceive >	requestData,
		const bool	enablePythonFuture
	)

Initiate a multi-buffer tag 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 a send transfer must be verified from the resulting request object before the data can be released. If this is a receive transfer 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.

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 ucxx::RequestTag calls sending headers (depending on the number of frames being transferred), followed by one ucxx::RequestTag 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 to be compiled with UCXX_ENABLE_PYTHON=1.

Exceptions

std::runtime_error if sizes of buffer, size and isCUDA do not match.

Parameters

[in]	endpoint	the `std::shared_ptr<Endpoint>` parent component
[in]	requestData	container of the specified message type, including all type-specific data.
[in]	enablePythonFuture	whether a python future should be created and subsequently notified.

Returns: Request to be subsequently checked for the completion and its state.

◆ createWorker()

std::shared_ptr<Worker> ucxx::createWorker	(	std::shared_ptr< Context >	context,
		const bool	enableDelayedSubmission,
		const bool	enableFuture
	)

The constructor for a shared_ptr<ucxx::Worker> object. The default constructor is made private to ensure all UCXX objects are shared pointers for correct lifetime management.

// context is `std::shared_ptr<ucxx::Context>`
auto worker = context->createWorker(false);
 
// Equivalent to line above
// auto worker = ucxx::createWorker(context, false);

Parameters

[in]	context	the context from which to create the worker.
[in]	enableDelayedSubmission	if `true`, each `ucxx::Request` will not be submitted immediately, but instead delayed to the progress thread. Requires use of the progress thread.
[in]	enableFuture	if `true`, notifies the future associated with each `ucxx::Request`, currently used only by `ucxx::python::Worker`.

Returns: The shared_ptr<ucxx::Worker> object

◆ parseLogLevel()

void ucxx::parseLogLevel ( )

Parse the active log level.

Parse the active log level and set appropriate internal values to match the specified level.

◆ waitRequests()

void ucxx::waitRequests	(	std::shared_ptr< Worker >	worker,
		std::vector< std::shared_ptr< Request >>	requests
	)

Wait for a multiple requests to complete.

Block while waiting for all requests to complete.

Exceptions

ucxx::Error the specific error of the first request that failed.

Parameters

[in]	worker	the worker to progress until completion.
[in]	requests	the requests to wait for.

◆ waitSingleRequest()

void ucxx::waitSingleRequest	(	std::shared_ptr< Worker >	worker,
		std::shared_ptr< Request >	request
	)

Wait for a single request to complete.

Block while waiting for a single request to complete.

Exceptions

ucxx::Error a specific error if the request failed.

Parameters

[in]	worker	the worker to progress until completion.
[in]	request	the request to wait for.

Variable Documentation

◆ HeaderFramesSize

const size_t ucxx::HeaderFramesSize

Initial value:

=

100

The number of buffers contained in a single ucxx::Header object.

◆ logLevelDefault

const ucs_log_level_t ucxx::logLevelDefault = (ucs_log_level_t)logLevelNames.at(logLevelNameDefault)

The type of the default log level.

The type of default log level, automatically set based on the value of logLevelNameDefault.

◆ logLevelNameDefault

const char ucxx::logLevelNameDefault[] = "WARN"

The name of the default log level.

The name of default log level, must be one of the keys in logLevelNames.

◆ logLevelNames

const std::unordered_map<std::string, ucxx_log_level_t> ucxx::logLevelNames

Initial value:

= {
  {"FATAL", UCXX_LOG_LEVEL_FATAL},
  {"ERROR", UCXX_LOG_LEVEL_ERROR},
  {"WARN", UCXX_LOG_LEVEL_WARN},
  {"DIAG", UCXX_LOG_LEVEL_DIAG},
  {"INFO", UCXX_LOG_LEVEL_INFO},
  {"DEBUG", UCXX_LOG_LEVEL_DEBUG},
  {"TRACE", UCXX_LOG_LEVEL_TRACE},
  {"REQ", UCXX_LOG_LEVEL_TRACE_REQ},
  {"DATA", UCXX_LOG_LEVEL_TRACE_DATA},
  {"ASYNC", UCXX_LOG_LEVEL_TRACE_ASYNC},
  {"FUNC", UCXX_LOG_LEVEL_TRACE_FUNC},
  {"POLL", UCXX_LOG_LEVEL_TRACE_POLL},
  {"", UCXX_LOG_LEVEL_LAST},
  {"PRINT", UCXX_LOG_LEVEL_PRINT}}

Map of log level names to their respective types.

Map of log level names, used by the user to specify levels to enable, to their respective internal types.

◆ ucxx_log_component_config

ucs_log_component_config_t ucxx::ucxx_log_component_config

extern

The UCXX log level component configuration.

The type with the UCXX log level component configuration.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ AmAllocatorType

◆ AmReceiverCallbackIdType

◆ AmReceiverCallbackOwnerType

◆ AmReceiverCallbackType

◆ BufferRequestPtr

◆ ConfigMap

◆ DelayedSubmissionCallbackType

◆ EndpointCloseCallbackUserData

◆ EndpointCloseCallbackUserFunction

◆ InflightRequestsMap

◆ ProgressThreadStartCallback

◆ ProgressThreadStartCallbackArg

◆ RequestCallbackUserData

◆ RequestCallbackUserFunction

◆ RequestTagMultiPtr

◆ SignalWorkerFunction

◆ TrackedRequests

◆ TrackedRequestsPtr

Enumeration Type Documentation

◆ BufferType

◆ RequestNotifierThreadState

◆ RequestNotifierWaitState

◆ Tag

◆ TagMask

◆ TransferDirection

◆ ucxx_log_level_t

Function Documentation

◆ allocateBuffer()

◆ createAddressFromString()

◆ createAddressFromWorker()

◆ createContext()

◆ createEndpointFromConnRequest()

◆ createEndpointFromHostname()

◆ createEndpointFromWorkerAddress()

◆ createListener()

◆ createMemoryHandle()

◆ createRemoteKeyFromMemoryHandle()

◆ createRemoteKeyFromSerialized()

◆ createRequestAm()

◆ createRequestEndpointClose()

◆ createRequestFlush()

◆ createRequestMem()

◆ createRequestStream()

◆ createRequestTag()

◆ createRequestTagMulti()

◆ createWorker()

◆ parseLogLevel()

◆ waitRequests()

◆ waitSingleRequest()

Variable Documentation

◆ HeaderFramesSize

◆ logLevelDefault

◆ logLevelNameDefault

◆ logLevelNames

◆ ucxx_log_component_config