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¶
-
uv_thread_options_t
¶ Options for spawning a new thread (passed to
uv_thread_create_ex()
).typedef struct uv_process_options_s { enum { UV_THREAD_NO_FLAGS = 0x00, UV_THREAD_HAS_STACK_SIZE = 0x01 } flags; size_t stack_size; } uv_process_options_t;
More fields may be added to this struct at any time, so its exact layout and size should not be relied upon.
1.26.0 新版功能.
-
int
uv_thread_create
(uv_thread_t* tid, uv_thread_cb entry, void* arg)¶ 在 1.4.1 版更改: returns a UV_E* error code on failure
-
int
uv_thread_create_ex
(uv_thread_t* tid, const uv_thread_options_t* params, uv_thread_cb entry, void* arg)¶ Like
uv_thread_create()
, but additionally specifies options for creating a new thread.If UV_THREAD_HAS_STACK_SIZE is set, stack_size specifies a stack size for the new thread. 0 indicates that the default value should be used, i.e. behaves as if the flag was not set. Other values will be rounded up to the nearest page boundary.
1.26.0 新版功能.
-
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¶
注解
The total thread-local storage size may be limited. That is, it may not be possible to create many TLS keys.
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.
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)¶
-
int
uv_mutex_init_recursive
(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).
Conditions¶
Functions return 0 on success or an error code < 0 (unless the return type is void, of course).
注解
- Callers should be prepared to deal with spurious wakeups on
uv_cond_wait()
anduv_cond_timedwait()
. - The timeout parameter for
uv_cond_timedwait()
is relative to the time at which function is called. - On z/OS, the timeout parameter for
uv_cond_timedwait()
is converted to an absolute system time at which the wait expires. If the current system clock time passes the absolute time calculated before the condition is signaled, an ETIMEDOUT error results. After the wait begins, the wait time is not affected by changes to the system clock.
-
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).
注解
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)¶