UCX  1.8
Unified Communication X
UCT client-server operations

Data Structures

struct  uct_cm_attr
 Connection manager attributes, capabilities and limitations. More...
 
struct  uct_listener_attr
 UCT listener attributes, capabilities and limitations. More...
 
struct  uct_listener_params
 Parameters for creating a listener object uct_listener_h by uct_listener_create. More...
 
struct  uct_cm_remote_data
 Data received from the remote peer. More...
 

Typedefs

typedef struct uct_cm_remote_data uct_cm_remote_data_t
 Data received from the remote peer. More...
 
typedef void(* uct_sockaddr_conn_request_callback_t) (uct_iface_h iface, void *arg, uct_conn_request_h conn_request, const void *conn_priv_data, size_t length)
 Callback to process an incoming connection request on the server side. More...
 
typedef void(* uct_listener_conn_request_callback_t) (uct_listener_h listener, void *arg, const char *local_dev_name, uct_conn_request_h conn_request, const uct_cm_remote_data_t *remote_data)
 Callback to process an incoming connection request on the server side listener in a connection manager. More...
 
typedef void(* uct_ep_server_connect_cb_t) (uct_ep_h ep, void *arg, ucs_status_t status)
 Callback to process an incoming connection establishment acknowledgment on the server side listener, from the client, which indicates that the client side is connected. More...
 
typedef void(* uct_ep_client_connect_cb_t) (uct_ep_h ep, void *arg, const uct_cm_remote_data_t *remote_data, ucs_status_t status)
 Callback to process an incoming connection response on the client side from the server. More...
 
typedef void(* uct_ep_disconnect_cb_t) (uct_ep_h ep, void *arg)
 Callback to handle the disconnection of the remote peer. More...
 
typedef ssize_t(* uct_sockaddr_priv_pack_callback_t) (void *arg, const char *dev_name, void *priv_data)
 Callback to fill the user's private data in a client-server flow. More...
 

Enumerations

enum  uct_cm_attr_field { UCT_CM_ATTR_FIELD_MAX_CONN_PRIV = UCS_BIT(0) }
 UCT connection manager attributes field mask. More...
 
enum  uct_listener_attr_field { UCT_LISTENER_ATTR_FIELD_SOCKADDR = UCS_BIT(0) }
 UCT listener attributes field mask. More...
 
enum  uct_listener_params_field { UCT_LISTENER_PARAM_FIELD_BACKLOG = UCS_BIT(0), UCT_LISTENER_PARAM_FIELD_CONN_REQUEST_CB = UCS_BIT(1), UCT_LISTENER_PARAM_FIELD_USER_DATA = UCS_BIT(2) }
 UCT listener created by uct_listener_create parameters field mask. More...
 
enum  uct_cm_remote_data_field { UCT_CM_REMOTE_DATA_FIELD_DEV_ADDR = UCS_BIT(0), UCT_CM_REMOTE_DATA_FIELD_DEV_ADDR_LENGTH = UCS_BIT(1), UCT_CM_REMOTE_DATA_FIELD_CONN_PRIV_DATA = UCS_BIT(2), UCT_CM_REMOTE_DATA_FIELD_CONN_PRIV_DATA_LENGTH = UCS_BIT(3) }
 Remote data attributes field mask. More...
 

Functions

ucs_status_t uct_iface_accept (uct_iface_h iface, uct_conn_request_h conn_request)
 Accept connection request. More...
 
ucs_status_t uct_iface_reject (uct_iface_h iface, uct_conn_request_h conn_request)
 Reject connection request. Will invoke an error handler uct_error_handler_t on the remote transport interface, if set. More...
 
ucs_status_t uct_ep_disconnect (uct_ep_h ep, unsigned flags)
 Initiate a disconnection of an endpoint connected to a sockaddr by a connection manager uct_cm_h. More...
 
ucs_status_t uct_cm_open (uct_component_h component, uct_worker_h worker, const uct_cm_config_t *config, uct_cm_h *cm_p)
 Open a connection manager. More...
 
void uct_cm_close (uct_cm_h cm)
 Close a connection manager. More...
 
ucs_status_t uct_cm_query (uct_cm_h cm, uct_cm_attr_t *cm_attr)
 Get connection manager attributes. More...
 
ucs_status_t uct_cm_config_read (uct_component_h component, const char *env_prefix, const char *filename, uct_cm_config_t **config_p)
 Read the configuration for a connection manager. More...
 
ucs_status_t uct_listener_create (uct_cm_h cm, const struct sockaddr *saddr, socklen_t socklen, const uct_listener_params_t *params, uct_listener_h *listener_p)
 Create a new transport listener object. More...
 
void uct_listener_destroy (uct_listener_h listener)
 Destroy a transport listener. More...
 
ucs_status_t uct_listener_reject (uct_listener_h listener, uct_conn_request_h conn_request)
 Reject a connection request. More...
 
ucs_status_t uct_listener_query (uct_listener_h listener, uct_listener_attr_t *listener_attr)
 Get attributes specific to a particular listener. More...
 

Detailed Description

Defines client-server operations. The client-server API allows the connection establishment between an active side - a client, and its peer - the passive side - a server. The connection can be established through a UCT transport that supports listening and connecting via IP address and port (listening can also be on INADDR_ANY).

The following is a general overview of the operations on the server side:

Connecting: uct_cm_open Open a connection manager. uct_listener_create Create a listener on the CM and start listening on a given IP,port / INADDR_ANY. uct_listener_conn_request_callback_t This callback is invoked by the UCT transport to handle an incoming connection request from a client. Accept or reject the client's connection request. uct_ep_create Connect to the client by creating an endpoint in case of accepting its request. The server creates a new endpoint per every connection request that it accepts. uct_sockaddr_priv_pack_callback_t This callback is invoked by the UCT transport to fill auxiliary data in the connection acknowledgement or reject notification back to the client. Send the client a connection acknowledgement or reject notification. Wait for an acknowledgment from the client, indicating that it is connected. uct_ep_server_connect_cb_t This callback is invoked by the UCT transport to handle the connection acknowledgment from the client.

Disconnecting: uct_ep_disconnect Disconnect the server's endpoint from the client. Can be called when initiating a disconnect or when receiving a disconnect notification from the remote side. uct_ep_disconnect_cb_t This callback is invoked by the UCT transport when the client side calls uct_ep_disconnect as well. uct_ep_destroy Destroy the endpoint connected to the remote peer. If this function is called before the endpoint was disconnected, the uct_ep_disconnect_cb_t will not be invoked.

Destroying the server's resources: uct_listener_destroy Destroy the listener object. uct_cm_close Close the connection manager.

The following is a general overview of the operations on the client side:

Connecting: uct_cm_open Open a connection manager. uct_ep_create Create an endpoint for establishing a connection to the server. uct_sockaddr_priv_pack_callback_t This callback is invoked by the UCT transport to fill the user's private data in the connection request to be sent to the server. This connection request should be created by the transport. Send the connection request to the server. Wait for an acknowledgment from the server, indicating that it is connected. uct_ep_client_connect_cb_t This callback is invoked by the UCT transport to handle a connection response from the server. After invoking this callback, the UCT transport will finalize the client's connection to the server.

Disconnecting: uct_ep_disconnect Disconnect the client's endpoint from the server. Can be called when initiating a disconnect or when receiving a disconnect notification from the remote side. uct_ep_disconnect_cb_t This callback is invoked by the UCT transport when the server side calls uct_ep_disconnect as well. uct_ep_destroy Destroy the endpoint connected to the remote peer.

Destroying the client's resources: uct_cm_close Close the connection manager.


Data Structure Documentation

◆ uct_cm_attr

struct uct_cm_attr
Data Fields
uint64_t field_mask

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

size_t max_conn_priv

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

◆ uct_listener_attr

struct uct_listener_attr
Data Fields
uint64_t field_mask

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

struct sockaddr_storage sockaddr

Sockaddr on which this listener is listening.

◆ uct_listener_params

struct uct_listener_params
Data Fields
uint64_t field_mask

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

int backlog

Backlog of incoming connection requests. If not specified, SOMAXCONN, as defined in <sys/socket.h>, will be used.

uct_listener_conn_request_callback_t conn_request_cb

Callback function for handling incoming connection requests.

void * user_data

User data associated with the listener.

◆ uct_cm_remote_data

struct uct_cm_remote_data

The remote peer's device address, the data received from it and their lengths. Used with the client-server API on a connection manager.

Data Fields
uint64_t field_mask

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

const uct_device_addr_t * dev_addr

Device address of the remote peer.

size_t dev_addr_length

Length of the remote device address.

const void * conn_priv_data

Pointer to the received data. This is the private data that was passed to uct_ep_params_t::sockaddr_pack_cb.

size_t conn_priv_data_length

Length of the received data from the peer.

Typedef Documentation

◆ uct_cm_remote_data_t

The remote peer's device address, the data received from it and their lengths. Used with the client-server API on a connection manager.

◆ uct_sockaddr_conn_request_callback_t

typedef void(* uct_sockaddr_conn_request_callback_t) (uct_iface_h iface, void *arg, uct_conn_request_h conn_request, const void *conn_priv_data, size_t length)

This callback routine will be invoked on the server side upon receiving an incoming connection request. It should be set by the server side while initializing an interface. Incoming data is placed inside the conn_priv_data buffer. This callback has to be thread safe. Other than communication progress routines, it is allowed to call other UCT communication routines from this callback.

Parameters
[in]ifaceTransport interface.
[in]argUser defined argument for this callback.
[in]conn_requestTransport level connection request. The user should accept or reject the request by calling uct_iface_accept or uct_iface_reject routines respectively. conn_request should not be used outside the scope of this callback.
[in]conn_priv_dataPoints to the received data. This is the private data that was passed to the uct_ep_params_t::sockaddr_pack_cb on the client side.
[in]lengthLength of the received data.

◆ uct_listener_conn_request_callback_t

typedef void(* uct_listener_conn_request_callback_t) (uct_listener_h listener, void *arg, const char *local_dev_name, uct_conn_request_h conn_request, const uct_cm_remote_data_t *remote_data)

This callback routine will be invoked on the server side upon receiving an incoming connection request. It should be set by the server side while initializing a listener in a connection manager. This callback has to be thread safe. Other than communication progress routines, it is allowed to call other UCT communication routines from this callback.

Parameters
[in]listenerTransport listener.
[in]argUser argument for this callback as defined in uct_listener_params_t::user_data
[in]local_dev_nameDevice name which handles the incoming connection request.
[in]conn_requestConnection request handle. Can be passed to this callback from the transport and will be used by it to accept or reject the connection request from the client.
[in]remote_dataRemote data from the client.

◆ uct_ep_server_connect_cb_t

typedef void(* uct_ep_server_connect_cb_t) (uct_ep_h ep, void *arg, ucs_status_t status)

This callback routine will be invoked on the server side upon receiving an incoming connection establishment acknowledgment from the client, which is sent from it once the client is connected to the server. Used to connect the server side to the client or handle an error from it - depending on the status field. This callback has to be thread safe. Other than communication progress routines, it is allowed to call other UCT communication routines from this callback.

Parameters
[in]epTransport endpoint.
[in]argUser argument for this callback as defined in uct_ep_params_t::user_data
[in]statusIndicates the client's status.

◆ uct_ep_client_connect_cb_t

typedef void(* uct_ep_client_connect_cb_t) (uct_ep_h ep, void *arg, const uct_cm_remote_data_t *remote_data, ucs_status_t status)

This callback routine will be invoked on the client side upon receiving an incoming connection response from the server. Used to connect the client side to the server or handle an error from it - depending on the status field. This callback has to be thread safe. Other than communication progress routines, it is allowed to call other UCT communication routines from this callback.

Parameters
[in]epTransport endpoint.
[in]argUser argument for this callback as defined in uct_ep_params_t::user_data.
[in]remote_dataRemote data from the server.
[in]statusIndicates the server's status.

◆ uct_ep_disconnect_cb_t

typedef void(* uct_ep_disconnect_cb_t) (uct_ep_h ep, void *arg)

This callback routine will be invoked on the client and server sides upon a disconnect of the remote peer. It will disconnect the given endpoint from the remote peer. This callback won't be invoked if uct_ep_disconnect was called locally with a completion that is not NULL. This callback has to be thread safe. Other than communication progress routines, it is allowed to call other UCT communication routines from this callback.

Parameters
[in]epTransport endpoint to disconnect.
[in]argUser argument for this callback as defined in uct_ep_params_t::user_data.

◆ uct_sockaddr_priv_pack_callback_t

typedef ssize_t(* uct_sockaddr_priv_pack_callback_t) (void *arg, const char *dev_name, void *priv_data)

This callback routine will be invoked on the client side, before sending the transport's connection request to the server, or on the server side before sending a connection response to the client. The callback routine must be set when creating an endpoint. The user's private data should be placed inside the priv_data buffer to be sent to the remote side. The maximal allowed length of the private data is indicated by the field max_conn_priv inside uct_iface_attr or inside uct_cm_attr when using a connection manager. Communication progress routines should not be called from this callback. It is allowed to call other UCT communication routines from this callback.

Parameters
[in]argUser defined argument for this callback.
[in]dev_nameDevice name. This routine may fill the user's private data according to the given device name. The device name that is passed to this routine, corresponds to the dev_name field inside uct_tl_resource_desc_t as returned from uct_md_query_tl_resources.
[out]priv_dataUser's private data to be passed to the remote side.
Returns
Negative value indicates an error according to ucs_status_t. On success, a non-negative value indicates actual number of bytes written to the priv_data buffer.

Enumeration Type Documentation

◆ uct_cm_attr_field

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

Enumerator
UCT_CM_ATTR_FIELD_MAX_CONN_PRIV 

Enables uct_cm_attr::max_conn_priv

◆ uct_listener_attr_field

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

Enumerator
UCT_LISTENER_ATTR_FIELD_SOCKADDR 

Enables uct_listener_attr::sockaddr

◆ uct_listener_params_field

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

Enumerator
UCT_LISTENER_PARAM_FIELD_BACKLOG 

Enables uct_listener_params::backlog

UCT_LISTENER_PARAM_FIELD_CONN_REQUEST_CB 

Enables uct_listener_params::conn_request_cb

UCT_LISTENER_PARAM_FIELD_USER_DATA 

Enables uct_listener_params::user_data

◆ uct_cm_remote_data_field

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

Enumerator
UCT_CM_REMOTE_DATA_FIELD_DEV_ADDR 

Enables uct_cm_remote_data::dev_addr

UCT_CM_REMOTE_DATA_FIELD_DEV_ADDR_LENGTH 

Enables uct_cm_remote_data::dev_addr_length

UCT_CM_REMOTE_DATA_FIELD_CONN_PRIV_DATA 

Enables uct_cm_remote_data::conn_priv_data

UCT_CM_REMOTE_DATA_FIELD_CONN_PRIV_DATA_LENGTH 

Enables uct_cm_remote_data::conn_priv_data_length

Function Documentation

◆ uct_iface_accept()

ucs_status_t uct_iface_accept ( uct_iface_h  iface,
uct_conn_request_h  conn_request 
)
Parameters
[in]ifaceTransport interface which generated connection request conn_request.
[in]conn_requestConnection establishment request passed as parameter of uct_sockaddr_conn_request_callback_t.
Returns
Error code as defined by ucs_status_t

◆ uct_iface_reject()

ucs_status_t uct_iface_reject ( uct_iface_h  iface,
uct_conn_request_h  conn_request 
)
Parameters
[in]ifaceInterface which generated connection establishment request conn_request.
[in]conn_requestConnection establishment request passed as parameter of uct_sockaddr_conn_request_callback_t.
Returns
Error code as defined by ucs_status_t

◆ uct_ep_disconnect()

ucs_status_t uct_ep_disconnect ( uct_ep_h  ep,
unsigned  flags 
)

This non-blocking routine will send a disconnect notification on the endpoint, so that uct_ep_disconnect_cb_t will be called on the remote peer. The remote side should also call this routine when handling the initiator's disconnect. After a call to this function, the given endpoint may not be used for communications anymore. The uct_ep_flush / uct_iface_flush routines will guarantee that the disconnect notification is delivered to the remote peer. uct_ep_destroy should be called on this endpoint after invoking this routine and uct_ep_params::disconnect_cb was called.

Parameters
[in]epEndpoint to disconnect.
[in]flagsReserved for future use.
Returns
UCS_OK Operation has completed successfully. UCS_ERR_BUSY The ep is not connected yet (either uct_ep_client_connect_cb_t or uct_ep_server_connect_cb_t was not invoked). UCS_INPROGRESS The disconnect request has been initiated, but the remote peer has not yet responded to this request, and consequently the registered callback uct_ep_disconnect_cb_t has not been invoked to handle the request. UCS_ERR_NOT_CONNECTED The ep is disconnected locally and remotely. Other error codes as defined by ucs_status_t .

◆ uct_cm_open()

ucs_status_t uct_cm_open ( uct_component_h  component,
uct_worker_h  worker,
const uct_cm_config_t config,
uct_cm_h cm_p 
)

Open a connection manager. All client server connection establishment operations are performed in the context of a specific connection manager.

Note
This is an alternative API for uct_iface_open_mode::UCT_IFACE_OPEN_MODE_SOCKADDR_SERVER and uct_iface_open_mode::UCT_IFACE_OPEN_MODE_SOCKADDR_CLIENT .
Parameters
[in]componentComponent on which to open the connection manager, as returned from uct_query_components.
[in]workerWorker on which to open the connection manager.
[in]configCM configuration options. Either obtained from uct_cm_config_read() function, or pointer to CM-specific structure that extends uct_cm_config_t.
[out]cm_pFilled with a handle to the connection manager.
Returns
Error code.

◆ uct_cm_close()

void uct_cm_close ( uct_cm_h  cm)
Parameters
[in]cmConnection manager to close.

◆ uct_cm_query()

ucs_status_t uct_cm_query ( uct_cm_h  cm,
uct_cm_attr_t cm_attr 
)

This routine queries the cm for its attributes uct_cm_attr_t.

Parameters
[in]cmConnection manager to query.
[out]cm_attrFilled with connection manager attributes.

◆ uct_cm_config_read()

ucs_status_t uct_cm_config_read ( uct_component_h  component,
const char *  env_prefix,
const char *  filename,
uct_cm_config_t **  config_p 
)
Parameters
[in]componentRead the configuration of the connection manager on this component.
[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, or exists but cannot be opened or read, it will be ignored.
[out]config_pFilled with a pointer to the configuration.
Returns
Error code.

◆ uct_listener_create()

ucs_status_t uct_listener_create ( uct_cm_h  cm,
const struct sockaddr *  saddr,
socklen_t  socklen,
const uct_listener_params_t params,
uct_listener_h listener_p 
)

This routine creates a new listener on the given CM which will start listening on a given sockaddr.

Parameters
[in]cmConnection manager on which to open the listener. This cm should not be closed as long as there are open listeners on it.
[in]saddrThe socket address to listen on.
[in]socklenThe saddr length.
[in]paramsUser defined uct_listener_params_t configurations for the listener_p.
[out]listener_pFilled with handle to the new listener.
Returns
Error code.

◆ uct_listener_destroy()

void uct_listener_destroy ( uct_listener_h  listener)
Parameters
[in]listenerListener to destroy.

◆ uct_listener_reject()

ucs_status_t uct_listener_reject ( uct_listener_h  listener,
uct_conn_request_h  conn_request 
)

This routine can be invoked on the server side. It rejects a connection request from the client.

Parameters
[in]listenerListener which will reject the connection request.
[in]conn_requestConnection establishment request passed as parameter of uct_listener_conn_request_callback_t.
Returns
Error code as defined by ucs_status_t

◆ uct_listener_query()

ucs_status_t uct_listener_query ( uct_listener_h  listener,
uct_listener_attr_t listener_attr 
)

This routine queries the listener for its attributes uct_listener_attr_t.

Parameters
[in]listenerListener object to query.
[out]listener_attrFilled with attributes of the listener.
Returns
Error code as defined by ucs_status_t