Threading and synchronization utilities

libuv provides cross-platform implementations for multiple threading and synchronization primitives. The API largely follows the pthreads API.

Data types

uv_thread_t

Thread data type.

void (*uv_thread_cb)(void* arg)

Callback that is invoked to initialize thread execution. arg is the same value that was passed to uv_thread_create().

uv_key_t

Thread-local key data type.

uv_once_t

Once-only initializer data type.

uv_mutex_t

Mutex data type.

uv_rwlock_t

Read-write lock data type.

uv_sem_t

Semaphore data type.

uv_cond_t

Condition data type.

uv_barrier_t

Barrier data type.

API

Threads

int uv_thread_create(uv_thread_t* tid, uv_thread_cb entry, void* arg)

Changed in version 1.4.1: returns a UV_E* error code on failure

uv_thread_t uv_thread_self(void)

int uv_thread_join(uv_thread_t *tid)

int uv_thread_equal(const uv_thread_t* t1, const uv_thread_t* t2)

Thread-local storage

Note

The total thread-local storage size may be limited. That is, it may not be possible to create many TLS keys.

int uv_key_create(uv_key_t* key)

void uv_key_delete(uv_key_t* key)

void* uv_key_get(uv_key_t* key)

void uv_key_set(uv_key_t* key, void* value)

Once-only initialization

Runs a function once and only once. Concurrent calls to uv_once() with the same guard will block all callers except one (it’s unspecified which one). The guard should be initialized statically with the UV_ONCE_INIT macro.

void uv_once(uv_once_t* guard, void (*callback)(void))

Mutex locks

Functions return 0 on success or an error code < 0 (unless the return type is void, of course).

int uv_mutex_init(uv_mutex_t* handle)

void uv_mutex_destroy(uv_mutex_t* handle)

void uv_mutex_lock(uv_mutex_t* handle)

int uv_mutex_trylock(uv_mutex_t* handle)

void uv_mutex_unlock(uv_mutex_t* handle)

Read-write locks

Functions return 0 on success or an error code < 0 (unless the return type is void, of course).

int uv_rwlock_init(uv_rwlock_t* rwlock)

void uv_rwlock_destroy(uv_rwlock_t* rwlock)

void uv_rwlock_rdlock(uv_rwlock_t* rwlock)

int uv_rwlock_tryrdlock(uv_rwlock_t* rwlock)

void uv_rwlock_rdunlock(uv_rwlock_t* rwlock)

void uv_rwlock_wrlock(uv_rwlock_t* rwlock)

int uv_rwlock_trywrlock(uv_rwlock_t* rwlock)

void uv_rwlock_wrunlock(uv_rwlock_t* rwlock)

Semaphores

Functions return 0 on success or an error code < 0 (unless the return type is void, of course).

int uv_sem_init(uv_sem_t* sem, unsigned int value)

void uv_sem_destroy(uv_sem_t* sem)

void uv_sem_post(uv_sem_t* sem)

void uv_sem_wait(uv_sem_t* sem)

int uv_sem_trywait(uv_sem_t* sem)

Conditions

Functions return 0 on success or an error code < 0 (unless the return type is void, of course).

Note

Callers should be prepared to deal with spurious wakeups on uv_cond_wait() and uv_cond_timedwait().

int uv_cond_init(uv_cond_t* cond)

void uv_cond_destroy(uv_cond_t* cond)

void uv_cond_signal(uv_cond_t* cond)

void uv_cond_broadcast(uv_cond_t* cond)

void uv_cond_wait(uv_cond_t* cond, uv_mutex_t* mutex)

int uv_cond_timedwait(uv_cond_t* cond, uv_mutex_t* mutex, uint64_t timeout)

Barriers

Functions return 0 on success or an error code < 0 (unless the return type is void, of course).

Note

uv_barrier_wait() returns a value > 0 to an arbitrarily chosen “serializer” thread to facilitate cleanup, i.e.

if (uv_barrier_wait(&barrier) > 0)
    uv_barrier_destroy(&barrier);

int uv_barrier_init(uv_barrier_t* barrier, unsigned int count)

void uv_barrier_destroy(uv_barrier_t* barrier)

int uv_barrier_wait(uv_barrier_t* barrier)