uv_async_t — Async handle

Async handles allow the user to “wakeup” the event loop and get a callback called from another thread.

Note

uv_async_send() and the uv_async_cb invocation are sequentially consistent (seq_cst) operations for a given async handle: all memory accesses (reads and writes) made before uv_async_send() are visible to that callback.

Warning

libuv will coalesce calls to uv_async_send(), that is, not every call to it will yield an execution of the callback. For example: if uv_async_send() is called 5 times in a row before the callback is called, the callback will only be called once. If uv_async_send() is called again after the callback was called, it will be called again. However, since it is sequentially consistent, the values read or written in that callback will always be the same (or newer) as those read or written by the other thread.

Changed in version 1.53.0: uv_async_send() and uv_async_cb are sequentially consistent. Prior to this version, any case where libuv might coalesce calls probably requires a full seq_cst fence before it for correctness.

Data types

type uv_async_t

Async handle type.

typedef void (*uv_async_cb)(uv_async_t *handle)

Type definition for callback passed to uv_async_init().

Public members

N/A

See also

The uv_handle_t members also apply.

API

int uv_async_init(uv_loop_t *loop, uv_async_t *async, uv_async_cb async_cb)

Initialize the handle. A NULL callback is allowed.

Returns:

0 on success, or an error code < 0 on failure.

Note

Unlike other handle initialization functions, it immediately starts the handle.

int uv_async_send(uv_async_t *async)

Wake up the event loop and call the async handle’s callback.

Returns:

0 on success, or an error code < 0 on failure.

Note

It’s safe to call this function from any thread. The callback will be called on the loop thread.

Note

uv_async_send() is async-signal-safe. It’s safe to call this function from a signal handler.

Note

This is a full memory fence with respect to other calls and callbacks using this same async handle, and so it will order all operations around this call and the corresponding callback on the sending thread and receiving thread.

See also

The uv_handle_t API functions also apply.