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 struct ucs_callbackq_priv ucs_callbackq_priv_t¶

typedef void *ucs_callbackq_key_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”.

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

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.

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.

Returns

The user-defined argument provided when the callback was added.

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

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.

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.

Returns

The user-defined argument provided when the callback was added.

void ucs_callbackq_add_oneshot(ucs_callbackq_t *cbq, ucs_callbackq_key_t key, ucs_callback_t cb, void *arg)¶

Add a slowpath oneshot callback to the queue. This can be used from any context and any thread.

Parameters

cbq – [in] Callback queue to add the callback to.
key – [in] User-defind key, used to remove the callback later.
cb – [in] Callback to add.
arg – [in] User-defined argument for the callback.

Note

Callbacks with the same key will be called in the same order they were added. On the other hand, callbacks with different keys can be called in any order.

void ucs_callbackq_remove_oneshot(ucs_callbackq_t *cbq, ucs_callbackq_key_t key, ucs_callbackq_predicate_t pred, void *arg)¶

Remove all slowpath callbacks from the queue with the given key and for which the given predicate returns “true” (nonzero) value. This can be used from any context and any thread.

Parameters

cbq – [in] Callback queue.
key – [in] Callback key to remove.
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

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.

ucs_callbackq_priv_t *priv¶: Private data, which we don’t want to expose in API to avoid pulling more header files