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

Topics

 UCT interface operations and capabilities
 List of capabilities supported by UCX API.
 
 UCT interface for asynchronous event capabilities
 List of capabilities supported by UCT iface event API.
 

Data Structures

struct  uct_md_resource_desc
 Memory domain resource descriptor. More...
 
struct  uct_component_attr
 UCT component attributes. More...
 
struct  uct_tl_resource_desc
 Communication resource descriptor. More...
 
struct  uct_iface_attr
 Interface attributes: capabilities and limitations. More...
 
struct  uct_iface_params
 Parameters used for interface creation. More...
 
struct  uct_ep_params
 Parameters for creating a UCT endpoint by uct_ep_create. More...
 
struct  uct_completion
 Completion handle. More...
 
struct  uct_pending_req
 Pending request. More...
 
struct  uct_iov
 Structure for scatter-gather I/O. More...
 
struct  uct_iface_attr.cap
 
struct  uct_iface_attr.cap.put
 
struct  uct_iface_attr.cap.get
 
struct  uct_iface_attr.cap.am
 
struct  uct_iface_attr.cap.tag
 
struct  uct_iface_attr.cap.tag.recv
 
struct  uct_iface_attr.cap.tag.eager
 
struct  uct_iface_attr.cap.tag.rndv
 
struct  uct_iface_attr.cap.atomic32
 
struct  uct_iface_attr.cap.atomic64
 
union  uct_iface_params.mode
 
struct  uct_iface_params.mode.device
 
struct  uct_iface_params.mode.sockaddr
 

Typedefs

typedef struct uct_md_resource_desc uct_md_resource_desc_t
 Memory domain resource descriptor.
 
typedef struct uct_component_attr uct_component_attr_t
 UCT component attributes.
 
typedef struct uct_tl_resource_desc uct_tl_resource_desc_t
 Communication resource descriptor.
 
typedef struct uct_component * uct_component_h
 
typedef struct uct_iface * uct_iface_h
 
typedef struct uct_iface_config uct_iface_config_t
 
typedef struct uct_md_config uct_md_config_t
 
typedef struct uct_cm_config uct_cm_config_t
 
typedef struct uct_ep * uct_ep_h
 
typedef void * uct_mem_h
 
typedef uintptr_t uct_rkey_t
 
typedef struct uct_md * uct_md_h
 Memory domain handler.
 
typedef struct uct_md_ops uct_md_ops_t
 
typedef void * uct_rkey_ctx_h
 
typedef struct uct_iface_attr uct_iface_attr_t
 
typedef struct uct_iface_params uct_iface_params_t
 
typedef struct uct_ep_attr uct_ep_attr_t
 
typedef struct uct_md_attr uct_md_attr_t
 
typedef struct uct_completion uct_completion_t
 
typedef struct uct_pending_req uct_pending_req_t
 
typedef struct uct_worker * uct_worker_h
 
typedef struct uct_md uct_md_t
 
typedef enum uct_am_trace_type uct_am_trace_type_t
 
typedef struct uct_device_addr uct_device_addr_t
 
typedef struct uct_iface_addr uct_iface_addr_t
 
typedef struct uct_ep_addr uct_ep_addr_t
 
typedef struct uct_ep_params uct_ep_params_t
 
typedef struct uct_ep_connect_params uct_ep_connect_params_t
 
typedef struct uct_cm_attr uct_cm_attr_t
 
typedef struct uct_cm uct_cm_t
 
typedef uct_cm_tuct_cm_h
 
typedef struct uct_listener_attr uct_listener_attr_t
 
typedef struct uct_listener * uct_listener_h
 
typedef struct uct_listener_params uct_listener_params_t
 
typedef struct uct_tag_context uct_tag_context_t
 
typedef uint64_t uct_tag_t
 
typedef int uct_worker_cb_id_t
 
typedef void * uct_conn_request_h
 
typedef struct uct_iov uct_iov_t
 Structure for scatter-gather I/O.
 
typedef void(* uct_completion_callback_t) (uct_completion_t *self)
 Callback to process send completion.
 
typedef ucs_status_t(* uct_pending_callback_t) (uct_pending_req_t *self)
 Callback to process pending requests.
 
typedef ucs_status_t(* uct_error_handler_t) (void *arg, uct_ep_h ep, ucs_status_t status)
 Callback to process peer failure.
 
typedef void(* uct_pending_purge_callback_t) (uct_pending_req_t *self, void *arg)
 Callback to purge pending requests.
 
typedef size_t(* uct_pack_callback_t) (void *dest, void *arg)
 Callback for producing data.
 
typedef void(* uct_unpack_callback_t) (void *arg, const void *data, size_t length)
 Callback for consuming data.
 
typedef void(* uct_async_event_cb_t) (void *arg, unsigned flags)
 Callback to process asynchronous events.
 

Enumerations

enum  uct_component_attr_field { UCT_COMPONENT_ATTR_FIELD_NAME = UCS_BIT(0) , UCT_COMPONENT_ATTR_FIELD_MD_RESOURCE_COUNT = UCS_BIT(1) , UCT_COMPONENT_ATTR_FIELD_MD_RESOURCES = UCS_BIT(2) , UCT_COMPONENT_ATTR_FIELD_FLAGS = UCS_BIT(3) }
 UCT component attributes field mask. More...
 
enum  { UCT_COMPONENT_FLAG_CM = UCS_BIT(0) , UCT_COMPONENT_FLAG_RKEY_PTR = UCS_BIT(1) }
 Capability flags of uct_component_h. More...
 
enum  uct_device_type_t {
  UCT_DEVICE_TYPE_NET , UCT_DEVICE_TYPE_SHM , UCT_DEVICE_TYPE_ACC , UCT_DEVICE_TYPE_SELF ,
  UCT_DEVICE_TYPE_LAST
}
 List of UCX device types. More...
 
enum  uct_iface_event_types { UCT_EVENT_SEND_COMP = UCS_BIT(0) , UCT_EVENT_RECV = UCS_BIT(1) , UCT_EVENT_RECV_SIG = UCS_BIT(2) }
 Asynchronous event types. More...
 
enum  uct_flush_flags { UCT_FLUSH_FLAG_LOCAL = 0 , UCT_FLUSH_FLAG_CANCEL = UCS_BIT(0) , UCT_FLUSH_FLAG_REMOTE = UCS_BIT(1) }
 Flush modifiers. More...
 
enum  uct_progress_types { UCT_PROGRESS_SEND = UCS_BIT(0) , UCT_PROGRESS_RECV = UCS_BIT(1) , UCT_PROGRESS_THREAD_SAFE = UCS_BIT(7) }
 UCT progress types. More...
 
enum  uct_cb_flags { UCT_CB_FLAG_RESERVED = UCS_BIT(1) , UCT_CB_FLAG_ASYNC = UCS_BIT(2) }
 Callback flags. More...
 
enum  uct_iface_open_mode { UCT_IFACE_OPEN_MODE_DEVICE = UCS_BIT(0) , UCT_IFACE_OPEN_MODE_SOCKADDR_SERVER = UCS_BIT(1) , UCT_IFACE_OPEN_MODE_SOCKADDR_CLIENT = UCS_BIT(2) }
 Mode in which to open the interface. More...
 
enum  uct_iface_params_field {
  UCT_IFACE_PARAM_FIELD_CPU_MASK = UCS_BIT(0) , UCT_IFACE_PARAM_FIELD_OPEN_MODE = UCS_BIT(1) , UCT_IFACE_PARAM_FIELD_DEVICE = UCS_BIT(2) , UCT_IFACE_PARAM_FIELD_SOCKADDR = UCS_BIT(3) ,
  UCT_IFACE_PARAM_FIELD_STATS_ROOT = UCS_BIT(4) , UCT_IFACE_PARAM_FIELD_RX_HEADROOM = UCS_BIT(5) , UCT_IFACE_PARAM_FIELD_ERR_HANDLER_ARG = UCS_BIT(6) , UCT_IFACE_PARAM_FIELD_ERR_HANDLER = UCS_BIT(7) ,
  UCT_IFACE_PARAM_FIELD_ERR_HANDLER_FLAGS = UCS_BIT(8) , UCT_IFACE_PARAM_FIELD_HW_TM_EAGER_ARG = UCS_BIT(9) , UCT_IFACE_PARAM_FIELD_HW_TM_EAGER_CB = UCS_BIT(10) , UCT_IFACE_PARAM_FIELD_HW_TM_RNDV_ARG = UCS_BIT(11) ,
  UCT_IFACE_PARAM_FIELD_HW_TM_RNDV_CB = UCS_BIT(12) , UCT_IFACE_PARAM_FIELD_ASYNC_EVENT_ARG = UCS_BIT(13) , UCT_IFACE_PARAM_FIELD_ASYNC_EVENT_CB = UCS_BIT(14) , UCT_IFACE_PARAM_FIELD_KEEPALIVE_INTERVAL = UCS_BIT(15) ,
  UCT_IFACE_PARAM_FIELD_AM_ALIGNMENT = UCS_BIT(16) , UCT_IFACE_PARAM_FIELD_AM_ALIGN_OFFSET = UCS_BIT(17) , UCT_IFACE_PARAM_FIELD_FEATURES = UCS_BIT(18)
}
 UCT interface created by uct_iface_open parameters field mask. More...
 
enum  uct_ep_params_field {
  UCT_EP_PARAM_FIELD_IFACE = UCS_BIT(0) , UCT_EP_PARAM_FIELD_USER_DATA = UCS_BIT(1) , UCT_EP_PARAM_FIELD_DEV_ADDR = UCS_BIT(2) , UCT_EP_PARAM_FIELD_IFACE_ADDR = UCS_BIT(3) ,
  UCT_EP_PARAM_FIELD_SOCKADDR = UCS_BIT(4) , UCT_EP_PARAM_FIELD_SOCKADDR_CB_FLAGS = UCS_BIT(5) , UCT_EP_PARAM_FIELD_SOCKADDR_PACK_CB = UCS_BIT(6) , UCT_EP_PARAM_FIELD_CM = UCS_BIT(7) ,
  UCT_EP_PARAM_FIELD_CONN_REQUEST = UCS_BIT(8) , UCT_EP_PARAM_FIELD_SOCKADDR_CONNECT_CB_CLIENT = UCS_BIT(9) , UCT_EP_PARAM_FIELD_SOCKADDR_NOTIFY_CB_SERVER = UCS_BIT(10) , UCT_EP_PARAM_FIELD_SOCKADDR_DISCONNECT_CB = UCS_BIT(11) ,
  UCT_EP_PARAM_FIELD_PATH_INDEX = UCS_BIT(12) , UCT_EP_PARAM_FIELD_CM_RESOLVE_CB = UCS_BIT(13) , UCT_EP_PARAM_FIELD_PRIV_DATA = UCS_BIT(14) , UCT_EP_PARAM_FIELD_PRIV_DATA_LENGTH = UCS_BIT(15) ,
  UCT_EP_PARAM_FIELD_LOCAL_SOCKADDR = UCS_BIT(16)
}
 UCT endpoint created by uct_ep_create parameters field mask. More...
 
enum  uct_iface_feature {
  UCT_IFACE_FEATURE_AM = UCS_BIT(0) , UCT_IFACE_FEATURE_PUT = UCS_BIT(1) , UCT_IFACE_FEATURE_GET = UCS_BIT(2) , UCT_IFACE_FEATURE_AMO32 = UCS_BIT(3) ,
  UCT_IFACE_FEATURE_AMO64 = UCS_BIT(4) , UCT_IFACE_FEATURE_TAG = UCS_BIT(5) , UCT_IFACE_FEATURE_FLUSH_REMOTE = UCS_BIT(6) , UCT_IFACE_FEATURE_LAST = UCS_BIT(7)
}
 UCT interface configuration features. More...
 
enum  { UCT_TAG_RECV_CB_INLINE_DATA = UCS_BIT(0) }
 flags of uct_tag_context. More...
 
enum  uct_cb_param_flags { UCT_CB_PARAM_FLAG_DESC = UCS_BIT(0) , UCT_CB_PARAM_FLAG_FIRST = UCS_BIT(1) , UCT_CB_PARAM_FLAG_MORE = UCS_BIT(2) }
 Flags for active message and tag-matching offload callbacks (callback's parameters). More...
 

Functions

ucs_status_t uct_query_components (uct_component_h **components_p, unsigned *num_components_p)
 Query for list of components.
 
void uct_release_component_list (uct_component_h *components)
 Release the list of components returned from uct_query_components.
 
ucs_status_t uct_component_query (uct_component_h component, uct_component_attr_t *component_attr)
 Get component attributes.
 
ucs_status_t uct_md_open (uct_component_h component, const char *md_name, const uct_md_config_t *config, uct_md_h *md_p)
 Open a memory domain.
 
void uct_md_close (uct_md_h md)
 Close a memory domain.
 
ucs_status_t uct_md_query_tl_resources (uct_md_h md, uct_tl_resource_desc_t **resources_p, unsigned *num_resources_p)
 Query for transport resources.
 
void uct_release_tl_resource_list (uct_tl_resource_desc_t *resources)
 Release the list of resources returned from uct_md_query_tl_resources.
 
ucs_status_t uct_md_iface_config_read (uct_md_h md, const char *tl_name, const char *env_prefix, const char *filename, uct_iface_config_t **config_p)
 Read transport-specific interface configuration.
 
void uct_config_release (void *config)
 Release configuration memory returned from uct_md_iface_config_read(), uct_md_config_read(), or from uct_cm_config_read().
 
ucs_status_t uct_iface_open (uct_md_h md, uct_worker_h worker, const uct_iface_params_t *params, const uct_iface_config_t *config, uct_iface_h *iface_p)
 Open a communication interface.
 
void uct_iface_close (uct_iface_h iface)
 Close and destroy an interface.
 
ucs_status_t uct_iface_query (uct_iface_h iface, uct_iface_attr_t *iface_attr)
 Get interface attributes.
 
ucs_status_t uct_iface_get_device_address (uct_iface_h iface, uct_device_addr_t *addr)
 Get address of the device the interface is using.
 
ucs_status_t uct_iface_get_address (uct_iface_h iface, uct_iface_addr_t *addr)
 Get interface address.
 
int uct_iface_is_reachable (const uct_iface_h iface, const uct_device_addr_t *dev_addr, const uct_iface_addr_t *iface_addr)
 Check if remote iface address is reachable.
 
ucs_status_t uct_ep_check (const uct_ep_h ep, unsigned flags, uct_completion_t *comp)
 check if the destination endpoint is alive in respect to UCT library
 
ucs_status_t uct_iface_event_fd_get (uct_iface_h iface, int *fd_p)
 Obtain a notification file descriptor for polling.
 
ucs_status_t uct_iface_event_arm (uct_iface_h iface, unsigned events)
 Turn on event notification for the next event.
 
ucs_status_t uct_iface_mem_alloc (uct_iface_h iface, size_t length, unsigned flags, const char *name, uct_allocated_memory_t *mem)
 Allocate memory which can be used for zero-copy communications.
 
void uct_iface_mem_free (const uct_allocated_memory_t *mem)
 Release memory allocated with uct_iface_mem_alloc().
 
ucs_status_t uct_ep_create (const uct_ep_params_t *params, uct_ep_h *ep_p)
 Create new endpoint.
 
void uct_ep_destroy (uct_ep_h ep)
 Destroy an endpoint.
 
ucs_status_t uct_ep_get_address (uct_ep_h ep, uct_ep_addr_t *addr)
 Get endpoint address.
 
ucs_status_t uct_ep_connect_to_ep (uct_ep_h ep, const uct_device_addr_t *dev_addr, const uct_ep_addr_t *ep_addr)
 Connect endpoint to a remote endpoint.
 
ucs_status_t uct_iface_flush (uct_iface_h iface, unsigned flags, uct_completion_t *comp)
 Flush outstanding communication operations on an interface.
 
ucs_status_t uct_iface_fence (uct_iface_h iface, unsigned flags)
 Ensures ordering of outstanding communications on the interface. Operations issued on the interface prior to this call are guaranteed to be completed before any subsequent communication operations to the same interface which follow the call to fence.
 
ucs_status_t uct_ep_pending_add (uct_ep_h ep, uct_pending_req_t *req, unsigned flags)
 Add a pending request to an endpoint.
 
void uct_ep_pending_purge (uct_ep_h ep, uct_pending_purge_callback_t cb, void *arg)
 Remove all pending requests from an endpoint.
 
ucs_status_t uct_ep_flush (uct_ep_h ep, unsigned flags, uct_completion_t *comp)
 Flush outstanding communication operations on an endpoint.
 
ucs_status_t uct_ep_fence (uct_ep_h ep, unsigned flags)
 Ensures ordering of outstanding communications on the endpoint. Operations issued on the endpoint prior to this call are guaranteed to be completed before any subsequent communication operations to the same endpoint which follow the call to fence.
 
void uct_iface_progress_enable (uct_iface_h iface, unsigned flags)
 Enable synchronous progress for the interface.
 
void uct_iface_progress_disable (uct_iface_h iface, unsigned flags)
 Disable synchronous progress for the interface.
 
unsigned uct_iface_progress (uct_iface_h iface)
 Perform a progress on an interface.
 
static UCS_F_ALWAYS_INLINE void uct_completion_update_status (uct_completion_t *comp, ucs_status_t status)
 Update status of UCT completion handle.
 

Detailed Description

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


Data Structure Documentation

◆ uct_md_resource_desc

struct uct_md_resource_desc

This structure describes a memory domain resource.

Data Fields
char md_name[UCT_MD_NAME_MAX]

Memory domain name

◆ uct_component_attr

struct uct_component_attr

This structure defines the attributes for UCT component. It is used for uct_component_query

Examples
uct_hello_world.c.
Data Fields
uint64_t field_mask

Mask of valid fields in this structure, using bits from uct_component_attr_field. Fields not specified in this mask will be ignored. Provides ABI compatibility with respect to adding new fields.

char name[UCT_COMPONENT_NAME_MAX]

Component name

unsigned md_resource_count

Number of memory-domain resources

uct_md_resource_desc_t * md_resources

Array of memory domain resources. When used, it should be initialized prior to calling uct_component_query with a pointer to an array, which is large enough to hold all memory domain resource entries. After the call, this array will be filled with information about existing memory domain resources. In order to allocate this array, you can call uct_component_query twice: The first time would only obtain the amount of entries required, by specifying UCT_COMPONENT_ATTR_FIELD_MD_RESOURCE_COUNT in field_mask. Then the array could be allocated with the returned number of entries, and passed to a second call to uct_component_query, this time setting field_mask to UCT_COMPONENT_ATTR_FIELD_MD_RESOURCES.

uint64_t flags

Flags as defined by UCT_COMPONENT_FLAG_xx.

◆ uct_tl_resource_desc

struct uct_tl_resource_desc

Resource descriptor is an object representing the network resource. Resource descriptor could represent a stand-alone communication resource such as an HCA port, network interface, or multiple resources such as multiple network interfaces or communication ports. It could also represent virtual communication resources that are defined over a single physical network interface.

Examples
uct_hello_world.c.
Data Fields
char tl_name[UCT_TL_NAME_MAX]

Transport name

char dev_name[UCT_DEVICE_NAME_MAX]

Hardware device name

uct_device_type_t dev_type

The device represented by this resource (e.g. UCT_DEVICE_TYPE_NET for a network interface)

ucs_sys_device_t sys_device

The identifier associated with the device bus_id as captured in ucs_sys_bus_id_t struct

◆ uct_iface_attr

struct uct_iface_attr
Data Fields
struct uct_iface_attr.cap cap

Interface capabilities

size_t device_addr_len

Size of device address

size_t iface_addr_len

Size of interface address

size_t ep_addr_len

Size of endpoint address

size_t max_conn_priv

Max size of the iface's private data. used for connection establishment with sockaddr

struct sockaddr_storage listen_sockaddr

Sockaddr on which this iface is listening.

double overhead

Message overhead, seconds

uct_ppn_bandwidth_t bandwidth

Bandwidth model

ucs_linear_func_t latency

Latency as function of number of active endpoints

uint8_t priority

Priority of device

size_t max_num_eps

Maximum number of endpoints

unsigned dev_num_paths

How many network paths can be utilized on the device used by this interface for optimal performance. Endpoints that connect to the same remote address but use different paths can potentially achieve higher total bandwidth compared to using only a single endpoint.

◆ uct_iface_params

struct uct_iface_params

This structure should be allocated by the user and should be passed to uct_iface_open. User has to initialize all fields of this structure.

Examples
uct_hello_world.c.
Data Fields
uint64_t field_mask

Mask of valid fields in this structure, using bits from uct_iface_params_field. Fields not specified in this mask will be ignored.

ucs_cpu_set_t cpu_mask

Mask of CPUs to use for resources

uint64_t open_mode

Interface open mode bitmap. uct_iface_open_mode

union uct_iface_params.mode mode

Mode-specific parameters

ucs_stats_node_t * stats_root

Root in the statistics tree. Can be NULL. If non NULL, it will be a root of uct_iface object in the statistics tree.

size_t rx_headroom

How much bytes to reserve before the receive segment.

void * err_handler_arg

Custom argument of err_handler.

uct_error_handler_t err_handler

The callback to handle transport level error.

uint32_t err_handler_flags

Callback flags to indicate where the err_handler callback can be invoked from. uct_cb_flags

void * eager_arg

These callbacks are only relevant for HW Tag Matching

uct_tag_unexp_eager_cb_t eager_cb

Callback for tag matching unexpected eager messages

void * rndv_arg
uct_tag_unexp_rndv_cb_t rndv_cb

Callback for tag matching unexpected rndv messages

void * async_event_arg
uct_async_event_cb_t async_event_cb

Callback for asynchronous event handling. The callback will be invoked from UCT transport when there are new events to be read by user if the iface has UCT_IFACE_FLAG_EVENT_ASYNC_CB capability

ucs_time_t keepalive_interval
size_t am_alignment

Desired alignment for Active Messages on the receiver. Note that only data received in the UCT descriptor can be aligned (i.e. UCT_CB_PARAM_FLAG_DESC flag is provided in the Active Message handler callback). The provided value must be power of 2. The default value is 1.

size_t am_align_offset

Offset in the Active Message receive buffer, which should be aligned to the am_alignment boundary. Note this parameter has no effect without setting am_alignment parameter. The provided value must be less than the given am_alignment value. The default value is 0.

+-+ pointer to data in uct_am_callback_t | | + alignment boundary | | v v +----------------—+ | align | | | offset | | +----------------—+

uint64_t features

UCT features that are used for interface initialization.

◆ uct_ep_params

struct uct_ep_params
Data Fields
uint64_t field_mask

Mask of valid fields in this structure, using bits from uct_ep_params_field. Fields not specified by this mask will be ignored.

uct_iface_h iface

Interface to create the endpoint on. Either iface or cm field must be initialized but not both.

void * user_data

User data associated with the endpoint.

const uct_device_addr_t * dev_addr

The device address to connect to on the remote peer. This must be defined together with uct_ep_params_t::iface_addr to create an endpoint connected to a remote interface.

const uct_iface_addr_t * iface_addr

This specifies the remote address to use when creating an endpoint that is connected to a remote interface.

Note
This requires UCT_IFACE_FLAG_CONNECT_TO_IFACE capability.
const ucs_sock_addr_t * sockaddr

The sockaddr to connect to on the remote peer. If set, uct_ep_create will create an endpoint for a connection to the remote peer, specified by its socket address.

Note
The interface in this routine requires the UCT_IFACE_FLAG_CONNECT_TO_SOCKADDR capability.
uint32_t sockaddr_cb_flags

uct_cb_flags to indicate uct_ep_params_t::sockaddr_pack_cb, uct_ep_params_t::sockaddr_cb_client, uct_ep_params_t::sockaddr_cb_server, uct_ep_params_t::disconnect_cb and uct_ep_params_t::cm_resolve_cb behavior. If none from these are not set, this field will be ignored.

uct_cm_ep_priv_data_pack_callback_t sockaddr_pack_cb

Callback that will be used for filling the user's private data to be delivered to the remote peer by the callback on the server or client side. This field is only valid if uct_ep_params_t::sockaddr is set.

Note
It is never guaranteed that the callback will be called. If, for example, the endpoint goes into error state before issuing the connection request, the callback will not be invoked.
Can not be set together with uct_ep_params_t::private_data or uct_ep_params_t::cm_resolve_cb.
uct_cm_h cm

The connection manager object as created by uct_cm_open. Either cm or iface field must be initialized but not both.

uct_conn_request_h conn_request

Connection request that was passed to uct_cm_listener_conn_request_args_t::conn_request.

Note
After a call to uct_ep_create, params.conn_request is consumed and should not be used anymore, even if the call returns with an error.
uct_cm_ep_client_connect_callback_t sockaddr_cb_client

Callback that will be invoked when the endpoint on the client side is being connected to the server by a connection manager uct_cm_h .

uct_cm_ep_server_conn_notify_callback_t sockaddr_cb_server

Callback that will be invoked when the endpoint on the server side is being connected to a client by a connection manager uct_cm_h .

uct_ep_disconnect_cb_t disconnect_cb

Callback that will be invoked when the endpoint is disconnected.

unsigned path_index

Index of the path which the endpoint should use, must be in the range 0..(uct_iface_attr_t::dev_num_paths - 1).

uct_cm_ep_resolve_callback_t cm_resolve_cb

This callback is invoked when the remote server address provided in field uct_ep_params_t::sockaddr is resolved to the local device to be used for connection establishment.

Note
This field is mutually exclusive with uct_ep_params::sockaddr_pack_cb.
const void * private_data

Private data to be passed from server to client. Can be used only along with uct_ep_params::conn_request.

Note
This field is mutually exclusive with uct_ep_params::sockaddr_pack_cb.
size_t private_data_length

Length of uct_ep_params::private_data, the maximal allowed value is indicated by the uct_cm_attr::max_conn_priv.

const ucs_sock_addr_t * local_sockaddr

The sockaddr to bind locally. If set, uct_ep_create will create an endpoint binding to this local sockaddr.

Note
The interface in this routine requires the UCT_IFACE_FLAG_CONNECT_TO_SOCKADDR capability.

◆ uct_completion

struct uct_completion

This structure should be allocated by the user and can be passed to communication primitives. The user must initialize all fields of the structure. If the operation returns UCS_INPROGRESS, this structure will be in use by the transport until the operation completes. When the operation completes, "count" field is decremented by 1, and whenever it reaches 0 - the callback is called.

Notes:

  • The same structure can be passed multiple times to communication functions without the need to wait for completion.
  • If the number of operations is smaller than the initial value of the counter, the callback will not be called at all, so it may be left undefined.
  • status field is required to track the first time the error occurred, and report it via a callback when count reaches 0.
Examples
uct_hello_world.c.
Data Fields
uct_completion_callback_t func

User callback function

int count

Completion counter

ucs_status_t status

Completion status, this field must be initialized with UCS_OK before first operation is started.

◆ uct_pending_req

struct uct_pending_req

This structure should be passed to uct_ep_pending_add() and is used to signal new available resources back to user.

Data Fields
uct_pending_callback_t func

User callback function

char priv[UCT_PENDING_REQ_PRIV_LEN]

Used internally by UCT

◆ uct_iov

struct uct_iov

Specifies a list of buffers which can be used within a single data transfer function call.

 buffer
 |
 +-----------+-------+-----------+-------+-----------+
 |  payload  | empty |  payload  | empty |  payload  |
 +-----------+-------+-----------+-------+-----------+
 |<-length-->|       |<-length-->|       |<-length-->|
 |<---- stride ----->|<---- stride ----->|
Note
The sum of lengths in all iov list must be less or equal to max_zcopy of the respective communication operation.
If length or count are zero, the memory pointed to by buffer will not be accessed. Otherwise, buffer must point to valid memory.
If count is one, every iov entry specifies a single contiguous data block
If count > 1, each iov entry specifies a strided block of count elements and distance of stride byte between consecutive elements
Examples
uct_hello_world.c.
Data Fields
void * buffer

Data buffer

size_t length

Length of the payload in bytes

uct_mem_h memh

Local memory key descriptor for the data

size_t stride

Stride between beginnings of payload elements in the buffer in bytes

unsigned count

Number of payload elements in the buffer

◆ uct_iface_attr.cap

struct uct_iface_attr.cap
Data Fields
struct uct_iface_attr.cap.put put

Attributes for PUT operations

struct uct_iface_attr.cap.get get

Attributes for GET operations

struct uct_iface_attr.cap.am am

Attributes for AM operations

struct uct_iface_attr.cap.tag tag

Attributes for TAG operations

struct uct_iface_attr.cap.atomic32 atomic32
struct uct_iface_attr.cap.atomic64 atomic64

Attributes for atomic operations

uint64_t flags

Flags from UCT interface operations and capabilities

uint64_t event_flags

Flags from UCT interface for asynchronous event capabilities

◆ uct_iface_attr.cap.put

struct uct_iface_attr.cap.put
Data Fields
size_t max_short

Maximal size for put_short

size_t max_bcopy

Maximal size for put_bcopy

size_t min_zcopy

Minimal size for put_zcopy (total of uct_iov_t::length of the iov parameter)

size_t max_zcopy

Maximal size for put_zcopy (total of uct_iov_t::length of the iov parameter)

size_t opt_zcopy_align

Optimal alignment for zero-copy buffer address

size_t align_mtu

MTU used for alignment

size_t max_iov

Maximal iovcnt parameter in uct_ep_put_zcopy

◆ uct_iface_attr.cap.get

struct uct_iface_attr.cap.get
Data Fields
size_t max_short

Maximal size for get_short

size_t max_bcopy

Maximal size for get_bcopy

size_t min_zcopy

Minimal size for get_zcopy (total of uct_iov_t::length of the iov parameter)

size_t max_zcopy

Maximal size for get_zcopy (total of uct_iov_t::length of the iov parameter)

size_t opt_zcopy_align

Optimal alignment for zero-copy buffer address

size_t align_mtu

MTU used for alignment

size_t max_iov

Maximal iovcnt parameter in uct_ep_get_zcopy

◆ uct_iface_attr.cap.am

struct uct_iface_attr.cap.am
Data Fields
size_t max_short

Total maximum size (incl. the header)

size_t max_bcopy

Total maximum size (incl. the header)

size_t min_zcopy

Minimal size for am_zcopy (incl. the header and total of uct_iov_t::length of the iov parameter)

size_t max_zcopy

Total max. size (incl. the header and total of uct_iov_t::length of the iov parameter)

size_t opt_zcopy_align

Optimal alignment for zero-copy buffer address

size_t align_mtu

MTU used for alignment

size_t max_hdr

Max. header size for zcopy

size_t max_iov

Maximal iovcnt parameter in uct_ep_am_zcopy

◆ uct_iface_attr.cap.tag

struct uct_iface_attr.cap.tag
Data Fields
struct uct_iface_attr.cap.tag.recv recv
struct uct_iface_attr.cap.tag.eager eager

Attributes related to eager protocol

struct uct_iface_attr.cap.tag.rndv rndv

Attributes related to rendezvous protocol

◆ uct_iface_attr.cap.tag.recv

struct uct_iface_attr.cap.tag.recv
Data Fields
size_t min_recv

Minimal allowed length of posted receive buffer

size_t max_zcopy

Maximal allowed data length in uct_iface_tag_recv_zcopy

size_t max_iov

Maximal iovcnt parameter in uct_iface_tag_recv_zcopy

size_t max_outstanding

Maximal number of simultaneous receive operations

◆ uct_iface_attr.cap.tag.eager

struct uct_iface_attr.cap.tag.eager
Data Fields
size_t max_short

Maximal allowed data length in uct_ep_tag_eager_short

size_t max_bcopy

Maximal allowed data length in uct_ep_tag_eager_bcopy

size_t max_zcopy

Maximal allowed data length in uct_ep_tag_eager_zcopy

size_t max_iov

Maximal iovcnt parameter in uct_ep_tag_eager_zcopy

◆ uct_iface_attr.cap.tag.rndv

struct uct_iface_attr.cap.tag.rndv
Data Fields
size_t max_zcopy

Maximal allowed data length in uct_ep_tag_rndv_zcopy

size_t max_hdr

Maximal allowed header length in uct_ep_tag_rndv_zcopy and uct_ep_tag_rndv_request

size_t max_iov

Maximal iovcnt parameter in uct_ep_tag_rndv_zcopy

◆ uct_iface_attr.cap.atomic32

struct uct_iface_attr.cap.atomic32
Data Fields
uint64_t op_flags

Attributes for atomic-post operations

uint64_t fop_flags

Attributes for atomic-fetch operations

◆ uct_iface_attr.cap.atomic64

struct uct_iface_attr.cap.atomic64
Data Fields
uint64_t op_flags

Attributes for atomic-post operations

uint64_t fop_flags

Attributes for atomic-fetch operations

◆ uct_iface_params.mode

union uct_iface_params.mode

Mode-specific parameters

Data Fields
struct uct_iface_params.mode.device device

The fields in this structure (tl_name and dev_name) need to be set only when the UCT_IFACE_OPEN_MODE_DEVICE bit is set in uct_iface_params_t::open_mode This will make uct_iface_open open the interface on the specified device.

struct uct_iface_params.mode.sockaddr sockaddr

These callbacks and address are only relevant for client-server connection establishment with sockaddr and are needed on the server side. The callbacks and address need to be set when the UCT_IFACE_OPEN_MODE_SOCKADDR_SERVER bit is set in uct_iface_params_t::open_mode. This will make uct_iface_open open the interface on the specified address as a server.

◆ uct_iface_params.mode.device

struct uct_iface_params.mode.device

The fields in this structure (tl_name and dev_name) need to be set only when the UCT_IFACE_OPEN_MODE_DEVICE bit is set in uct_iface_params_t::open_mode This will make uct_iface_open open the interface on the specified device.

Data Fields
const char * tl_name

Transport name

const char * dev_name

Device Name

◆ uct_iface_params.mode.sockaddr

struct uct_iface_params.mode.sockaddr

These callbacks and address are only relevant for client-server connection establishment with sockaddr and are needed on the server side. The callbacks and address need to be set when the UCT_IFACE_OPEN_MODE_SOCKADDR_SERVER bit is set in uct_iface_params_t::open_mode. This will make uct_iface_open open the interface on the specified address as a server.

Data Fields
ucs_sock_addr_t listen_sockaddr
void * conn_request_arg

Argument for connection request callback

uct_sockaddr_conn_request_callback_t conn_request_cb

Callback for an incoming connection request on the server

uint32_t cb_flags

Callback flags to indicate where the callback can be invoked from. uct_cb_flags

Typedef Documentation

◆ uct_md_resource_desc_t

This structure describes a memory domain resource.

◆ uct_component_attr_t

This structure defines the attributes for UCT component. It is used for uct_component_query

◆ uct_tl_resource_desc_t

Resource descriptor is an object representing the network resource. Resource descriptor could represent a stand-alone communication resource such as an HCA port, network interface, or multiple resources such as multiple network interfaces or communication ports. It could also represent virtual communication resources that are defined over a single physical network interface.

◆ uct_component_h

typedef struct uct_component* uct_component_h

◆ uct_iface_h

typedef struct uct_iface* uct_iface_h

◆ uct_iface_config_t

typedef struct uct_iface_config uct_iface_config_t

◆ uct_md_config_t

typedef struct uct_md_config uct_md_config_t

◆ uct_cm_config_t

typedef struct uct_cm_config uct_cm_config_t

◆ uct_ep_h

typedef struct uct_ep* uct_ep_h

◆ uct_mem_h

typedef void* uct_mem_h

◆ uct_rkey_t

typedef uintptr_t uct_rkey_t

◆ uct_md_h

typedef struct uct_md* uct_md_h

◆ uct_md_ops_t

typedef struct uct_md_ops uct_md_ops_t

◆ uct_rkey_ctx_h

typedef void* uct_rkey_ctx_h

◆ uct_iface_attr_t

◆ uct_iface_params_t

◆ uct_ep_attr_t

typedef struct uct_ep_attr uct_ep_attr_t

◆ uct_md_attr_t

typedef struct uct_md_attr uct_md_attr_t

◆ uct_completion_t

◆ uct_pending_req_t

◆ uct_worker_h

typedef struct uct_worker* uct_worker_h

◆ uct_md_t

typedef struct uct_md uct_md_t

◆ uct_am_trace_type_t

◆ uct_device_addr_t

typedef struct uct_device_addr uct_device_addr_t

◆ uct_iface_addr_t

typedef struct uct_iface_addr uct_iface_addr_t

◆ uct_ep_addr_t

typedef struct uct_ep_addr uct_ep_addr_t

◆ uct_ep_params_t

◆ uct_ep_connect_params_t

◆ uct_cm_attr_t

typedef struct uct_cm_attr uct_cm_attr_t

◆ uct_cm_t

typedef struct uct_cm uct_cm_t

◆ uct_cm_h

typedef uct_cm_t* uct_cm_h

◆ uct_listener_attr_t

◆ uct_listener_h

typedef struct uct_listener* uct_listener_h

◆ uct_listener_params_t

◆ uct_tag_context_t

◆ uct_tag_t

typedef uint64_t uct_tag_t

◆ uct_worker_cb_id_t

typedef int uct_worker_cb_id_t

◆ uct_conn_request_h

typedef void* uct_conn_request_h

◆ uct_iov_t

typedef struct uct_iov uct_iov_t

Specifies a list of buffers which can be used within a single data transfer function call.

 buffer
 |
 +-----------+-------+-----------+-------+-----------+
 |  payload  | empty |  payload  | empty |  payload  |
 +-----------+-------+-----------+-------+-----------+
 |<-length-->|       |<-length-->|       |<-length-->|
 |<---- stride ----->|<---- stride ----->|
Note
The sum of lengths in all iov list must be less or equal to max_zcopy of the respective communication operation.
If length or count are zero, the memory pointed to by buffer will not be accessed. Otherwise, buffer must point to valid memory.
If count is one, every iov entry specifies a single contiguous data block
If count > 1, each iov entry specifies a strided block of count elements and distance of stride byte between consecutive elements

◆ uct_completion_callback_t

typedef void(* uct_completion_callback_t) (uct_completion_t *self)
Parameters
[in]selfPointer to relevant completion structure, which was initially passed to the operation.

◆ uct_pending_callback_t

typedef ucs_status_t(* uct_pending_callback_t) (uct_pending_req_t *self)
Parameters
[in]selfPointer to relevant pending structure, which was initially passed to the operation.
Returns
UCS_OK - This pending request has completed and should be removed. UCS_INPROGRESS - Some progress was made, but not completed. Keep this request and keep processing the queue. Otherwise - Could not make any progress. Keep this pending request on the queue, and stop processing the queue.

◆ uct_error_handler_t

typedef ucs_status_t(* uct_error_handler_t) (void *arg, uct_ep_h ep, ucs_status_t status)
Note
User should purge a pending queue and do not post any TX operations and cancel all possible outstanding operations prior closing a UCT endpoint.
Parameters
[in]argUser argument to be passed to the callback.
[in]epEndpoint which has failed. Upon return from the callback, this ep is no longer usable and all subsequent operations on this ep will fail with the error code passed in status.
[in]statusStatus indicating error.
Returns
UCS_OK - The error was handled successfully. Otherwise - The error was not handled and is returned back to the transport.

◆ uct_pending_purge_callback_t

typedef void(* uct_pending_purge_callback_t) (uct_pending_req_t *self, void *arg)
Parameters
[in]selfPointer to relevant pending structure, which was initially passed to the operation.
[in]argUser argument to be passed to the callback.

◆ uct_pack_callback_t

typedef size_t(* uct_pack_callback_t) (void *dest, void *arg)
Parameters
[in]destMemory buffer to pack the data to.
[in]argCustom user-argument.
Returns
Size of the data was actually produced.

◆ uct_unpack_callback_t

typedef void(* uct_unpack_callback_t) (void *arg, const void *data, size_t length)
Parameters
[in]argCustom user-argument.
[in]dataMemory buffer to unpack the data from.
[in]lengthHow much data to consume (size of "data")
Note
The arguments for this callback are in the same order as libc's memcpy().

◆ uct_async_event_cb_t

typedef void(* uct_async_event_cb_t) (void *arg, unsigned flags)
Parameters
[in]argUser argument to be passed to the callback.
[in]flagsFlags to be passed to the callback (reserved for future use).

Enumeration Type Documentation

◆ uct_component_attr_field

The enumeration allows specifying which fields in uct_component_attr_t are present. It is used for backward compatibility support.

Enumerator
UCT_COMPONENT_ATTR_FIELD_NAME 

Component name

UCT_COMPONENT_ATTR_FIELD_MD_RESOURCE_COUNT 

MD resource count

UCT_COMPONENT_ATTR_FIELD_MD_RESOURCES 

MD resources array

UCT_COMPONENT_ATTR_FIELD_FLAGS 

Capability flags

◆ anonymous enum

anonymous enum

The enumeration defines bit mask of uct_component_h capabilities in uct_component_attr_t::flags which is set by uct_component_query.

Enumerator
UCT_COMPONENT_FLAG_CM 

If set, the component supports uct_cm_h functionality. See uct_cm_open for details.

UCT_COMPONENT_FLAG_RKEY_PTR 

If set, the component supports direct access to remote memory using a local pointer returned from uct_rkey_ptr function.

◆ uct_device_type_t

Enumerator
UCT_DEVICE_TYPE_NET 

Network devices

UCT_DEVICE_TYPE_SHM 

Shared memory devices

UCT_DEVICE_TYPE_ACC 

Acceleration devices

UCT_DEVICE_TYPE_SELF 

Loop-back device

UCT_DEVICE_TYPE_LAST 

◆ uct_iface_event_types

Note
The UCT_EVENT_RECV and UCT_EVENT_RECV_SIG event types are used to indicate receive-side completions for both tag matching and active messages. If the interface supports signaled receives (UCT_IFACE_FLAG_EVENT_RECV_SIG), then for the messages sent with UCT_SEND_FLAG_SIGNALED flag, UCT_EVENT_RECV_SIG should be triggered on the receiver. Otherwise, UCT_EVENT_RECV should be triggered.
Enumerator
UCT_EVENT_SEND_COMP 

Send completion event

UCT_EVENT_RECV 

Tag or active message received

UCT_EVENT_RECV_SIG 

Signaled tag or active message received

◆ uct_flush_flags

Enumerator
UCT_FLUSH_FLAG_LOCAL 

Guarantees that the data transfer is completed but the target buffer may not be updated yet.

UCT_FLUSH_FLAG_CANCEL 

The library will make a best effort attempt to cancel all uncompleted operations. However, there is a chance that some operations will not be canceled in which case the user will need to handle their completions through the relevant callbacks. After uct_ep_flush with this flag is completed, the endpoint will be set to error state, and it becomes unusable for send operations and should be destroyed.

UCT_FLUSH_FLAG_REMOTE 

Guarantees that all previous UCP memory update operations (put, atomics, etc.) are completed, the target memory of these operation was updated, and the updated memory is globally visible for all processing elements in the system.

◆ uct_progress_types

Enumerator
UCT_PROGRESS_SEND 

Progress send operations

UCT_PROGRESS_RECV 

Progress receive operations

UCT_PROGRESS_THREAD_SAFE 

Enable/disable progress while another thread may be calling ucp_worker_progress().

◆ uct_cb_flags

List of flags for a callback.

Enumerator
UCT_CB_FLAG_RESERVED 

Reserved for future use.

UCT_CB_FLAG_ASYNC 

Callback is allowed to be called from any thread in the process, and therefore should be thread-safe. For example, it may be called from a transport async progress thread. To guarantee async invocation, the interface must have the UCT_IFACE_FLAG_CB_ASYNC flag set. If async callback is requested on an interface which only supports sync callback (i.e., only the UCT_IFACE_FLAG_CB_SYNC flag is set), the callback will be invoked only from the context that called uct_iface_progress).

◆ uct_iface_open_mode

Enumerator
UCT_IFACE_OPEN_MODE_DEVICE 

Interface is opened on a specific device

UCT_IFACE_OPEN_MODE_SOCKADDR_SERVER 

Interface is opened on a specific address on the server side. This mode will be deprecated in the near future for a better API.

UCT_IFACE_OPEN_MODE_SOCKADDR_CLIENT 

Interface is opened on a specific address on the client side This mode will be deprecated in the near future for a better API.

◆ uct_iface_params_field

The enumeration allows specifying which fields in uct_iface_params_t are present, for backward compatibility support.

Enumerator
UCT_IFACE_PARAM_FIELD_CPU_MASK 

Enables uct_iface_params_t::cpu_mask

UCT_IFACE_PARAM_FIELD_OPEN_MODE 

Enables uct_iface_params_t::open_mode

UCT_IFACE_PARAM_FIELD_DEVICE 

Enables uct_iface_params_t::mode::device

UCT_IFACE_PARAM_FIELD_SOCKADDR 

Enables uct_iface_params_t::mode::sockaddr

UCT_IFACE_PARAM_FIELD_STATS_ROOT 

Enables uct_iface_params_t::stats_root

UCT_IFACE_PARAM_FIELD_RX_HEADROOM 

Enables uct_iface_params_t::rx_headroom

UCT_IFACE_PARAM_FIELD_ERR_HANDLER_ARG 

Enables uct_iface_params_t::err_handler_arg

UCT_IFACE_PARAM_FIELD_ERR_HANDLER 

Enables uct_iface_params_t::err_handler

UCT_IFACE_PARAM_FIELD_ERR_HANDLER_FLAGS 

Enables uct_iface_params_t::err_handler_flags

UCT_IFACE_PARAM_FIELD_HW_TM_EAGER_ARG 

Enables uct_iface_params_t::eager_arg

UCT_IFACE_PARAM_FIELD_HW_TM_EAGER_CB 

Enables uct_iface_params_t::eager_cb

UCT_IFACE_PARAM_FIELD_HW_TM_RNDV_ARG 

Enables uct_iface_params_t::rndv_arg

UCT_IFACE_PARAM_FIELD_HW_TM_RNDV_CB 

Enables uct_iface_params_t::rndv_cb

UCT_IFACE_PARAM_FIELD_ASYNC_EVENT_ARG 

Enables uct_iface_params_t::async_event_arg

UCT_IFACE_PARAM_FIELD_ASYNC_EVENT_CB 

Enables uct_iface_params_t::async_event_cb

UCT_IFACE_PARAM_FIELD_KEEPALIVE_INTERVAL 

Enables uct_iface_params_t::keepalive_interval

UCT_IFACE_PARAM_FIELD_AM_ALIGNMENT 

Enables uct_iface_params_t::am_alignment

UCT_IFACE_PARAM_FIELD_AM_ALIGN_OFFSET 

Enables uct_iface_params_t::am_align_offset

UCT_IFACE_PARAM_FIELD_FEATURES 

Enables uct_iface_params_t::features

◆ uct_ep_params_field

The enumeration allows specifying which fields in uct_ep_params_t are present, for backward compatibility support.

Enumerator
UCT_EP_PARAM_FIELD_IFACE 

Enables uct_ep_params::iface

UCT_EP_PARAM_FIELD_USER_DATA 

Enables uct_ep_params::user_data

UCT_EP_PARAM_FIELD_DEV_ADDR 

Enables uct_ep_params::dev_addr

UCT_EP_PARAM_FIELD_IFACE_ADDR 

Enables uct_ep_params::iface_addr

UCT_EP_PARAM_FIELD_SOCKADDR 

Enables uct_ep_params::sockaddr

UCT_EP_PARAM_FIELD_SOCKADDR_CB_FLAGS 

Enables uct_ep_params::sockaddr_cb_flags

UCT_EP_PARAM_FIELD_SOCKADDR_PACK_CB 

Enables uct_ep_params::sockaddr_pack_cb

UCT_EP_PARAM_FIELD_CM 

Enables uct_ep_params::cm

UCT_EP_PARAM_FIELD_CONN_REQUEST 

Enables uct_ep_params::conn_request

UCT_EP_PARAM_FIELD_SOCKADDR_CONNECT_CB_CLIENT 

Enables uct_ep_params::sockaddr_cb_client

UCT_EP_PARAM_FIELD_SOCKADDR_NOTIFY_CB_SERVER 

Enables uct_ep_params::sockaddr_cb_server

UCT_EP_PARAM_FIELD_SOCKADDR_DISCONNECT_CB 

Enables uct_ep_params::disconnect_cb

UCT_EP_PARAM_FIELD_PATH_INDEX 

Enables uct_ep_params::path_index

UCT_EP_PARAM_FIELD_CM_RESOLVE_CB 

Enables uct_ep_params::cm_resolve_cb

UCT_EP_PARAM_FIELD_PRIV_DATA 

Enables uct_ep_params::private_data

UCT_EP_PARAM_FIELD_PRIV_DATA_LENGTH 

Enables uct_ep_params::private_data_length

UCT_EP_PARAM_FIELD_LOCAL_SOCKADDR 

Enables uct_ep_params::local_sockaddr

◆ uct_iface_feature

The enumeration list describes the features supported by UCT. An application can request the features using UCT parameters during UCT iface initialization process.

Enumerator
UCT_IFACE_FEATURE_AM 

Request Active Message support

UCT_IFACE_FEATURE_PUT 

Request PUT support

UCT_IFACE_FEATURE_GET 

Request GET support

UCT_IFACE_FEATURE_AMO32 

Request 32-bit atomic operations support

UCT_IFACE_FEATURE_AMO64 

Request 64-bit atomic operations support

UCT_IFACE_FEATURE_TAG 

Request tag matching offload support

UCT_IFACE_FEATURE_FLUSH_REMOTE 

Request remote flush support

UCT_IFACE_FEATURE_LAST 

Used to determine the number of features

◆ anonymous enum

anonymous enum
Enumerator
UCT_TAG_RECV_CB_INLINE_DATA 

◆ uct_cb_param_flags

If UCT_CB_PARAM_FLAG_DESC flag is enabled, then data is part of a descriptor which includes the user-defined rx_headroom, and the callback may return UCS_INPROGRESS and hold on to that descriptor. Otherwise, the data can't be used outside the callback. If needed, the data must be copied-out.

 descriptor    data
 |             |
 +-------------+-------------------------+
 | rx_headroom | payload                 |
 +-------------+-------------------------+

UCT_CB_PARAM_FLAG_FIRST and UCT_CB_PARAM_FLAG_MORE flags are relevant for uct_tag_unexp_eager_cb_t callback only. The former value indicates that the data is the first fragment of the message. The latter value means that more fragments of the message yet to be delivered.

Enumerator
UCT_CB_PARAM_FLAG_DESC 
UCT_CB_PARAM_FLAG_FIRST 
UCT_CB_PARAM_FLAG_MORE 

Function Documentation

◆ uct_query_components()

ucs_status_t uct_query_components ( uct_component_h ** components_p,
unsigned * num_components_p )

Obtain the list of transport components available on the current system.

Parameters
[out]components_pFilled with a pointer to an array of component handles.
[out]num_components_pFilled with the number of elements in the array.
Returns
UCS_OK if successful, or UCS_ERR_NO_MEMORY if failed to allocate the array of component handles.
Examples
uct_hello_world.c.

◆ uct_release_component_list()

void uct_release_component_list ( uct_component_h * components)

This routine releases the memory associated with the list of components allocated by uct_query_components.

Parameters
[in]componentsArray of component handles to release.
Examples
uct_hello_world.c.

◆ uct_component_query()

ucs_status_t uct_component_query ( uct_component_h component,
uct_component_attr_t * component_attr )

Query various attributes of a component.

Parameters
[in]componentComponent handle to query attributes for. The handle can be obtained from uct_query_components.
[in,out]component_attrFilled with component attributes.
Returns
UCS_OK if successful, or nonzero error code in case of failure.
Examples
uct_hello_world.c.

◆ uct_md_open()

ucs_status_t uct_md_open ( uct_component_h component,
const char * md_name,
const uct_md_config_t * config,
uct_md_h * md_p )

Open a specific memory domain. All communications and memory operations are performed in the context of a specific memory domain. Therefore it must be created before communication resources.

Parameters
[in]componentComponent on which to open the memory domain, as returned from uct_query_components.
[in]md_nameMemory domain name, as returned from uct_component_query.
[in]configMD configuration options. Should be obtained from uct_md_config_read() function, or point to MD-specific structure which extends uct_md_config_t.
[out]md_pFilled with a handle to the memory domain.
Returns
Error code.
Examples
uct_hello_world.c.

◆ uct_md_close()

void uct_md_close ( uct_md_h md)
Parameters
[in]mdMemory domain to close.
Examples
uct_hello_world.c.

◆ uct_md_query_tl_resources()

ucs_status_t uct_md_query_tl_resources ( uct_md_h md,
uct_tl_resource_desc_t ** resources_p,
unsigned * num_resources_p )

This routine queries the memory domain for communication resources that are available for it.

Parameters
[in]mdHandle to memory domain.
[out]resources_pFilled with a pointer to an array of resource descriptors.
[out]num_resources_pFilled with the number of resources in the array.
Returns
Error code.
Examples
uct_hello_world.c.

◆ uct_release_tl_resource_list()

void uct_release_tl_resource_list ( uct_tl_resource_desc_t * resources)

This routine releases the memory associated with the list of resources allocated by uct_md_query_tl_resources.

Parameters
[in]resourcesArray of resource descriptors to release.
Examples
uct_hello_world.c.

◆ uct_md_iface_config_read()

ucs_status_t uct_md_iface_config_read ( uct_md_h md,
const char * tl_name,
const char * env_prefix,
const char * filename,
uct_iface_config_t ** config_p )
Parameters
[in]mdMemory domain on which the transport's interface was registered.
[in]tl_nameTransport name. If md supports UCT_MD_FLAG_SOCKADDR, the transport name is allowed to be NULL. In this case, the configuration returned from this routine should be passed to uct_iface_open with UCT_IFACE_OPEN_MODE_SOCKADDR_SERVER or UCT_IFACE_OPEN_MODE_SOCKADDR_CLIENT set in uct_iface_params_t::open_mode. In addition, if tl_name is not NULL, the configuration returned from this routine should be passed to uct_iface_open with UCT_IFACE_OPEN_MODE_DEVICE set in uct_iface_params_t::open_mode.
[in]env_prefixIf non-NULL, search for environment variables starting with this UCT_<prefix>_. Otherwise, search for environment variables starting with just UCT_.
[in]filenameIf non-NULL, read configuration from this file. If the file does not exist, it will be ignored.
[out]config_pFilled with a pointer to configuration.
Returns
Error code.
Examples
uct_hello_world.c.

◆ uct_config_release()

void uct_config_release ( void * config)
Parameters
[in]configConfiguration to release.
Examples
uct_hello_world.c.

◆ uct_iface_open()

ucs_status_t uct_iface_open ( uct_md_h md,
uct_worker_h worker,
const uct_iface_params_t * params,
const uct_iface_config_t * config,
uct_iface_h * iface_p )
Parameters
[in]mdMemory domain to create the interface on.
[in]workerHandle to worker which will be used to progress communications on this interface.
[in]paramsUser defined uct_iface_params_t parameters.
[in]configInterface configuration options. Should be obtained from uct_md_iface_config_read() function, or point to transport-specific structure which extends uct_iface_config_t.
[out]iface_pFilled with a handle to opened communication interface.
Returns
Error code.
Examples
uct_hello_world.c.

◆ uct_iface_close()

void uct_iface_close ( uct_iface_h iface)
Parameters
[in]ifaceInterface to close.
Examples
uct_hello_world.c.

◆ uct_iface_query()

ucs_status_t uct_iface_query ( uct_iface_h iface,
uct_iface_attr_t * iface_attr )
Parameters
[in]ifaceInterface to query.
[out]iface_attrFilled with interface attributes.
Examples
uct_hello_world.c.

◆ uct_iface_get_device_address()

ucs_status_t uct_iface_get_device_address ( uct_iface_h iface,
uct_device_addr_t * addr )

Get underlying device address of the interface. All interfaces using the same device would return the same address.

Parameters
[in]ifaceInterface to query.
[out]addrFilled with device address. The size of the buffer provided must be at least uct_iface_attr_t::device_addr_len.
Examples
uct_hello_world.c.

◆ uct_iface_get_address()

ucs_status_t uct_iface_get_address ( uct_iface_h iface,
uct_iface_addr_t * addr )

requires UCT_IFACE_FLAG_CONNECT_TO_IFACE.

Parameters
[in]ifaceInterface to query.
[out]addrFilled with interface address. The size of the buffer provided must be at least uct_iface_attr_t::iface_addr_len.
Examples
uct_hello_world.c.

◆ uct_iface_is_reachable()

int uct_iface_is_reachable ( const uct_iface_h iface,
const uct_device_addr_t * dev_addr,
const uct_iface_addr_t * iface_addr )

This function checks if a remote address can be reached from a local interface. If the function returns true, it does not necessarily mean a connection and/or data transfer would succeed, since the reachability check is a local operation it does not detect issues such as network mis-configuration or lack of connectivity.

Parameters
[in]ifaceInterface to check reachability from.
[in]dev_addrDevice address to check reachability to. It is NULL if iface_attr.dev_addr_len == 0, and must be non-NULL otherwise.
[in]iface_addrInterface address to check reachability to. It is NULL if iface_attr.iface_addr_len == 0, and must be non-NULL otherwise.
Returns
Nonzero if reachable, 0 if not.
Examples
uct_hello_world.c.

◆ uct_ep_check()

ucs_status_t uct_ep_check ( const uct_ep_h ep,
unsigned flags,
uct_completion_t * comp )

This function checks if the destination endpoint is alive with respect to the UCT library. If the status of ep is known, either UCS_OK or an error is returned immediately. Otherwise, UCS_INPROGRESS is returned, indicating that synchronization on the status is needed. In this case, the status will be be propagated by comp callback.

Parameters
[in]epEndpoint to check
[in]flagsFlags that define level of check (currently unsupported - set to 0).
[in]compHandler to process status of ep
Returns
Error code.

◆ uct_iface_event_fd_get()

ucs_status_t uct_iface_event_fd_get ( uct_iface_h iface,
int * fd_p )

Only interfaces that support at least one of the UCT_IFACE_FLAG_EVENT* flags will implement this function.

Parameters
[in]ifaceInterface to get the notification descriptor.
[out]fd_pLocation to write the notification file descriptor.
Returns
Error code.

◆ uct_iface_event_arm()

ucs_status_t uct_iface_event_arm ( uct_iface_h iface,
unsigned events )

This routine needs to be called before waiting on each notification on this interface, so will typically be called once the processing of the previous event is over.

Parameters
[in]ifaceInterface to arm.
[in]eventsEvents to wakeup on. See uct_iface_event_types
Returns
UCS_OK The operation completed successfully. File descriptor will be signaled by new events.
UCS_ERR_BUSY There are unprocessed events which prevent the file descriptor from being armed. The operation is not completed. File descriptor will not be signaled by new events.
Other different error codes in case of issues.

◆ uct_iface_mem_alloc()

ucs_status_t uct_iface_mem_alloc ( uct_iface_h iface,
size_t length,
unsigned flags,
const char * name,
uct_allocated_memory_t * mem )

Allocate a region of memory which can be used for zero-copy data transfer or remote access on a particular transport interface.

Parameters
[in]ifaceInterface to allocate memory on.
[in]lengthSize of memory region to allocate.
[in]flagsMemory allocation flags, see uct_md_mem_flags.
[in]nameAllocation name, for debug purposes.
[out]memDescriptor of allocated memory.
Returns
UCS_OK if allocation was successful, error code otherwise.

◆ uct_iface_mem_free()

void uct_iface_mem_free ( const uct_allocated_memory_t * mem)
Parameters
[in]memDescriptor of memory to release.

◆ uct_ep_create()

ucs_status_t uct_ep_create ( const uct_ep_params_t * params,
uct_ep_h * ep_p )

Create a UCT endpoint in one of the available modes:

  1. Unconnected endpoint: If no any address is present in uct_ep_params, this creates an unconnected endpoint. To establish a connection to a remote endpoint, uct_ep_connect_to_ep will need to be called. Use of this mode requires uct_ep_params_t::iface has the UCT_IFACE_FLAG_CONNECT_TO_EP capability flag. It may be obtained by uct_iface_query .
  2. Connect to a remote interface: If uct_ep_params_t::dev_addr and uct_ep_params_t::iface_addr are set, this will establish an endpoint that is connected to a remote interface. This requires that uct_ep_params_t::iface has the UCT_IFACE_FLAG_CONNECT_TO_IFACE capability flag. It may be obtained by uct_iface_query.
  3. Connect to a remote socket address: If uct_ep_params_t::sockaddr is set, this will create an endpoint that is connected to a remote socket. This requires that either uct_ep_params::cm, or uct_ep_params::iface will be set. In the latter case, the interface has to support UCT_IFACE_FLAG_CONNECT_TO_SOCKADDR flag, which can be checked by calling uct_iface_query.
    Parameters
    [in]paramsUser defined uct_ep_params_t configuration for the ep_p.
    [out]ep_pFilled with handle to the new endpoint.
    Returns
    UCS_OK The endpoint is created successfully. This does not guarantee that the endpoint has been connected to the destination defined in params; in case of failure, the error will be reported to the interface error handler callback provided to uct_iface_open via uct_iface_params_t::err_handler.
    Error code as defined by ucs_status_t
Examples
uct_hello_world.c.

◆ uct_ep_destroy()

void uct_ep_destroy ( uct_ep_h ep)
Parameters
[in]epEndpoint to destroy.
Examples
uct_hello_world.c.

◆ uct_ep_get_address()

ucs_status_t uct_ep_get_address ( uct_ep_h ep,
uct_ep_addr_t * addr )
Parameters
[in]epEndpoint to query.
[out]addrFilled with endpoint address. The size of the buffer provided must be at least uct_iface_attr_t::ep_addr_len.
Examples
uct_hello_world.c.

◆ uct_ep_connect_to_ep()

ucs_status_t uct_ep_connect_to_ep ( uct_ep_h ep,
const uct_device_addr_t * dev_addr,
const uct_ep_addr_t * ep_addr )

requires UCT_IFACE_FLAG_CONNECT_TO_EP capability.

Parameters
[in]epEndpoint to connect.
[in]dev_addrRemote device address.
[in]ep_addrRemote endpoint address.
Examples
uct_hello_world.c.

◆ uct_iface_flush()

ucs_status_t uct_iface_flush ( uct_iface_h iface,
unsigned flags,
uct_completion_t * comp )

Flushes all outstanding communications issued on the interface prior to this call. The operations are completed at the origin or at the target as well. The exact completion semantic depends on flags parameter.

Note
Currently only one completion type is supported. It guarantees that the data transfer is completed but the target buffer may not be updated yet.
Parameters
[in]ifaceInterface to flush communications from.
[in]flagsFlags that control completion semantic (currently only UCT_FLUSH_FLAG_LOCAL is supported).
[in,out]compCompletion handle as defined by uct_completion_t. Can be NULL, which means that the call will return the current state of the interface and no completion will be generated in case of outstanding communications. If it is not NULL completion counter is decremented by 1 when the call completes. Completion callback is called when the counter reaches 0.
Returns
UCS_OK - No outstanding communications left. UCS_INPROGRESS - Some communication operations are still in progress. If non-NULL 'comp' is provided, it will be updated upon completion of these operations.

◆ uct_iface_fence()

ucs_status_t uct_iface_fence ( uct_iface_h iface,
unsigned flags )
Parameters
[in]ifaceInterface to issue communications from.
[in]flagsFlags that control ordering semantic (currently unsupported - set to 0).
Returns
UCS_OK - Ordering is inserted.

◆ uct_ep_pending_add()

ucs_status_t uct_ep_pending_add ( uct_ep_h ep,
uct_pending_req_t * req,
unsigned flags )

Add a pending request to the endpoint pending queue. The request will be dispatched when the endpoint could potentially have additional send resources.

Parameters
[in]epEndpoint to add the pending request to.
[in]reqPending request, which would be dispatched when more resources become available. The user is expected to initialize the "func" field. After being passed to the function, the request is owned by UCT, until the callback is called and returns UCS_OK.
[in]flagsFlags that control pending request processing (see uct_cb_flags)
Returns
UCS_OK - request added to pending queue UCS_ERR_BUSY - request was not added to pending queue, because send resources are available now. The user is advised to retry.

◆ uct_ep_pending_purge()

void uct_ep_pending_purge ( uct_ep_h ep,
uct_pending_purge_callback_t cb,
void * arg )

Remove pending requests from the given endpoint and pass them to the provided callback function. The callback return value is ignored.

Parameters
[in]epEndpoint to remove pending requests from.
[in]cbCallback to pass the removed requests to.
[in]argArgument to pass to the cb callback.

◆ uct_ep_flush()

ucs_status_t uct_ep_flush ( uct_ep_h ep,
unsigned flags,
uct_completion_t * comp )

Flushes all outstanding communications issued on the endpoint prior to this call. The operations are completed at the origin or at the target as well. The exact completion semantic depends on flags parameter.

Parameters
[in]epEndpoint to flush communications from.
[in]flagsFlags uct_flush_flags that control completion semantic.
[in,out]compCompletion handle as defined by uct_completion_t. Can be NULL, which means that the call will return the current state of the endpoint and no completion will be generated in case of outstanding communications. If it is not NULL completion counter is decremented by 1 when the call completes. Completion callback is called when the counter reaches 0.
Returns
UCS_OK - No outstanding communications left. UCS_ERR_NO_RESOURCE - Flush operation could not be initiated. A subsequent call to uct_ep_pending_add would add a pending operation, which provides an opportunity to retry the flush. UCS_INPROGRESS - Some communication operations are still in progress. If non-NULL 'comp' is provided, it will be updated upon completion of these operations.

◆ uct_ep_fence()

ucs_status_t uct_ep_fence ( uct_ep_h ep,
unsigned flags )
Parameters
[in]epEndpoint to issue communications from.
[in]flagsFlags that control ordering semantic (currently unsupported - set to 0).
Returns
UCS_OK - Ordering is inserted.

◆ uct_iface_progress_enable()

void uct_iface_progress_enable ( uct_iface_h iface,
unsigned flags )

Notify the transport that it should actively progress communications during uct_worker_progress().

When the interface is created, its progress is initially disabled.

Parameters
[in]ifaceThe interface to enable progress.
[in]flagsThe type of progress to enable as defined by uct_progress_types
Note
This function is not thread safe with respect to ucp_worker_progress(), unless the flag UCT_PROGRESS_THREAD_SAFE is specified.
Examples
uct_hello_world.c.

◆ uct_iface_progress_disable()

void uct_iface_progress_disable ( uct_iface_h iface,
unsigned flags )

Notify the transport that it should not progress its communications during uct_worker_progress(). Thus the latency of other transports may be improved.

By default, progress is disabled when the interface is created.

Parameters
[in]ifaceThe interface to disable progress.
[in]flagsThe type of progress to disable as defined by uct_progress_types.
Note
This function is not thread safe with respect to ucp_worker_progress(), unless the flag UCT_PROGRESS_THREAD_SAFE is specified.

◆ uct_iface_progress()

unsigned uct_iface_progress ( uct_iface_h iface)

◆ uct_completion_update_status()

static UCS_F_ALWAYS_INLINE void uct_completion_update_status ( uct_completion_t * comp,
ucs_status_t status )
static
Parameters
comp[in] Completion handle to update.
status[in] Status to update comp handle.