Data Structures
struct	ucs_sock_addr

Typedefs
typedef void(*	ucs_async_event_cb_t) (int id, void *arg)

typedef struct ucs_sock_addr	ucs_sock_addr_t

typedef unsigned long	ucs_time_t

typedef void *	ucs_status_ptr_t
	Status pointer. More...

Enumerations
enum	ucs_callbackq_flags { UCS_CALLBACKQ_FLAG_FAST = UCS_BIT(0), UCS_CALLBACKQ_FLAG_ONESHOT = UCS_BIT(1) }

enum	ucs_status_t { UCS_OK = 0, UCS_INPROGRESS = 1, UCS_ERR_NO_MESSAGE = -1, UCS_ERR_NO_RESOURCE = -2, UCS_ERR_IO_ERROR = -3, UCS_ERR_NO_MEMORY = -4, UCS_ERR_INVALID_PARAM = -5, UCS_ERR_UNREACHABLE = -6, UCS_ERR_INVALID_ADDR = -7, UCS_ERR_NOT_IMPLEMENTED = -8, UCS_ERR_MESSAGE_TRUNCATED = -9, UCS_ERR_NO_PROGRESS = -10, UCS_ERR_BUFFER_TOO_SMALL = -11, UCS_ERR_NO_ELEM = -12, UCS_ERR_SOME_CONNECTS_FAILED = -13, UCS_ERR_NO_DEVICE = -14, UCS_ERR_BUSY = -15, UCS_ERR_CANCELED = -16, UCS_ERR_SHMEM_SEGMENT = -17, UCS_ERR_ALREADY_EXISTS = -18, UCS_ERR_OUT_OF_RANGE = -19, UCS_ERR_TIMED_OUT = -20, UCS_ERR_EXCEEDS_LIMIT = -21, UCS_ERR_UNSUPPORTED = -22, UCS_ERR_REJECTED = -23, UCS_ERR_FIRST_LINK_FAILURE = -40, UCS_ERR_LAST_LINK_FAILURE = -59, UCS_ERR_FIRST_ENDPOINT_FAILURE = -60, UCS_ERR_LAST_ENDPOINT_FAILURE = -79, UCS_ERR_ENDPOINT_TIMEOUT = -80, UCS_ERR_LAST = -100 }
	Status codes. More...

enum	ucs_thread_mode_t { UCS_THREAD_MODE_SINGLE, UCS_THREAD_MODE_SERIALIZED, UCS_THREAD_MODE_MULTI, UCS_THREAD_MODE_LAST }
	Thread sharing mode. More...

Functions
ucs_status_t	ucs_async_set_event_handler (ucs_async_mode_t mode, int event_fd, int events, ucs_async_event_cb_t cb, void arg, ucs_async_context_t async)

ucs_status_t	ucs_async_add_timer (ucs_async_mode_t mode, ucs_time_t interval, ucs_async_event_cb_t cb, void arg, ucs_async_context_t async, int *timer_id_p)

ucs_status_t	ucs_async_remove_handler (int id, int sync)

ucs_status_t	ucs_async_modify_handler (int fd, int events)

ucs_status_t	ucs_async_context_create (ucs_async_mode_t mode, ucs_async_context_t **async_p)
	Create an asynchronous execution context. More...

void	ucs_async_context_destroy (ucs_async_context_t *async)
	Destroy the asynchronous execution context. More...

void	ucs_async_poll (ucs_async_context_t *async)

Detailed Description

This section describes a concept of the Communication Resource and routines associated with the concept.

Data Structure Documentation

struct ucs_sock_addr

BSD socket address specification.

Data Fields
const struct sockaddr *	addr	Pointer to socket address
socklen_t	addrlen	Address length

Typedef Documentation

typedef void(* ucs_async_event_cb_t) (int id, void *arg)

Async event callback.

Parameters

id	Event id (timer or file descriptor).
arg	User-defined argument.

typedef struct ucs_sock_addr ucs_sock_addr_t

BSD socket address specification.

typedef unsigned long ucs_time_t

UCS time units. These are not necessarily aligned with metric time units. MUST compare short time values with UCS_SHORT_TIME_CMP to handle wrap-around.

typedef void* ucs_status_ptr_t

A pointer can represent one of these values:

NULL / UCS_OK
Error code pointer (UCS_ERR_xx)
Valid pointer

Enumeration Type Documentation

enum ucs_callbackq_flags

Callback flags

Enumerator
UCS_CALLBACKQ_FLAG_FAST	Fast-path (best effort)
UCS_CALLBACKQ_FLAG_ONESHOT	Call the callback only once (cannot be used with FAST)

enum ucs_status_t

Note: In order to evaluate the necessary steps to recover from a certain error, all error codes which can be returned by the external API are grouped by the largest entity permanently effected by the error. Each group ranges between its UCS_ERR_FIRST_<name> and UCS_ERR_LAST_<name> enum values. For example, if a link fails it may be sufficient to destroy (and possibly replace) it, in contrast to an endpoint-level error.

Enumerator
UCS_OK
UCS_INPROGRESS
UCS_ERR_NO_MESSAGE
UCS_ERR_NO_RESOURCE
UCS_ERR_IO_ERROR
UCS_ERR_NO_MEMORY
UCS_ERR_INVALID_PARAM
UCS_ERR_UNREACHABLE
UCS_ERR_INVALID_ADDR
UCS_ERR_NOT_IMPLEMENTED
UCS_ERR_MESSAGE_TRUNCATED
UCS_ERR_NO_PROGRESS
UCS_ERR_BUFFER_TOO_SMALL
UCS_ERR_NO_ELEM
UCS_ERR_SOME_CONNECTS_FAILED
UCS_ERR_NO_DEVICE
UCS_ERR_BUSY
UCS_ERR_CANCELED
UCS_ERR_SHMEM_SEGMENT
UCS_ERR_ALREADY_EXISTS
UCS_ERR_OUT_OF_RANGE
UCS_ERR_TIMED_OUT
UCS_ERR_EXCEEDS_LIMIT
UCS_ERR_UNSUPPORTED
UCS_ERR_REJECTED
UCS_ERR_FIRST_LINK_FAILURE
UCS_ERR_LAST_LINK_FAILURE
UCS_ERR_FIRST_ENDPOINT_FAILURE
UCS_ERR_LAST_ENDPOINT_FAILURE
UCS_ERR_ENDPOINT_TIMEOUT
UCS_ERR_LAST

enum ucs_thread_mode_t

Specifies thread sharing mode of an object.

Enumerator
UCS_THREAD_MODE_SINGLE	Only the master thread can access (i.e. the thread that initialized the context; multiple threads may exist and never access)
UCS_THREAD_MODE_SERIALIZED	Multiple threads can access, but only one at a time
UCS_THREAD_MODE_MULTI	Multiple threads can access concurrently
UCS_THREAD_MODE_LAST

Function Documentation

ucs_status_t ucs_async_set_event_handler	(	ucs_async_mode_t	mode,
		int	event_fd,
		int	events,
		ucs_async_event_cb_t	cb,
		void *	arg,
		ucs_async_context_t *	async
	)

Register a file descriptor for monitoring (call handler upon events). Every fd can have only one handler.

Parameters

mode	Thread or signal.
event_fd	File descriptor to set handler for.
events	Events to wait on (POLLxx/EPOLLxx bits).
cb	Callback function to execute.
arg	Argument to callback.
async	Async context to which events are delivered. If NULL, safety is up to the user.

Returns: Error code as defined by ucs_status_t.

ucs_status_t ucs_async_add_timer	(	ucs_async_mode_t	mode,
		ucs_time_t	interval,
		ucs_async_event_cb_t	cb,
		void *	arg,
		ucs_async_context_t *	async,
		int *	timer_id_p
	)

Add timer handler.

Parameters

mode	Thread or signal.
interval	Timer interval.
cb	Callback function to execute.
arg	Argument to callback.
async	Async context to which events are delivered. If NULL, safety is up to the user.
timer_id_p	Filled with timer id.

Returns: Error code as defined by ucs_status_t.

ucs_status_t ucs_async_remove_handler	(	int	id,
		int	sync
	)

Remove an event handler (Timer or event file).

Parameters

id	Timer/FD to remove.
sync	If nonzero, wait until the handler for this event is not running anymore. Cannot be used in the context of the event handler itself because it would deadlock.

Returns: Error code as defined by ucs_status_t.

ucs_status_t ucs_async_modify_handler	(	int	fd,
		int	events
	)

Modify events mask for an existing event handler (event file).

Parameters

fd	File descriptor modify events for.
events	New set of events to wait on (POLLxx/EPOLLxx bits).

Returns: Error code as defined by ucs_status_t.

ucs_status_t ucs_async_context_create	(	ucs_async_mode_t	mode,
		ucs_async_context_t **	async_p
	)

Allocate and initialize an asynchronous execution context. This can be used to ensure safe event delivery.

Parameters

mode	Either to use signals or epoll threads to wait.
async_p	Event context pointer to initialize.

Returns: Error code as defined by ucs_status_t.

Examples:: uct_hello_world.c.

void ucs_async_context_destroy ( ucs_async_context_t * async )

Clean up the async context, and release system resources if possible. The context memory released.

Parameters

async Asynchronous context to clean up.

Examples:: uct_hello_world.c.

void ucs_async_poll ( ucs_async_context_t * async )

Poll on async context.

Parameters

async Async context to poll on. NULL polls on all.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation