File callbackq.h¶

See file LICENSE for terms.

Defines

UCS_CALLBACKQ_FAST_COUNT¶

UCS_CALLBACKQ_ID_NULL¶

Typedefs

typedef struct ucs_callbackq ucs_callbackq_t¶

typedef struct ucs_callbackq_elem ucs_callbackq_elem_t¶

typedef unsigned (*ucs_callback_t)(void *arg)¶

Callback which can be placed in a queue.

Parameters: arg – [in] User-defined argument for the callback.
Returns: Count of how much “work” was done by the callback. For example, zero means that no work was done, and any nonzero value means that something was done.

typedef int (*ucs_callbackq_predicate_t)(const ucs_callbackq_elem_t *elem, void *arg)¶

Callback queue element predicate.

Parameters

elem – [in] Callback queue element to check.
arg – [in] User-defined argument.

Returns

Predicate result value - nonzero means “true”, zero means “false”.

Enums

enum ucs_callbackq_flags

Callback flags

Values:

enumerator UCS_CALLBACKQ_FLAG_FAST: Fast-path (best effort)

enumerator UCS_CALLBACKQ_FLAG_ONESHOT: Call the callback only once (cannot be used with FAST)

Functions

ucs_status_t ucs_callbackq_init(ucs_callbackq_t *cbq)¶

Initialize the callback queue.

Parameters: cbq – [in] Callback queue to initialize.

void ucs_callbackq_cleanup(ucs_callbackq_t *cbq)¶

Clean up the callback queue and release associated memory.

Parameters: cbq – [in] Callback queue to clean up.

int ucs_callbackq_add(ucs_callbackq_t *cbq, ucs_callback_t cb, void *arg, unsigned flags)¶

Add a callback to the queue. This is not safe to call while another thread might be dispatching callbacks. However, it can be used from the dispatch context (e.g a callback may use this function to add another callback).

Parameters

cbq – [in] Callback queue to add the callback to.
cb – [in] Callback to add.
arg – [in] User-defined argument for the callback.
flags – [in] Flags for the callback, from ucs_callbackq_flags.

Returns

Unique identifier of the callback in the queue.

void ucs_callbackq_remove(ucs_callbackq_t *cbq, int id)¶

Remove a callback from the queue immediately. This is not safe to call while another thread might be dispatching callbacks. However, it can be used from the dispatch context (e.g a callback may use this function to remove itself or another callback). In this case, the callback may still be dispatched once after this function returned.

Parameters

cbq – [in] Callback queue to remove the callback from.
id – [in] Callback identifier to remove.

int ucs_callbackq_add_safe(ucs_callbackq_t *cbq, ucs_callback_t cb, void *arg, unsigned flags)¶

Add a callback to the queue. This can be used from any context and any thread, including but not limited to:

A callback can add another callback.
A thread can add a callback while another thread is dispatching callbacks.

Parameters

cbq – [in] Callback queue to add the callback to.
cb – [in] Callback to add.
arg – [in] User-defined argument for the callback.
flags – [in] Flags for the callback, from ucs_callbackq_flags.

Returns

Unique identifier of the callback in the queue.

void ucs_callbackq_remove_safe(ucs_callbackq_t *cbq, int id)¶

Remove a callback from the queue in a safe but lazy fashion. The callback will be removed at some point in the near future. This can be used from any context and any thread, including but not limited to:

A callback can remove another callback or itself.
A thread can’t remove a callback while another thread is dispatching callbacks.

Parameters

cbq – [in] Callback queue to remove the callback from.
id – [in] Callback identifier to remove.

void ucs_callbackq_remove_if(ucs_callbackq_t *cbq, ucs_callbackq_predicate_t pred, void *arg)¶

Remove all callbacks from the queue for which the given predicate returns “true” (nonzero) value. This is not safe to call while another thread might be dispatching callbacks. However, it can be used from the dispatch context (e.g a callback may use this function to remove itself or another callback). In this case, the callback may still be dispatched once after this function returned.

Parameters

cbq – [in] Callback queue.
pred – [in] Predicate to check candidates for removal.
arg – [in] User-defined argument for the predicate.

static inline unsigned ucs_callbackq_dispatch(ucs_callbackq_t *cbq)¶

Dispatch callbacks from the callback queue. Must be called from single thread only.

Parameters: cbq – [in] Callback queue to dispatch callbacks from.
Returns: Sum of all return values from the dispatched callbacks.

struct ucs_callbackq_elem¶

#include <callbackq.h>

Callback queue element.

Public Members

ucs_callback_t cb¶: Callback function

void *arg¶: Function argument

unsigned flags¶: Callback flags

int id¶: Callback id

struct ucs_callbackq¶

#include <callbackq.h>

A queue of callback to execute

Public Members

ucs_callbackq_elem_t fast_elems[UCS_CALLBACKQ_FAST_COUNT + 1]¶: Array of fast-path element, the last is reserved as a sentinel to mark array end.

char priv[72]¶: Private data, which we don’t want to expose in API to avoid pulling more header files