UCX  1.8
Unified Communication X

Typedefs

typedef ucs_status_t(* uct_am_callback_t) (void *arg, void *data, size_t length, unsigned flags)
 Callback to process incoming active message. More...
 
typedef void(* uct_am_tracer_t) (void *arg, uct_am_trace_type_t type, uint8_t id, const void *data, size_t length, char *buffer, size_t max)
 Callback to trace active messages. More...
 

Enumerations

enum  uct_msg_flags { UCT_SEND_FLAG_SIGNALED = UCS_BIT(0) }
 Flags for active message send operation. More...
 
enum  uct_am_trace_type {
  UCT_AM_TRACE_TYPE_SEND, UCT_AM_TRACE_TYPE_RECV, UCT_AM_TRACE_TYPE_SEND_DROP, UCT_AM_TRACE_TYPE_RECV_DROP,
  UCT_AM_TRACE_TYPE_LAST
}
 Trace types for active message tracer. More...
 

Functions

ucs_status_t uct_iface_set_am_handler (uct_iface_h iface, uint8_t id, uct_am_callback_t cb, void *arg, uint32_t flags)
 Set active message handler for the interface. More...
 
ucs_status_t uct_iface_set_am_tracer (uct_iface_h iface, uct_am_tracer_t tracer, void *arg)
 Set active message tracer for the interface. More...
 
void uct_iface_release_desc (void *desc)
 Release AM descriptor. More...
 
ucs_status_t uct_ep_am_short (uct_ep_h ep, uint8_t id, uint64_t header, const void *payload, unsigned length)
 
ssize_t uct_ep_am_bcopy (uct_ep_h ep, uint8_t id, uct_pack_callback_t pack_cb, void *arg, unsigned flags)
 
ucs_status_t uct_ep_am_zcopy (uct_ep_h ep, uint8_t id, const void *header, unsigned header_length, const uct_iov_t *iov, size_t iovcnt, unsigned flags, uct_completion_t *comp)
 Send active message while avoiding local memory copy. More...
 

Detailed Description

Defines active message functions.

Typedef Documentation

◆ uct_am_callback_t

typedef ucs_status_t(* uct_am_callback_t) (void *arg, void *data, size_t length, unsigned flags)

When the callback is called, flags indicates how data should be handled. If flags contain UCT_CB_PARAM_FLAG_DESC value, it means data is part of a descriptor which must be released later by uct_iface_release_desc by the user if the callback returns UCS_INPROGRESS.

Parameters
[in]argUser-defined argument.
[in]dataPoints to the received data. This may be a part of a descriptor which may be released later.
[in]lengthLength of data.
[in]flagsMask with uct_cb_param_flags
Note
This callback could be set and released by uct_iface_set_am_handler function.
Return values
UCS_OK- descriptor was consumed, and can be released by the caller.
UCS_INPROGRESS- descriptor is owned by the callee, and would be released later. Supported only if flags contain UCT_CB_PARAM_FLAG_DESC value. Otherwise, this is an error.

◆ uct_am_tracer_t

typedef void(* uct_am_tracer_t) (void *arg, uct_am_trace_type_t type, uint8_t id, const void *data, size_t length, char *buffer, size_t max)

Writes a string which represents active message contents into 'buffer'.

Parameters
[in]argUser-defined argument.
[in]typeMessage type.
[in]idActive message id.
[in]dataPoints to the received data.
[in]lengthLength of data.
[out]bufferFilled with a debug information string.
[in]maxMaximal length of the string.

Enumeration Type Documentation

◆ uct_msg_flags

Enumerator
UCT_SEND_FLAG_SIGNALED 

Trigger UCT_EVENT_RECV_SIG event on remote side. Make best effort attempt to avoid triggering UCT_EVENT_RECV event. Ignored if not supported by interface.

◆ uct_am_trace_type

Enumerator
UCT_AM_TRACE_TYPE_SEND 
UCT_AM_TRACE_TYPE_RECV 
UCT_AM_TRACE_TYPE_SEND_DROP 
UCT_AM_TRACE_TYPE_RECV_DROP 
UCT_AM_TRACE_TYPE_LAST 

Function Documentation

◆ uct_iface_set_am_handler()

ucs_status_t uct_iface_set_am_handler ( uct_iface_h  iface,
uint8_t  id,
uct_am_callback_t  cb,
void *  arg,
uint32_t  flags 
)

Only one handler can be set of each active message ID, and setting a handler replaces the previous value. If cb == NULL, the current handler is removed.

Parameters
[in]ifaceInterface to set the active message handler for.
[in]idActive message id. Must be 0..UCT_AM_ID_MAX-1.
[in]cbActive message callback. NULL to clear.
[in]argActive message argument.
[in]flagsRequired callback flags
Returns
error code if the interface does not support active messages or requested callback flags
Examples
uct_hello_world.c.

◆ uct_iface_set_am_tracer()

ucs_status_t uct_iface_set_am_tracer ( uct_iface_h  iface,
uct_am_tracer_t  tracer,
void *  arg 
)

Sets a function which dumps active message debug information to a buffer, which is printed every time an active message is sent or received, when data tracing is on. Without the tracer, only transport-level information is printed.

Parameters
[in]ifaceInterface to set the active message tracer for.
[in]tracerActive message tracer. NULL to clear.
[in]argTracer custom argument.

◆ uct_iface_release_desc()

void uct_iface_release_desc ( void *  desc)

Release active message descriptor desc, which was passed to the active message callback, and owned by the callee.

Parameters
[in]descDescriptor to release.
Examples
uct_hello_world.c.

◆ uct_ep_am_short()

ucs_status_t uct_ep_am_short ( uct_ep_h  ep,
uint8_t  id,
uint64_t  header,
const void *  payload,
unsigned  length 
)

◆ uct_ep_am_bcopy()

ssize_t uct_ep_am_bcopy ( uct_ep_h  ep,
uint8_t  id,
uct_pack_callback_t  pack_cb,
void *  arg,
unsigned  flags 
)

◆ uct_ep_am_zcopy()

ucs_status_t uct_ep_am_zcopy ( uct_ep_h  ep,
uint8_t  id,
const void *  header,
unsigned  header_length,
const uct_iov_t iov,
size_t  iovcnt,
unsigned  flags,
uct_completion_t comp 
)

The input data in iov array of uct_iov_t structures sent to remote side ("gather output"). Buffers in iov are processed in array order. This means that the function complete iov[0] before proceeding to iov[1], and so on.

Parameters
[in]epDestination endpoint handle.
[in]idActive message id. Must be in range 0..UCT_AM_ID_MAX-1.
[in]headerActive message header.
[in]header_lengthActive message header length in bytes.
[in]iovPoints to an array of uct_iov_t structures. The iov pointer must be a valid address of an array of uct_iov_t structures. A particular structure pointer must be a valid address. A NULL terminated array is not required.
[in]iovcntSize of the iov data uct_iov_t structures array. If iovcnt is zero, the data is considered empty. iovcnt is limited by uct_iface_attr::cap::am::max_iov.
[in]flagsActive message flags, see uct_msg_flags.
[in]compCompletion handle as defined by uct_completion_t.
Returns
UCS_OK Operation completed successfully.
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_ERR_NO_RESOURCE Could not start the operation due to lack of send resources.
Note
If the operation returns UCS_INPROGRESS, the memory buffers pointed to by iov array must not be modified until the operation is completed by comp. header can be released or changed.
Examples
uct_hello_world.c.