UCT Active messages

Typedefs
typedef ucs_status_t(*	uct_am_callback_t) (void *arg, void *data, size_t length, unsigned flags)
	Callback to process incoming active message.
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.

Enumerations
enum	uct_msg_flags { UCT_SEND_FLAG_SIGNALED = UCS_BIT(0) , UCT_SEND_FLAG_PEER_CHECK = UCS_BIT(1) }
	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.
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.
void	uct_iface_release_desc (void *desc)
	Release AM descriptor.
ucs_status_t	uct_ep_am_short (uct_ep_h ep, uint8_t id, uint64_t header, const void *payload, unsigned length)
ucs_status_t	uct_ep_am_short_iov (uct_ep_h ep, uint8_t id, const uct_iov_t *iov, size_t iovcnt)
	Short io-vector send operation.
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.

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]	arg	User-defined argument.
[in]	data	Points to the received data. This may be a part of a descriptor which may be released later.
[in]	length	Length of data.
[in]	flags	Mask 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]	arg	User-defined argument.
[in]	type	Message type.
[in]	id	Active message id.
[in]	data	Points to the received data.
[in]	length	Length of data.
[out]	buffer	Filled with a debug information string.
[in]	max	Maximal length of the string.

Enumeration Type Documentation

uct_msg_flags

enum 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_SEND_FLAG_PEER_CHECK	Forces checking connectivity to a peer. If the connection is not alive, an error callback will be invoked. If the flag is not set, there is no guarantee that a connectivity error could be detected.

uct_am_trace_type

enum 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]	iface	Interface to set the active message handler for.
[in]	id	Active message id. Must be 0..UCT_AM_ID_MAX-1.
[in]	cb	Active message callback. NULL to clear.
[in]	arg	Active message argument.
[in]	flags	Required 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]	iface	Interface to set the active message tracer for.
[in]	tracer	Active message tracer. NULL to clear.
[in]	arg	Tracer 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]

desc

Descriptor 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 )

Examples

uct_hello_world.c.

uct_ep_am_short_iov()

ucs_status_t uct_ep_am_short_iov	(	uct_ep_h	ep,
		uint8_t	id,
		const uct_iov_t *	iov,
		size_t	iovcnt )

This routine sends a message using short protocol. The input data in iov array of uct_iov_t structures is sent to remote side to contiguous buffer keeping the order of the data in the array.

Parameters

[in]	ep	Destination endpoint handle.
[in]	id	Active message id. Must be in range 0..UCT_AM_ID_MAX-1.
[in]	iov	Points 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. stride and count fields in uct_iov_t structure are ignored in current implementation. The total size of the data buffers in the array is limited by uct_iface_attr::cap::am::max_short.
[in]	iovcnt	Size 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.

Returns

UCS_OK Operation completed successfully.

UCS_ERR_NO_RESOURCE Could not start the operation due to lack of send resources.

otherwise Error code.

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 )

Examples

uct_hello_world.c.

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]	ep	Destination endpoint handle.
[in]	id	Active message id. Must be in range 0..UCT_AM_ID_MAX-1.
[in]	header	Active message header.
[in]	header_length	Active message header length in bytes.
[in]	iov	Points 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]	iovcnt	Size 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]	flags	Active message flags, see uct_msg_flags.
[in]	comp	Completion 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.