UCX 1.16
Unified Communication X
Loading...
Searching...
No Matches

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.
 
typedef unsigned long ucs_time_t
 
typedef void * ucs_status_ptr_t
 Status pointer.
 

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_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.
 
void ucs_async_context_destroy (ucs_async_context_t *async)
 Destroy the asynchronous execution context.
 
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
idEvent id (timer or file descriptor).
eventsThe events that triggered the callback.
argUser-defined argument.

◆ ucs_sock_addr_t

BSD socket address specification.

◆ 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

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

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_LAST 
UCS_MEMORY_TYPE_UNKNOWN 

◆ 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

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
modeThread or signal.
event_fdFile descriptor to set handler for.
eventsEvents to wait on (UCS_EVENT_SET_EVxxx bits).
cbCallback function to execute.
argArgument to callback.
asyncAsync 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
modeThread or signal.
intervalTimer interval.
cbCallback function to execute.
argArgument to callback.
asyncAsync context to which events are delivered. If NULL, safety is up to the user.
timer_id_pFilled 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
idTimer/FD to remove.
syncIf 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
fdFile descriptor modify events for.
eventsNew 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
modeIndicates whether to use signals or polling threads for waiting.
async_pEvent 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
asyncAsynchronous 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
asyncAsync context to poll on. NULL polls on all.