Modules
	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_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

struct	uct_iface_params
	Parameters used for interface creation. More...

union	uct_iface_params.mode

struct	uct_iface_params.mode.device

struct	uct_iface_params.mode.sockaddr

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

Typedefs
typedef struct uct_md_resource_desc	uct_md_resource_desc_t
	Memory domain resource descriptor. More...

typedef struct uct_component_attr	uct_component_attr_t
	UCT component attributes. More...

typedef struct uct_tl_resource_desc	uct_tl_resource_desc_t
	Communication resource descriptor. More...

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

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_t *	uct_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. More...

typedef void(*	uct_completion_callback_t) (uct_completion_t *self)
	Callback to process send completion. More...

typedef ucs_status_t(*	uct_pending_callback_t) (uct_pending_req_t *self)
	Callback to process pending requests. More...

typedef ucs_status_t(*	uct_error_handler_t) (void *arg, uct_ep_h ep, ucs_status_t status)
	Callback to process peer failure. More...

typedef void(*	uct_pending_purge_callback_t) (uct_pending_req_t self, void arg)
	Callback to purge pending requests. More...

typedef size_t(*	uct_pack_callback_t) (void dest, void arg)
	Callback for producing data. More...

typedef void(*	uct_unpack_callback_t) (void arg, const void data, size_t length)
	Callback for consuming data. More...

typedef void(*	uct_async_event_cb_t) (void *arg, unsigned flags)
	Callback to process asynchronous events. More...

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

void	uct_release_component_list (uct_component_h *components)
	Release the list of components returned from uct_query_components. More...

ucs_status_t	uct_component_query (uct_component_h component, uct_component_attr_t *component_attr)
	Get component attributes. More...

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

void	uct_md_close (uct_md_h md)
	Close a memory domain. More...

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

void	uct_release_tl_resource_list (uct_tl_resource_desc_t *resources)
	Release the list of resources returned from uct_md_query_tl_resources. More...

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

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(). More...

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

void	uct_iface_close (uct_iface_h iface)
	Close and destroy an interface. More...

ucs_status_t	uct_iface_query (uct_iface_h iface, uct_iface_attr_t *iface_attr)
	Get interface attributes. More...

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

ucs_status_t	uct_iface_get_address (uct_iface_h iface, uct_iface_addr_t *addr)
	Get interface address. More...

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

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

ucs_status_t	uct_iface_event_fd_get (uct_iface_h iface, int *fd_p)
	Obtain a notification file descriptor for polling. More...

ucs_status_t	uct_iface_event_arm (uct_iface_h iface, unsigned events)
	Turn on event notification for the next event. More...

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

void	uct_iface_mem_free (const uct_allocated_memory_t *mem)
	Release memory allocated with uct_iface_mem_alloc(). More...

ucs_status_t	uct_ep_create (const uct_ep_params_t params, uct_ep_h ep_p)
	Create new endpoint. More...

void	uct_ep_destroy (uct_ep_h ep)
	Destroy an endpoint. More...

ucs_status_t	uct_ep_get_address (uct_ep_h ep, uct_ep_addr_t *addr)
	Get endpoint address. More...

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

ucs_status_t	uct_iface_flush (uct_iface_h iface, unsigned flags, uct_completion_t *comp)
	Flush outstanding communication operations on an interface. More...

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

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

void	uct_ep_pending_purge (uct_ep_h ep, uct_pending_purge_callback_t cb, void *arg)
	Remove all pending requests from an endpoint. More...

ucs_status_t	uct_ep_flush (uct_ep_h ep, unsigned flags, uct_completion_t *comp)
	Flush outstanding communication operations on an endpoint. More...

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

void	uct_iface_progress_enable (uct_iface_h iface, unsigned flags)
	Enable synchronous progress for the interface. More...

void	uct_iface_progress_disable (uct_iface_h iface, unsigned flags)
	Disable synchronous progress for the interface. More...

unsigned	uct_iface_progress (uct_iface_h iface)
	Perform a progress on an interface. More...

static UCS_F_ALWAYS_INLINE void	uct_completion_update_status (uct_completion_t *comp, ucs_status_t status)
	Update status of UCT completion handle. More...

Detailed Description

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

Data Structure Documentation

struct uct_md_resource_desc

This structure describes a memory domain resource.

Data Fields
char	md_name[UCT_MD_NAME_MAX]	Memory domain name

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.

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

struct uct_iface_attr

Examples:: uct_hello_world.c.

Data Fields
struct uct_iface_attr	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.

struct uct_iface_attr.cap

Data Fields
cap	put	Attributes for PUT operations
cap	get	Attributes for GET operations
cap	am	Attributes for AM operations
cap	tag	Attributes for TAG operations
cap	atomic32
cap	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

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

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

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

struct uct_iface_attr.cap.tag

Data Fields
tag	recv
tag	eager	Attributes related to eager protocol
tag	rndv	Attributes related to rendezvous protocol

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

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

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

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

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

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

union uct_iface_params.mode

Mode-specific parameters

Data Fields
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.
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.

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

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

struct uct_ep_params

Examples:: uct_hello_world.c.

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.

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.

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

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

Typedef Documentation

typedef struct uct_md_resource_desc uct_md_resource_desc_t

This structure describes a memory domain resource.

typedef struct uct_component_attr uct_component_attr_t

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

typedef struct uct_tl_resource_desc 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.

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

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_t* uct_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

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

typedef void(* uct_completion_callback_t) (uct_completion_t *self)

Parameters

[in] self Pointer to relevant completion structure, which was initially passed to the operation.

typedef ucs_status_t(* uct_pending_callback_t) (uct_pending_req_t *self)

Parameters

[in] self Pointer 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.

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]	arg	User argument to be passed to the callback.
[in]	ep	Endpoint 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]	status	Status indicating error.

Returns: UCS_OK - The error was handled successfully. Otherwise - The error was not handled and is returned back to the transport.

typedef void(* uct_pending_purge_callback_t) (uct_pending_req_t *self, void *arg)

Parameters

[in]	self	Pointer to relevant pending structure, which was initially passed to the operation.
[in]	arg	User argument to be passed to the callback.

typedef size_t(* uct_pack_callback_t) (void *dest, void *arg)

Parameters

[in]	dest	Memory buffer to pack the data to.
[in]	arg	Custom user-argument.

Returns: Size of the data was actually produced.

typedef void(* uct_unpack_callback_t) (void *arg, const void *data, size_t length)

Parameters

[in]	arg	Custom user-argument.
[in]	data	Memory buffer to unpack the data from.
[in]	length	How much data to consume (size of "data")

Note: The arguments for this callback are in the same order as libc's memcpy().

typedef void(* uct_async_event_cb_t) (void *arg, unsigned flags)

Parameters

[in]	arg	User argument to be passed to the callback.
[in]	flags	Flags to be passed to the callback (reserved for future use).

Enumeration Type Documentation

enum 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

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.

enum 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

enum 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

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

enum 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().

enum 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).

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

enum 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

enum 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

enum 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

Enumerator
UCT_TAG_RECV_CB_INLINE_DATA

enum 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

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_p	Filled with a pointer to an array of component handles.
[out]	num_components_p	Filled 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.

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] components Array of component handles to release.

Examples:: uct_hello_world.c.

ucs_status_t uct_component_query	(	uct_component_h	component,
		uct_component_attr_t *	component_attr
	)

Query various attributes of a component.

Parameters

[in]	component	Component handle to query attributes for. The handle can be obtained from uct_query_components.
[in,out]	component_attr	Filled with component attributes.

Returns: UCS_OK if successful, or nonzero error code in case of failure.

Examples:: uct_hello_world.c.

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]	component	Component on which to open the memory domain, as returned from uct_query_components.
[in]	md_name	Memory domain name, as returned from uct_component_query.
[in]	config	MD 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_p	Filled with a handle to the memory domain.

Returns: Error code.

Examples:: uct_hello_world.c.

void uct_md_close ( uct_md_h md )

Parameters

[in] md Memory domain to close.

Examples:: uct_hello_world.c.

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]	md	Handle to memory domain.
[out]	resources_p	Filled with a pointer to an array of resource descriptors.
[out]	num_resources_p	Filled with the number of resources in the array.

Returns: Error code.

Examples:: uct_hello_world.c.

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] resources Array of resource descriptors to release.

Examples:: uct_hello_world.c.

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]	md	Memory domain on which the transport's interface was registered.
[in]	tl_name	Transport 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_prefix	If non-NULL, search for environment variables starting with this UCT_<prefix>_. Otherwise, search for environment variables starting with just UCT_.
[in]	filename	If non-NULL, read configuration from this file. If the file does not exist, it will be ignored.
[out]	config_p	Filled with a pointer to configuration.

Returns: Error code.

Examples:: uct_hello_world.c.

void uct_config_release ( void * config )

Parameters

[in] config Configuration to release.

Examples:: uct_hello_world.c.

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]	md	Memory domain to create the interface on.
[in]	worker	Handle to worker which will be used to progress communications on this interface.
[in]	params	User defined uct_iface_params_t parameters.
[in]	config	Interface 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_p	Filled with a handle to opened communication interface.

Returns: Error code.

Examples:: uct_hello_world.c.

void uct_iface_close ( uct_iface_h iface )

Parameters

[in] iface Interface to close.

Examples:: uct_hello_world.c.

ucs_status_t uct_iface_query	(	uct_iface_h	iface,
		uct_iface_attr_t *	iface_attr
	)

Parameters

[in]	iface	Interface to query.
[out]	iface_attr	Filled with interface attributes.

Examples:: uct_hello_world.c.

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]	iface	Interface to query.
[out]	addr	Filled 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.

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]	iface	Interface to query.
[out]	addr	Filled 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.

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]	iface	Interface to check reachability from.
[in]	dev_addr	Device address to check reachability to. It is NULL if iface_attr.dev_addr_len == 0, and must be non-NULL otherwise.
[in]	iface_addr	Interface 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.

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]	ep	Endpoint to check
[in]	flags	Flags that define level of check (currently unsupported - set to 0).
[in]	comp	Handler to process status of ep

Returns: Error code.

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]	iface	Interface to get the notification descriptor.
[out]	fd_p	Location to write the notification file descriptor.

Returns: Error code.

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]	iface	Interface to arm.
[in]	events	Events 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.

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]	iface	Interface to allocate memory on.
[in]	length	Size of memory region to allocate.
[in]	flags	Memory allocation flags, see uct_md_mem_flags.
[in]	name	Allocation name, for debug purposes.
[out]	mem	Descriptor of allocated memory.

Returns: UCS_OK if allocation was successful, error code otherwise.

void uct_iface_mem_free ( const uct_allocated_memory_t * mem )

Parameters

[in] mem Descriptor of memory to release.

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:

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 .
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.
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] params User defined uct_ep_params_t configuration for the ep_p.

[out] ep_p Filled 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.

void uct_ep_destroy ( uct_ep_h ep )

Parameters

[in] ep Endpoint to destroy.

Examples:: uct_hello_world.c.

ucs_status_t uct_ep_get_address	(	uct_ep_h	ep,
		uct_ep_addr_t *	addr
	)

Parameters

[in]	ep	Endpoint to query.
[out]	addr	Filled 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.

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]	ep	Endpoint to connect.
[in]	dev_addr	Remote device address.
[in]	ep_addr	Remote endpoint address.

Examples:: uct_hello_world.c.

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]	iface	Interface to flush communications from.
[in]	flags	Flags that control completion semantic (currently only UCT_FLUSH_FLAG_LOCAL is supported).
[in,out]	comp	Completion 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.

ucs_status_t uct_iface_fence	(	uct_iface_h	iface,
		unsigned	flags
	)

Parameters

[in]	iface	Interface to issue communications from.
[in]	flags	Flags that control ordering semantic (currently unsupported - set to 0).

Returns: UCS_OK - Ordering is inserted.

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]	ep	Endpoint to add the pending request to.
[in]	req	Pending 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]	flags	Flags 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.

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]	ep	Endpoint to remove pending requests from.
[in]	cb	Callback to pass the removed requests to.
[in]	arg	Argument to pass to the cb callback.

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]	ep	Endpoint to flush communications from.
[in]	flags	Flags uct_flush_flags that control completion semantic.
[in,out]	comp	Completion 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.

ucs_status_t uct_ep_fence	(	uct_ep_h	ep,
		unsigned	flags
	)

Parameters

[in]	ep	Endpoint to issue communications from.
[in]	flags	Flags that control ordering semantic (currently unsupported - set to 0).

Returns: UCS_OK - Ordering is inserted.

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]	iface	The interface to enable progress.
[in]	flags	The 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.

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]	iface	The interface to disable progress.
[in]	flags	The 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.

unsigned uct_iface_progress ( uct_iface_h iface )

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.

[in]	params	User defined uct_ep_params_t configuration for the ep_p.
[out]	ep_p	Filled with handle to the new endpoint.

Modules

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation