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

Data Structures

struct  ucp_ep_evaluate_perf_param_t
 UCP endpoint performance evaluation request attributes. More...
 
struct  ucp_ep_evaluate_perf_attr_t
 UCP endpoint performance evaluation result attributes. More...
 
struct  ucp_stream_poll_ep
 Output parameter of ucp_stream_worker_poll function. More...
 
struct  ucp_ep_attr
 UCP endpoint attributes. More...
 
struct  ucp_ep_params
 Tuning parameters for the UCP endpoint. More...
 
struct  ucp_transport_entry_t
 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. More...
 
struct  ucp_transports_t
 Structure containing an array of transport layers and device names used by an endpoint. More...
 

Typedefs

typedef enum ucp_ep_perf_param_field ucp_ep_perf_param_field_t
 UCP performance fields and flags.
 
typedef enum ucp_ep_perf_attr_field ucp_ep_perf_attr_field_t
 UCP performance fields and flags.
 
typedef struct ucp_stream_poll_ep ucp_stream_poll_ep_t
 Output parameter of ucp_stream_worker_poll function.
 
typedef struct ucp_ep_attr ucp_ep_attr_t
 UCP endpoint attributes.
 
typedef struct ucp_ep * ucp_ep_h
 UCP Endpoint.
 
typedef struct ucp_conn_request * ucp_conn_request_h
 UCP connection request.
 
typedef ucs_status_t(* ucp_am_callback_t) (void *arg, void *data, size_t length, ucp_ep_h reply_ep, unsigned flags)
 Callback to process incoming Active Message.
 
typedef ucs_status_t(* ucp_am_recv_callback_t) (void *arg, const void *header, size_t header_length, void *data, size_t length, const ucp_am_recv_param_t *param)
 Callback to process incoming Active Message sent by ucp_am_send_nbx routine.
 
typedef struct ucp_ep_params ucp_ep_params_t
 Tuning parameters for the UCP endpoint.
 

Enumerations

enum  ucp_ep_params_field {
  UCP_EP_PARAM_FIELD_REMOTE_ADDRESS = UCS_BIT(0) , UCP_EP_PARAM_FIELD_ERR_HANDLING_MODE = UCS_BIT(1) , UCP_EP_PARAM_FIELD_ERR_HANDLER = UCS_BIT(2) , UCP_EP_PARAM_FIELD_USER_DATA = UCS_BIT(3) ,
  UCP_EP_PARAM_FIELD_SOCK_ADDR = UCS_BIT(4) , UCP_EP_PARAM_FIELD_FLAGS = UCS_BIT(5) , UCP_EP_PARAM_FIELD_CONN_REQUEST = UCS_BIT(6) , UCP_EP_PARAM_FIELD_NAME = UCS_BIT(7) ,
  UCP_EP_PARAM_FIELD_LOCAL_SOCK_ADDR = UCS_BIT(8)
}
 UCP endpoint parameters field mask. More...
 
enum  ucp_ep_params_flags_field { UCP_EP_PARAMS_FLAGS_CLIENT_SERVER = UCS_BIT(0) , UCP_EP_PARAMS_FLAGS_NO_LOOPBACK = UCS_BIT(1) , UCP_EP_PARAMS_FLAGS_SEND_CLIENT_ID = UCS_BIT(2) }
 UCP endpoint parameters flags. More...
 
enum  ucp_ep_close_flags_t { UCP_EP_CLOSE_FLAG_FORCE = UCS_BIT(0) }
 Close UCP endpoint modes. More...
 
enum  ucp_ep_perf_param_field { UCP_EP_PERF_PARAM_FIELD_MESSAGE_SIZE = UCS_BIT(0) }
 UCP performance fields and flags. More...
 
enum  ucp_ep_perf_attr_field { UCP_EP_PERF_ATTR_FIELD_ESTIMATED_TIME = UCS_BIT(0) }
 UCP performance fields and flags. More...
 
enum  ucp_cb_param_flags { UCP_CB_PARAM_FLAG_DATA = UCS_BIT(0) }
 Descriptor flags for Active Message callback. More...
 
enum  ucp_ep_attr_field { UCP_EP_ATTR_FIELD_NAME = UCS_BIT(0) , UCP_EP_ATTR_FIELD_LOCAL_SOCKADDR = UCS_BIT(1) , UCP_EP_ATTR_FIELD_REMOTE_SOCKADDR = UCS_BIT(2) , UCP_EP_ATTR_FIELD_TRANSPORTS = UCS_BIT(3) }
 UCP endpoint attributes field mask. More...
 
enum  ucp_ep_close_mode { UCP_EP_CLOSE_MODE_FORCE = 0 , UCP_EP_CLOSE_MODE_FLUSH = 1 }
 Close UCP endpoint modes. More...
 
enum  ucp_err_handling_mode_t { UCP_ERR_HANDLING_MODE_NONE , UCP_ERR_HANDLING_MODE_PEER }
 Error handling mode for the UCP endpoint. More...
 

Functions

ucs_status_t ucp_ep_create (ucp_worker_h worker, const ucp_ep_params_t *params, ucp_ep_h *ep_p)
 Create and connect an endpoint.
 
ucs_status_ptr_t ucp_ep_close_nbx (ucp_ep_h ep, const ucp_request_param_t *param)
 Non-blocking endpoint closure.
 
void ucp_ep_print_info (ucp_ep_h ep, FILE *stream)
 Print endpoint information.
 
ucs_status_ptr_t ucp_ep_flush_nbx (ucp_ep_h ep, const ucp_request_param_t *param)
 Non-blocking flush of outstanding AMO and RMA operations on the endpoint.
 
ucs_status_t ucp_ep_evaluate_perf (ucp_ep_h ep, const ucp_ep_evaluate_perf_param_t *param, ucp_ep_evaluate_perf_attr_t *attr)
 Estimate performance characteristics of a specific endpoint.
 
ucs_status_t ucp_ep_query (ucp_ep_h ep, ucp_ep_attr_t *attr)
 Get attributes of a given endpoint.
 
void ucp_request_release (void *request)
 
void ucp_ep_destroy (ucp_ep_h ep)
 
ucs_status_ptr_t ucp_disconnect_nb (ucp_ep_h ep)
 
ucs_status_t ucp_request_test (void *request, ucp_tag_recv_info_t *info)
 
ucs_status_t ucp_ep_flush (ucp_ep_h ep)
 
ucs_status_ptr_t ucp_ep_modify_nb (ucp_ep_h ep, const ucp_ep_params_t *params)
 Modify endpoint parameters.
 
ucs_status_ptr_t ucp_ep_close_nb (ucp_ep_h ep, unsigned mode)
 Non-blocking endpoint closure.
 
ucs_status_ptr_t ucp_ep_flush_nb (ucp_ep_h ep, unsigned flags, ucp_send_callback_t cb)
 Non-blocking flush of outstanding AMO and RMA operations on the endpoint.
 

Detailed Description

UCP Endpoint routines


Data Structure Documentation

◆ ucp_ep_evaluate_perf_param_t

struct ucp_ep_evaluate_perf_param_t

The structure defines the attributes which characterize the request for performance estimation of a particular endpoint.

Data Fields
uint64_t field_mask

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

size_t message_size

Message size to use for determining performance. This field must be initialized by the caller.

◆ ucp_ep_evaluate_perf_attr_t

struct ucp_ep_evaluate_perf_attr_t

The structure defines the attributes which characterize the result of performance estimation of a particular endpoint.

Data Fields
uint64_t field_mask

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

double estimated_time

Estimated time (in seconds) required to send a message of a given size on this endpoint. This field is set by the ucp_ep_evaluate_perf function.

◆ ucp_stream_poll_ep

struct ucp_stream_poll_ep

The structure defines the endpoint and its user data.

Data Fields
ucp_ep_h ep

Endpoint handle.

void * user_data

User data associated with an endpoint passed in ucp_ep_params_t::user_data.

unsigned flags

Reserved for future use.

uint8_t reserved[16]

Reserved for future use.

◆ ucp_ep_attr

struct ucp_ep_attr

The structure defines the attributes that characterize the particular endpoint.

Data Fields
uint64_t field_mask

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

char name[UCP_ENTITY_NAME_MAX]

Endpoint name. Tracing and analysis tools can identify the endpoint using this name.

struct sockaddr_storage local_sockaddr

Local socket address for this endpoint. Valid only for endpoints created by connecting to a socket address. If this field is specified for an endpoint not connected to a socket address, UCS_ERR_NOT_CONNECTED will be returned.

struct sockaddr_storage remote_sockaddr

Remote socket address this endpoint is connected to. Valid only for endpoints created by connecting to a socket address. If this field is specified for an endpoint not connected to a socket address, UCS_ERR_NOT_CONNECTED will be returned.

ucp_transports_t transports

Structure defining an array containing transport and device names used by this endpoint. The caller is responsible for allocation and deallocation of this array.

◆ ucp_ep_params

struct ucp_ep_params

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

Examples
ucp_client_server.c, and ucp_hello_world.c.
Data Fields
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.

◆ ucp_transport_entry_t

struct ucp_transport_entry_t

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;
malloc(10 * sizeof(ucp_transport_entry_t));
ep_attrs.transports.num_entries = 10;
status = ucp_ep_query(ep, &ep_attrs);
if (status == UCS_OK) {
// ep_attrs.transports.num_entries = number of returned entries
// ... process transport info ...
}
}
size_t entry_size
Definition ucp_def.h:868
ucp_transports_t transports
Definition ucp.h:4106
unsigned num_entries
Definition ucp_def.h:860
uint64_t field_mask
Definition ucp.h:4077
ucp_transport_entry_t * entries
Definition ucp_def.h:852
ucs_status_t ucp_ep_query(ucp_ep_h ep, ucp_ep_attr_t *attr)
Get attributes of a given endpoint.
struct ucp_ep * ucp_ep_h
UCP Endpoint.
Definition ucp_def.h:92
@ UCP_EP_ATTR_FIELD_TRANSPORTS
Definition ucp.h:4059
UCP endpoint attributes.
Definition ucp.h:4070
The ucp_transports_t and ucp_transport_entry_t structures are used when ucp_ep_query is called to ret...
Definition ucp_def.h:820
ucs_status_t
Status codes.
Definition status.h:45
@ UCS_OK
Definition status.h:47

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.

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

◆ ucp_transports_t

struct ucp_transports_t

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

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

Typedef Documentation

◆ ucp_ep_perf_param_field_t

The enumeration allows specifying which fields in ucp_ep_evaluate_perf_param_t are present and operation flags are used. It is used to enable backward compatibility support.

◆ ucp_ep_perf_attr_field_t

The enumeration allows specifying which fields in ucp_ep_evaluate_perf_attr_t are present and operation flags are used. It is used to enable backward compatibility support.

◆ ucp_stream_poll_ep_t

The structure defines the endpoint and its user data.

◆ ucp_ep_attr_t

typedef struct ucp_ep_attr ucp_ep_attr_t

The structure defines the attributes that characterize the particular endpoint.

◆ ucp_ep_h

typedef struct ucp_ep* ucp_ep_h

The endpoint handle is an opaque object that is used to address a remote worker. It typically provides a description of source, destination, or both. All UCP communication routines address a destination with the endpoint handle. The endpoint handle is associated with only one UCP context. UCP provides the endpoint create routine to create the endpoint handle and the destroy routine to destroy the endpoint handle.

◆ ucp_conn_request_h

typedef struct ucp_conn_request* ucp_conn_request_h

A server-side handle to incoming connection request. Can be used to create an endpoint which connects back to the client.

◆ ucp_am_callback_t

typedef ucs_status_t(* ucp_am_callback_t) (void *arg, void *data, size_t length, ucp_ep_h reply_ep, unsigned flags)

When the callback is called, flags indicates how data should be handled.

Parameters
[in]argUser-defined argument.
[in]dataPoints to the received data. This data may persist after the callback returns and needs to be freed with ucp_am_data_release.
[in]lengthLength of data.
[in]reply_epIf the Active Message is sent with the UCP_AM_SEND_FLAG_REPLY flag, the sending ep will be passed in. If not, NULL will be passed.
[in]flagsIf this flag is set to UCP_CB_PARAM_FLAG_DATA, the callback can return UCS_INPROGRESS and data will persist after the callback returns.
Returns
UCS_OK data will not persist after the callback returns.
UCS_INPROGRESS Can only be returned if flags is set to UCP_CB_PARAM_FLAG_DATA. If UCP_INPROGRESS is returned, data will persist after the callback has returned. To free the memory, a pointer to the data must be passed into ucp_am_data_release.
Note
This callback should be set and released by ucp_worker_set_am_handler function.

◆ ucp_am_recv_callback_t

typedef ucs_status_t(* ucp_am_recv_callback_t) (void *arg, const void *header, size_t header_length, void *data, size_t length, const ucp_am_recv_param_t *param)

The callback is always called from the progress context, therefore calling ucp_worker_progress() is not allowed. It is recommended to define callbacks with relatively short execution time to avoid blocking of communication progress.

Parameters
[in]argUser-defined argument.
[in]headerUser defined active message header. If header_length is 0, this value is undefined and must not be accessed.
[in]header_lengthActive message header length in bytes.
[in]dataPoints to the received data if UCP_AM_RECV_ATTR_FLAG_RNDV flag is not set in ucp_am_recv_param_t::recv_attr. Otherwise it points to the internal UCP descriptor which can further be used for initiating data receive by using ucp_am_recv_data_nbx routine.
[in]lengthLength of data. If UCP_AM_RECV_ATTR_FLAG_RNDV flag is set in ucp_am_recv_param_t::recv_attr, it indicates the required receive buffer size for initiating rendezvous protocol.
[in]paramData receive parameters.
Returns
UCS_OK data will not persist after the callback returns. If UCP_AM_RECV_ATTR_FLAG_RNDV flag is set in param->recv_attr and ucp_am_recv_data_nbx was not called for this data, the data descriptor will be dropped and the corresponding ucp_am_send_nbx call will complete with UCS_OK status.
UCS_INPROGRESS Can only be returned if param->recv_attr flags contains UCP_AM_RECV_ATTR_FLAG_DATA or UCP_AM_RECV_ATTR_FLAG_RNDV. The data will persist after the callback has returned. To free the memory, a pointer to the data must be passed into ucp_am_data_release or data receive is initiated by ucp_am_recv_data_nbx.
otherwise Can only be returned if param->recv_attr contains UCP_AM_RECV_ATTR_FLAG_RNDV. In this case data descriptor data will be dropped and the corresponding ucp_am_send_nbx call on the sender side will complete with the status returned from the callback.
Note
This callback should be set and released by ucp_worker_set_am_recv_handler function.

◆ ucp_ep_params_t

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

Enumeration Type Documentation

◆ ucp_ep_params_field

The enumeration allows specifying which fields in ucp_ep_params_t are present. It is used to enable backward compatibility support.

Enumerator
UCP_EP_PARAM_FIELD_REMOTE_ADDRESS 

Address of remote peer

UCP_EP_PARAM_FIELD_ERR_HANDLING_MODE 

Error handling mode. ucp_err_handling_mode_t

UCP_EP_PARAM_FIELD_ERR_HANDLER 

Handler to process transport level errors

UCP_EP_PARAM_FIELD_USER_DATA 

User data pointer

UCP_EP_PARAM_FIELD_SOCK_ADDR 

Socket address field

UCP_EP_PARAM_FIELD_FLAGS 

Endpoint flags Connection request field

UCP_EP_PARAM_FIELD_CONN_REQUEST 
UCP_EP_PARAM_FIELD_NAME 

Endpoint name

UCP_EP_PARAM_FIELD_LOCAL_SOCK_ADDR 

Local socket Address

◆ ucp_ep_params_flags_field

The enumeration list describes the endpoint's parameters flags supported by ucp_ep_create() function.

Enumerator
UCP_EP_PARAMS_FLAGS_CLIENT_SERVER 

Using a client-server connection establishment mechanism. ucs_sock_addr_t sockaddr field must be provided and contain the address of the remote peer

UCP_EP_PARAMS_FLAGS_NO_LOOPBACK 

Avoid connecting the endpoint to itself when connecting the endpoint to the same worker it was created on. Affects protocols which send to a particular remote endpoint, for example stream

UCP_EP_PARAMS_FLAGS_SEND_CLIENT_ID 

Send client id when connecting to remote socket address as part of the connection request payload. On the remote side value can be obtained from ucp_conn_request_h using ucp_conn_request_query

◆ ucp_ep_close_flags_t

The enumeration is used to specify the behavior of ucp_ep_close_nbx.

Enumerator
UCP_EP_CLOSE_FLAG_FORCE 

ucp_ep_close_nbx releases the endpoint without any confirmation from the peer. All outstanding requests will be completed with UCS_ERR_CANCELED error.

Note
This mode may cause transport level errors on remote side, so it requires set UCP_ERR_HANDLING_MODE_PEER for all endpoints created on both (local and remote) sides to avoid undefined behavior. If this flag is not set then ucp_ep_close_nbx schedules flushes on all outstanding operations.
this flag is incompatible with UCP_OP_ATTR_FLAG_NO_IMM_CMPL, since it forces immediate completion.

◆ ucp_ep_perf_param_field

The enumeration allows specifying which fields in ucp_ep_evaluate_perf_param_t are present and operation flags are used. It is used to enable backward compatibility support.

Enumerator
UCP_EP_PERF_PARAM_FIELD_MESSAGE_SIZE 

Enables ucp_ep_evaluate_perf_param_t::message_size

◆ ucp_ep_perf_attr_field

The enumeration allows specifying which fields in ucp_ep_evaluate_perf_attr_t are present and operation flags are used. It is used to enable backward compatibility support.

Enumerator
UCP_EP_PERF_ATTR_FIELD_ESTIMATED_TIME 

Enables ucp_ep_evaluate_perf_attr_t::estimated_time

◆ ucp_cb_param_flags

In a callback, if flags is set to UCP_CB_PARAM_FLAG_DATA in a callback then data was allocated, so if UCS_INPROGRESS is returned from the callback, the data parameter will persist and the user has to call ucp_am_data_release when data is no longer needed.

Enumerator
UCP_CB_PARAM_FLAG_DATA 

◆ ucp_ep_attr_field

The enumeration allows specifying which fields in ucp_ep_attr_t are present. It is used to enable backward compatibility support.

Enumerator
UCP_EP_ATTR_FIELD_NAME 

UCP endpoint name

UCP_EP_ATTR_FIELD_LOCAL_SOCKADDR 

Sockaddr used by the endpoint

UCP_EP_ATTR_FIELD_REMOTE_SOCKADDR 

Sockaddr the endpoint is connected to

UCP_EP_ATTR_FIELD_TRANSPORTS 

Transport and device used by endpoint

◆ ucp_ep_close_mode

Deprecated:
Use ucp_ep_close_nbx and ucp_ep_close_flags_t instead.

The enumeration is used to specify the behavior of ucp_ep_close_nb.

Enumerator
UCP_EP_CLOSE_MODE_FORCE 

ucp_ep_close_nb releases the endpoint without any confirmation from the peer. All outstanding requests will be completed with UCS_ERR_CANCELED error.

Note
This mode may cause transport level errors on remote side, so it requires set UCP_ERR_HANDLING_MODE_PEER for all endpoints created on both (local and remote) sides to avoid undefined behavior.
UCP_EP_CLOSE_MODE_FLUSH 

ucp_ep_close_nb schedules flushes on all outstanding operations.

◆ ucp_err_handling_mode_t

Specifies error handling mode for the UCP endpoint.

Enumerator
UCP_ERR_HANDLING_MODE_NONE 

No guarantees about error reporting, imposes minimal overhead from a performance perspective.

Note
In this mode, any error reporting will not generate calls to ucp_ep_params_t::err_handler.
UCP_ERR_HANDLING_MODE_PEER 

Guarantees that send requests are always completed (successfully or error) even in case of remote failure, disables protocols and APIs which may cause a hang or undefined behavior in case of peer failure, may affect performance and memory footprint

Function Documentation

◆ ucp_ep_create()

ucs_status_t ucp_ep_create ( ucp_worker_h  worker,
const ucp_ep_params_t params,
ucp_ep_h ep_p 
)

This routine creates and connects an endpoint on a local worker for a destination address that identifies the remote worker. This function is non-blocking, and communications may begin immediately after it returns. If the connection process is not completed, communications may be delayed. The created endpoint is associated with one and only one worker.

Parameters
[in]workerHandle to the worker; the endpoint is associated with the worker.
[in]paramsUser defined ucp_ep_params_t configurations for the UCP endpoint.
[out]ep_pA handle to the created endpoint.
Returns
Error code as defined by ucs_status_t
Note
One of the following fields has to be specified:
By default, ucp_ep_create() will connect an endpoint to itself if the endpoint is destined to the same worker on which it was created, i.e. params.address belongs to worker. This behavior can be changed by passing the UCP_EP_PARAMS_FLAGS_NO_LOOPBACK flag in params.flags. In that case, the endpoint will be connected to the next endpoint created in the same way on the same worker.
Examples
ucp_client_server.c, and ucp_hello_world.c.

◆ ucp_ep_close_nbx()

ucs_status_ptr_t ucp_ep_close_nbx ( ucp_ep_h  ep,
const ucp_request_param_t param 
)
Parameters
[in]epHandle to the endpoint to close.
[in]paramOperation parameters, see ucp_request_param_t. This operation supports specific flags, which can be passed in param by ucp_request_param_t::flags. The exact set of flags is defined by ucp_ep_close_flags_t.
Returns
NULL - The endpoint is closed successfully.
UCS_PTR_IS_ERR(_ptr) - The closure failed and an error code indicates the transport level status. However, resources are released and the endpoint can no longer be used.
otherwise - The closure process is started, and can be completed at any point in time. A request handle is returned to the application in order to track progress of the endpoint closure.

◆ ucp_ep_print_info()

void ucp_ep_print_info ( ucp_ep_h  ep,
FILE *  stream 
)

This routine prints information about the endpoint transport methods, their thresholds, and other useful information associated with the endpoint.

Parameters
[in]epEndpoint object whose configuration to print.
[in]streamOutput stream to print the information to.

◆ ucp_ep_flush_nbx()

ucs_status_ptr_t ucp_ep_flush_nbx ( ucp_ep_h  ep,
const ucp_request_param_t param 
)

This routine flushes all outstanding AMO and RMA communications on the endpoint. All the AMO and RMA operations issued on the ep prior to this call are completed both at the origin and at the target endpoint when this call returns.

Parameters
[in]epUCP endpoint.
[in]paramOperation parameters, see ucp_request_param_t.
Returns
NULL - The flush operation was completed immediately.
UCS_PTR_IS_ERR(_ptr) - The flush operation failed.
otherwise - Flush operation was scheduled and can be completed in any point in time. The request handle is returned to the application in order to track progress.

The following example demonstrates how blocking flush can be implemented using non-blocking flush:

ucs_status_t blocking_ep_flush(ucp_ep_h ep, ucp_worker_h worker)
{
void *request;
param.op_attr_mask = 0;
request = ucp_ep_flush_nbx(ep, &param);
if (request == NULL) {
return UCS_OK;
} else if (UCS_PTR_IS_ERR(request)) {
return UCS_PTR_STATUS(request);
} else {
ucs_status_t status;
do {
status = ucp_request_check_status(request);
} while (status == UCS_INPROGRESS);
ucp_request_free(request);
return status;
}
}
void ucp_request_free(void *request)
Release a communications request.
ucs_status_t ucp_request_check_status(void *request)
Check the status of non-blocking request.
uint32_t op_attr_mask
Definition ucp.h:1747
Operation parameters passed to ucp_tag_send_nbx, ucp_tag_send_sync_nbx, ucp_tag_recv_nbx,...
Definition ucp.h:1741
ucs_status_ptr_t ucp_ep_flush_nbx(ucp_ep_h ep, const ucp_request_param_t *param)
Non-blocking flush of outstanding AMO and RMA operations on the endpoint.
unsigned ucp_worker_progress(ucp_worker_h worker)
Progress all communications on a specific worker.
struct ucp_worker * ucp_worker_h
UCP Worker.
Definition ucp_def.h:246
@ UCS_INPROGRESS
Definition status.h:50
Examples
ucp_hello_world.c.

◆ ucp_ep_evaluate_perf()

ucs_status_t ucp_ep_evaluate_perf ( ucp_ep_h  ep,
const ucp_ep_evaluate_perf_param_t param,
ucp_ep_evaluate_perf_attr_t attr 
)

This routine fetches information about the endpoint.

Parameters
[in]epEndpoint to query.
[in]paramFilled by the user with request params.
[out]attrFilled with performance estimation of the given operation on the endpoint.
Returns
Error code as defined by ucs_status_t

◆ ucp_ep_query()

ucs_status_t ucp_ep_query ( ucp_ep_h  ep,
ucp_ep_attr_t attr 
)

This routine fetches information about the endpoint.

Parameters
[in]epEndpoint object to query.
[out]attrFilled with attributes of the endpoint.
Returns
Error code as defined by ucs_status_t

◆ ucp_request_release()

void ucp_request_release ( void *  request)

◆ ucp_ep_destroy()

void ucp_ep_destroy ( ucp_ep_h  ep)

◆ ucp_disconnect_nb()

ucs_status_ptr_t ucp_disconnect_nb ( ucp_ep_h  ep)

◆ ucp_request_test()

ucs_status_t ucp_request_test ( void *  request,
ucp_tag_recv_info_t info 
)
Deprecated:
Replaced by ucp_tag_recv_request_test and ucp_request_check_status depends on use case.
Note
Please use ucp_request_check_status for cases that only need to check the completion status of an outstanding request. ucp_request_check_status can be used for any type of request. ucp_tag_recv_request_test should only be used for requests returned by ucp_tag_recv_nb (or request allocated by user for ucp_tag_recv_nbr) for which additional information (returned via the info pointer) is needed.

◆ ucp_ep_flush()

ucs_status_t ucp_ep_flush ( ucp_ep_h  ep)

◆ ucp_ep_modify_nb()

ucs_status_ptr_t ucp_ep_modify_nb ( ucp_ep_h  ep,
const ucp_ep_params_t params 
)
Deprecated:
Use ucp_listener_conn_handler_t instead of ucp_listener_accept_handler_t, if you have other use case please submit an issue on https://github.com/openucx/ucx or report to ucx-g.nosp@m.roup.nosp@m.@elis.nosp@m.t.or.nosp@m.nl.go.nosp@m.v

This routine modifies endpoint created by ucp_ep_create or ucp_listener_accept_callback_t. For example, this API can be used to setup custom parameters like ucp_ep_params_t::user_data or ucp_ep_params_t::err_handler to endpoint created by ucp_listener_accept_callback_t.

Parameters
[in]epA handle to the endpoint.
[in]paramsUser defined ucp_ep_params_t configurations for the UCP endpoint.
Returns
NULL - The endpoint is modified successfully.
UCS_PTR_IS_ERR(_ptr) - The reconfiguration failed and an error code indicates the status. However, the endpoint is not modified and can be used further.
otherwise - The reconfiguration process is started, and can be completed at any point in time. A request handle is returned to the application in order to track progress of the endpoint modification. The application is responsible for releasing the handle using the ucp_request_free routine.
Note
See the documentation of ucp_ep_params_t for details, only some of the parameters can be modified.

◆ ucp_ep_close_nb()

ucs_status_ptr_t ucp_ep_close_nb ( ucp_ep_h  ep,
unsigned  mode 
)
Deprecated:
Use ucp_ep_close_nbx instead.

This routine releases the endpoint. The endpoint closure process depends on the selected mode.

Parameters
[in]epHandle to the endpoint to close.
[in]modeOne from ucp_ep_close_mode value.
Returns
UCS_OK - The endpoint is closed successfully.
UCS_PTR_IS_ERR(_ptr) - The closure failed and an error code indicates the transport level status. However, resources are released and the endpoint can no longer be used.
otherwise - The closure process is started, and can be completed at any point in time. A request handle is returned to the application in order to track progress of the endpoint closure. The application is responsible for releasing the handle using the ucp_request_free routine.
Note
ucp_ep_close_nb replaces deprecated ucp_disconnect_nb and ucp_ep_destroy

◆ ucp_ep_flush_nb()

ucs_status_ptr_t ucp_ep_flush_nb ( ucp_ep_h  ep,
unsigned  flags,
ucp_send_callback_t  cb 
)
Deprecated:
Use ucp_ep_flush_nbx instead.

This routine flushes all outstanding AMO and RMA communications on the endpoint. All the AMO and RMA operations issued on the ep prior to this call are completed both at the origin and at the target endpoint when this call returns.

Parameters
[in]epUCP endpoint.
[in]flagsFlags for flush operation. Reserved for future use.
[in]cbCallback which will be called when the flush operation completes.
Returns
NULL - The flush operation was completed immediately.
UCS_PTR_IS_ERR(_ptr) - The flush operation failed.
otherwise - Flush operation was scheduled and can be completed in any point in time. The request handle is returned to the application in order to track progress. The application is responsible for releasing the handle using ucp_request_free() routine.