File ucp_def.h

Typedefs

typedef struct ucp_device_local_mem_list *ucp_device_local_mem_list_h

typedef struct ucp_device_remote_mem_list *ucp_device_remote_mem_list_h

struct ucp_mem_attr

#include <ucp_def.h>

Attributes of the UCP Memory handle, filled by ucp_mem_query function.

Public Members

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

void *address: Address of the memory segment.

size_t length: Size of the memory segment.

ucs_memory_type_t mem_type: Type of allocated or registered memory

struct ucp_err_handler

#include <ucp_def.h>

UCP endpoint error handling context.

This structure should be initialized in ucp_ep_params_t to handle peer failure

Public Members

ucp_err_handler_cb_t cb: Error handler callback, if NULL, will not be called.

void *arg: User defined argument associated with an endpoint, it will be overridden by ucp_ep_params_t::user_data if both are set.

struct ucp_listener_conn_handler

#include <ucp_def.h>

UCP callback to handle the connection request in a client-server connection establishment flow.

This structure is used for handling an incoming connection request on the listener. Setting this type of handler allows creating an endpoint on any other worker and not limited to the worker on which the listener was created.

Note

Other than communication progress routines, it is allowed to call all other communication routines from the callback in the struct.
The callback is thread safe with respect to the worker it is invoked on.
It is the user’s responsibility to avoid potential dead lock accessing different worker.

Public Members

ucp_listener_conn_callback_t cb: Connection request callback

void *arg: User defined argument for the callback

struct ucp_ep_params

#include <ucp_def.h>

Tuning parameters for the UCP endpoint.

The structure defines the parameters that are used for the UCP endpoint tuning during the UCP ep creation.

Public Members

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

const ucp_address_t *address: Destination address; this field should be set along with its corresponding bit in the field_mask - UCP_EP_PARAM_FIELD_REMOTE_ADDRESS and must be obtained using ucp_worker_get_address.

ucp_err_handling_mode_t err_mode: Desired error handling mode, optional parameter. Default value is UCP_ERR_HANDLING_MODE_NONE.

ucp_err_handler_t err_handler: Handler to process transport level failure.

void *user_data: User data associated with an endpoint. See ucp_stream_poll_ep_t and ucp_err_handler_t

unsigned flags: Endpoint flags from ucp_ep_params_flags_field. This value is optional. If it’s not set (along with its corresponding bit in the field_mask - UCP_EP_PARAM_FIELD_FLAGS), the ucp_ep_create() routine will consider the flags as set to zero.

ucs_sock_addr_t sockaddr: Destination address in the form of a sockaddr; this field should be set along with its corresponding bit in the field_mask - UCP_EP_PARAM_FIELD_SOCK_ADDR and must be obtained from the user, it means that this type of the endpoint creation is possible only on client side in client-server connection establishment flow.

ucp_conn_request_h conn_request: Connection request from client; this field should be set along with its corresponding bit in the field_mask - UCP_EP_PARAM_FIELD_CONN_REQUEST and must be obtained from ucp_listener_conn_callback_t, it means that this type of the endpoint creation is possible only on server side in client-server connection establishment flow.

const char *name: Endpoint name. Tracing and analysis tools can identify the endpoint using this name. To retrieve the endpoint’s name, use ucp_ep_query, as the name you supply may be changed by UCX under some circumstances, e.g. a name conflict. This field is only assigned if you set UCP_EP_PARAM_FIELD_NAME in the field mask. If not, then a default unique name will be created for you.

ucs_sock_addr_t local_sockaddr: The sockaddr to bind locally. Specifies the associated network device to bind locally to establish new connections. To retrieve the endpoint’s local_sockaddr, use ucp_ep_query. This setting is optional. To enable it, the corresponding - UCP_EP_PARAM_FIELD_LOCAL_SOCK_ADDR bit in the field mask must be set.

struct ucp_transport_entry_t

#include <ucp_def.h>

The ucp_transports_t and ucp_transport_entry_t structures are used when ucp_ep_query is called to return an array of transport name and device name pairs that are used by an active endpoint.

The ucp_transport_t structure specifies the characteristics of the ucp_transport_entry_t array.

The caller is responsible for the allocation and de-allocation of the ucp_transport_entry_t array.

Example: Implementation of a function to query the set of transport and device name pairs used by the specified endpoint.

int query_transports(ucp_ep_h ep)
{
  ucs_status_t status;
  ucp_transport_entry_t *transport_entries;
  ucp_ep_attr_t ep_attrs;

  ep_attrs.field_mask = UCP_EP_ATTR_FIELD_TRANSPORTS;
  ep_attrs.transports.entries = (ucp_transport_entry_t *)
           malloc(10 * sizeof(ucp_transport_entry_t));
  ep_attrs.transports.num_entries = 10;
  ep_attrs.transports.entry_size = sizeof(ucp_transport_entry_t);
  status = ucp_ep_query(ep, &ep_attrs);
  if (status == UCS_OK) {
      // ep_attrs.transports.num_entries = number of returned entries 
      // ... process transport info ... 
  }
}

A transport name and device name pair used by this endpoint. The caller is responsible for the allocation and deallocation of an array of these structures large enough to contain the desired number of transport and device name pairs.

Any new fields must be added to the end of this structure.

Public Members

const char *transport_name: The name of a transport layer used by this endpoint. This ‘\0’-terminated string is valid until the endpoint is closed using a ucp_ep_close_nbx call.

const char *device_name: The name of the device used with this transport by this endpoint. This ‘\0’-terminated string is valid until the endpoint is closed using a ucp_ep_close_nbx call.

struct ucp_transports_t

#include <ucp_def.h>

Structure containing an array of transport layers and device names used by an endpoint.

The caller is responsible for allocation and deallocation of this structure.

Public Members

ucp_transport_entry_t *entries: Pointer to array of transport/device name pairs used by this endpoint. The caller is responsible for the allocation and deallocation of this array.

unsigned num_entries: Number of transport/device name pairs. The caller must set this to the maximum number of pairs the structure can contain. On return, this is set to the actual number of transport and device name pairs used by the endpoint.

size_t entry_size: Size of a single ucp_transport_entry_t object. The caller sets this to the size of the ucp_transport_entry_t they are using. UCP code must not set any fields in the ucp_transport_entry_t structure beyond this size.