UCS Communication Resource

Data Structures
struct	ucs_sock_addr

Typedefs
typedef void(*	ucs_async_event_cb_t) (int id, ucs_event_set_types_t events, void *arg)
typedef struct ucs_sock_addr	ucs_sock_addr_t
typedef enum ucs_memory_type	ucs_memory_type_t
	Memory types. More...
typedef unsigned long	ucs_time_t
typedef void *	ucs_status_ptr_t
	Status pointer. More...

Enumerations
enum	ucs_callbackq_flags { UCS_CALLBACKQ_FLAG_FAST = UCS_BIT(0), UCS_CALLBACKQ_FLAG_ONESHOT = UCS_BIT(1) }
enum	ucs_memory_type {   UCS_MEMORY_TYPE_HOST, UCS_MEMORY_TYPE_CUDA, UCS_MEMORY_TYPE_CUDA_MANAGED, UCS_MEMORY_TYPE_ROCM,   UCS_MEMORY_TYPE_ROCM_MANAGED, UCS_MEMORY_TYPE_RDMA, UCS_MEMORY_TYPE_ZE_HOST, UCS_MEMORY_TYPE_ZE_DEVICE,   UCS_MEMORY_TYPE_ZE_MANAGED, UCS_MEMORY_TYPE_LAST, UCS_MEMORY_TYPE_UNKNOWN = UCS_MEMORY_TYPE_LAST }
	Memory types. More...
enum	ucs_status_t {   UCS_OK = 0, UCS_INPROGRESS = 1, UCS_ERR_NO_MESSAGE = -1, UCS_ERR_NO_RESOURCE = -2,   UCS_ERR_IO_ERROR = -3, UCS_ERR_NO_MEMORY = -4, UCS_ERR_INVALID_PARAM = -5, UCS_ERR_UNREACHABLE = -6,   UCS_ERR_INVALID_ADDR = -7, UCS_ERR_NOT_IMPLEMENTED = -8, UCS_ERR_MESSAGE_TRUNCATED = -9, UCS_ERR_NO_PROGRESS = -10,   UCS_ERR_BUFFER_TOO_SMALL = -11, UCS_ERR_NO_ELEM = -12, UCS_ERR_SOME_CONNECTS_FAILED = -13, UCS_ERR_NO_DEVICE = -14,   UCS_ERR_BUSY = -15, UCS_ERR_CANCELED = -16, UCS_ERR_SHMEM_SEGMENT = -17, UCS_ERR_ALREADY_EXISTS = -18,   UCS_ERR_OUT_OF_RANGE = -19, UCS_ERR_TIMED_OUT = -20, UCS_ERR_EXCEEDS_LIMIT = -21, UCS_ERR_UNSUPPORTED = -22,   UCS_ERR_REJECTED = -23, UCS_ERR_NOT_CONNECTED = -24, UCS_ERR_CONNECTION_RESET = -25, UCS_ERR_FIRST_LINK_FAILURE = -40,   UCS_ERR_LAST_LINK_FAILURE = -59, UCS_ERR_FIRST_ENDPOINT_FAILURE = -60, UCS_ERR_ENDPOINT_TIMEOUT = -80, UCS_ERR_LAST_ENDPOINT_FAILURE = -89,   UCS_ERR_LAST = -100 }
	Status codes. More...
enum	ucs_thread_mode_t { UCS_THREAD_MODE_SINGLE, UCS_THREAD_MODE_SERIALIZED, UCS_THREAD_MODE_MULTI, UCS_THREAD_MODE_LAST }
	Thread sharing mode. More...

Functions
ucs_status_t	ucs_async_set_event_handler (ucs_async_mode_t mode, int event_fd, ucs_event_set_types_t events, ucs_async_event_cb_t cb, void *arg, ucs_async_context_t *async)
ucs_status_t	ucs_async_add_timer (ucs_async_mode_t mode, ucs_time_t interval, ucs_async_event_cb_t cb, void *arg, ucs_async_context_t *async, int *timer_id_p)
ucs_status_t	ucs_async_remove_handler (int id, int sync)
ucs_status_t	ucs_async_modify_handler (int fd, ucs_event_set_types_t events)
ucs_status_t	ucs_async_context_create (ucs_async_mode_t mode, ucs_async_context_t **async_p)
	Create an asynchronous execution context. More...
void	ucs_async_context_destroy (ucs_async_context_t *async)
	Destroy the asynchronous execution context. More...
void	ucs_async_poll (ucs_async_context_t *async)

Detailed Description

This section describes a concept of the Communication Resource and routines associated with the concept.

---

Data Structure Documentation

ucs_sock_addr

struct ucs_sock_addr

BSD socket address specification.

Data Fields
const struct sockaddr *	addr	Pointer to socket address
socklen_t	addrlen	Address length

Typedef Documentation

ucs_async_event_cb_t

typedef void(* ucs_async_event_cb_t) (int id, ucs_event_set_types_t events, void *arg)

Async event callback.

Parameters

id	Event id (timer or file descriptor).
events	The events that triggered the callback.
arg	User-defined argument.

ucs_sock_addr_t

typedef struct ucs_sock_addr ucs_sock_addr_t

BSD socket address specification.

ucs_memory_type_t

typedef enum ucs_memory_type ucs_memory_type_t

List of supported memory types.

ucs_time_t

typedef unsigned long ucs_time_t

UCS time units. These are not necessarily aligned with metric time units. MUST compare short time values with UCS_SHORT_TIME_CMP to handle wrap-around.

ucs_status_ptr_t

typedef void* ucs_status_ptr_t

A pointer can represent one of these values:

• NULL / UCS_OK
• Error code pointer (UCS_ERR_xx)
• Valid pointer

Enumeration Type Documentation

ucs_callbackq_flags

enum ucs_callbackq_flags

Copyright (c) NVIDIA CORPORATION & AFFILIATES, 2023. ALL RIGHTS RESERVED.

See file LICENSE for terms.

Callback backward compatibility flags

Enumerator
UCS_CALLBACKQ_FLAG_FAST	Fast-path (best effort)
UCS_CALLBACKQ_FLAG_ONESHOT	Call the callback only once (cannot be used with FAST)

ucs_memory_type

enum ucs_memory_type

List of supported memory types.

Enumerator
UCS_MEMORY_TYPE_HOST	Default system memory
UCS_MEMORY_TYPE_CUDA	NVIDIA CUDA memory
UCS_MEMORY_TYPE_CUDA_MANAGED	NVIDIA CUDA managed (or unified) memory
UCS_MEMORY_TYPE_ROCM	AMD ROCM memory
UCS_MEMORY_TYPE_ROCM_MANAGED	AMD ROCM managed system memory
UCS_MEMORY_TYPE_RDMA	RDMA device memory
UCS_MEMORY_TYPE_ZE_HOST	Intel ZE memory (USM host)
UCS_MEMORY_TYPE_ZE_DEVICE	Intel ZE memory (USM device)
UCS_MEMORY_TYPE_ZE_MANAGED	Intel ZE managed memory (USM shared)
UCS_MEMORY_TYPE_LAST
UCS_MEMORY_TYPE_UNKNOWN

ucs_status_t

enum ucs_status_t

Note

In order to evaluate the necessary steps to recover from a certain error, all error codes which can be returned by the external API are grouped by the largest entity permanently effected by the error. Each group ranges between its UCS_ERR_FIRST_<name> and UCS_ERR_LAST_<name> enum values. For example, if a link fails it may be sufficient to destroy (and possibly replace) it, in contrast to an endpoint-level error.

Enumerator
UCS_OK
UCS_INPROGRESS
UCS_ERR_NO_MESSAGE
UCS_ERR_NO_RESOURCE
UCS_ERR_IO_ERROR
UCS_ERR_NO_MEMORY
UCS_ERR_INVALID_PARAM
UCS_ERR_UNREACHABLE
UCS_ERR_INVALID_ADDR
UCS_ERR_NOT_IMPLEMENTED
UCS_ERR_MESSAGE_TRUNCATED
UCS_ERR_NO_PROGRESS
UCS_ERR_BUFFER_TOO_SMALL
UCS_ERR_NO_ELEM
UCS_ERR_SOME_CONNECTS_FAILED
UCS_ERR_NO_DEVICE
UCS_ERR_BUSY
UCS_ERR_CANCELED
UCS_ERR_SHMEM_SEGMENT
UCS_ERR_ALREADY_EXISTS
UCS_ERR_OUT_OF_RANGE
UCS_ERR_TIMED_OUT
UCS_ERR_EXCEEDS_LIMIT
UCS_ERR_UNSUPPORTED
UCS_ERR_REJECTED
UCS_ERR_NOT_CONNECTED
UCS_ERR_CONNECTION_RESET
UCS_ERR_FIRST_LINK_FAILURE
UCS_ERR_LAST_LINK_FAILURE
UCS_ERR_FIRST_ENDPOINT_FAILURE
UCS_ERR_ENDPOINT_TIMEOUT
UCS_ERR_LAST_ENDPOINT_FAILURE
UCS_ERR_LAST

Examples:

uct_hello_world.c.

ucs_thread_mode_t

enum ucs_thread_mode_t

Specifies thread sharing mode of an object.

Enumerator
UCS_THREAD_MODE_SINGLE	Only the master thread can access (i.e. the thread that initialized the context; multiple threads may exist and never access)
UCS_THREAD_MODE_SERIALIZED	Multiple threads can access, but only one at a time
UCS_THREAD_MODE_MULTI	Multiple threads can access concurrently
UCS_THREAD_MODE_LAST

Function Documentation

ucs_async_set_event_handler()

ucs_status_t ucs_async_set_event_handler	(	ucs_async_mode_t	mode,
		int	event_fd,
		ucs_event_set_types_t	events,
		ucs_async_event_cb_t	cb,
		void *	arg,
		ucs_async_context_t *	async
	)

Register a file descriptor for monitoring (call handler upon events). Every fd can have only one handler.

Parameters

mode	Thread or signal.
event_fd	File descriptor to set handler for.
events	Events to wait on (UCS_EVENT_SET_EVxxx bits).
cb	Callback function to execute.
arg	Argument to callback.
async	Async context to which events are delivered. If NULL, safety is up to the user.

Returns

Error code as defined by ucs_status_t.

ucs_async_add_timer()

ucs_status_t ucs_async_add_timer	(	ucs_async_mode_t	mode,
		ucs_time_t	interval,
		ucs_async_event_cb_t	cb,
		void *	arg,
		ucs_async_context_t *	async,
		int *	timer_id_p
	)

Add timer handler.

Parameters

mode	Thread or signal.
interval	Timer interval.
cb	Callback function to execute.
arg	Argument to callback.
async	Async context to which events are delivered. If NULL, safety is up to the user.
timer_id_p	Filled with timer id.

Returns

Error code as defined by ucs_status_t.

ucs_async_remove_handler()

ucs_status_t ucs_async_remove_handler	(	int	id,
		int	sync
	)

Remove an event handler (Timer or event file).

Parameters

id	Timer/FD to remove.
sync	If nonzero, wait until the handler for this event is not running anymore. If called from the context of the callback, the handler will be removed immediately after the current callback returns.

Returns

Error code as defined by ucs_status_t.

ucs_async_modify_handler()

ucs_status_t ucs_async_modify_handler	(	int	fd,
		ucs_event_set_types_t	events
	)

Modify events mask for an existing event handler (event file).

Parameters

fd	File descriptor modify events for.
events	New set of events to wait on (UCS_EVENT_SET_EVxxx bits).

Returns

Error code as defined by ucs_status_t.

ucs_async_context_create()

ucs_status_t ucs_async_context_create	(	ucs_async_mode_t	mode,
		ucs_async_context_t **	async_p
	)

Allocate and initialize an asynchronous execution context. This can be used to ensure safe event delivery.

Parameters

mode	Indicates whether to use signals or polling threads for waiting.
async_p	Event context pointer to initialize.

Returns

Error code as defined by ucs_status_t.

Examples:

uct_hello_world.c.

ucs_async_context_destroy()

void ucs_async_context_destroy

(

ucs_async_context_t *

async

)

Clean up the async context, and release system resources if possible. The context memory released.

Parameters

async

Asynchronous context to clean up.

Examples:

uct_hello_world.c.

ucs_async_poll()

void ucs_async_poll

(

ucs_async_context_t *

async

)

Poll on async context.

Parameters

async

Async context to poll on. NULL polls on all.