|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. _threading:
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Threading and synchronization utilities
|
|
Packit |
b5b901 |
=======================================
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
libuv provides cross-platform implementations for multiple threading and
|
|
Packit |
b5b901 |
synchronization primitives. The API largely follows the pthreads API.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Data types
|
|
Packit |
b5b901 |
----------
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_thread_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Thread data type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: void (*uv_thread_cb)(void* arg)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Callback that is invoked to initialize thread execution. `arg` is the same
|
|
Packit |
b5b901 |
value that was passed to :c:func:`uv_thread_create`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_key_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Thread-local key data type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_once_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Once-only initializer data type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_mutex_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Mutex data type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_rwlock_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Read-write lock data type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_sem_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Semaphore data type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_cond_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Condition data type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_barrier_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Barrier data type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
API
|
|
Packit |
b5b901 |
---
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Threads
|
|
Packit |
b5b901 |
^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit Service |
e08953 |
.. c:type:: uv_thread_options_t
|
|
Packit Service |
e08953 |
|
|
Packit Service |
e08953 |
Options for spawning a new thread (passed to :c:func:`uv_thread_create_ex`).
|
|
Packit Service |
e08953 |
|
|
Packit Service |
e08953 |
::
|
|
Packit Service |
e08953 |
|
|
Packit Service |
e08953 |
typedef struct uv_thread_options_s {
|
|
Packit Service |
e08953 |
enum {
|
|
Packit Service |
e08953 |
UV_THREAD_NO_FLAGS = 0x00,
|
|
Packit Service |
e08953 |
UV_THREAD_HAS_STACK_SIZE = 0x01
|
|
Packit Service |
e08953 |
} flags;
|
|
Packit Service |
e08953 |
size_t stack_size;
|
|
Packit Service |
e08953 |
} uv_thread_options_t;
|
|
Packit Service |
e08953 |
|
|
Packit Service |
e08953 |
More fields may be added to this struct at any time, so its exact
|
|
Packit Service |
e08953 |
layout and size should not be relied upon.
|
|
Packit Service |
e08953 |
|
|
Packit Service |
e08953 |
.. versionadded:: 1.26.0
|
|
Packit Service |
e08953 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_thread_create(uv_thread_t* tid, uv_thread_cb entry, void* arg)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. versionchanged:: 1.4.1 returns a UV_E* error code on failure
|
|
Packit |
b5b901 |
|
|
Packit Service |
e08953 |
.. c:function:: int uv_thread_create_ex(uv_thread_t* tid, const uv_thread_options_t* params, uv_thread_cb entry, void* arg)
|
|
Packit Service |
e08953 |
|
|
Packit Service |
e08953 |
Like :c:func:`uv_thread_create`, but additionally specifies options for creating a new thread.
|
|
Packit Service |
e08953 |
|
|
Packit Service |
e08953 |
If `UV_THREAD_HAS_STACK_SIZE` is set, `stack_size` specifies a stack size for the new thread.
|
|
Packit Service |
e08953 |
`0` indicates that the default value should be used, i.e. behaves as if the flag was not set.
|
|
Packit Service |
e08953 |
Other values will be rounded up to the nearest page boundary.
|
|
Packit Service |
e08953 |
|
|
Packit Service |
e08953 |
.. versionadded:: 1.26.0
|
|
Packit Service |
e08953 |
|
|
Packit |
b5b901 |
.. c:function:: uv_thread_t uv_thread_self(void)
|
|
Packit |
b5b901 |
.. c:function:: int uv_thread_join(uv_thread_t *tid)
|
|
Packit |
b5b901 |
.. c:function:: int uv_thread_equal(const uv_thread_t* t1, const uv_thread_t* t2)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Thread-local storage
|
|
Packit |
b5b901 |
^^^^^^^^^^^^^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note::
|
|
Packit |
b5b901 |
The total thread-local storage size may be limited. That is, it may not be possible to
|
|
Packit |
b5b901 |
create many TLS keys.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_key_create(uv_key_t* key)
|
|
Packit |
b5b901 |
.. c:function:: void uv_key_delete(uv_key_t* key)
|
|
Packit |
b5b901 |
.. c:function:: void* uv_key_get(uv_key_t* key)
|
|
Packit |
b5b901 |
.. c:function:: void uv_key_set(uv_key_t* key, void* value)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Once-only initialization
|
|
Packit |
b5b901 |
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Runs a function once and only once. Concurrent calls to :c:func:`uv_once` with the
|
|
Packit |
b5b901 |
same guard will block all callers except one (it's unspecified which one).
|
|
Packit |
b5b901 |
The guard should be initialized statically with the UV_ONCE_INIT macro.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: void uv_once(uv_once_t* guard, void (*callback)(void))
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Mutex locks
|
|
Packit |
b5b901 |
^^^^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Functions return 0 on success or an error code < 0 (unless the
|
|
Packit |
b5b901 |
return type is void, of course).
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_mutex_init(uv_mutex_t* handle)
|
|
Packit |
b5b901 |
.. c:function:: int uv_mutex_init_recursive(uv_mutex_t* handle)
|
|
Packit |
b5b901 |
.. c:function:: void uv_mutex_destroy(uv_mutex_t* handle)
|
|
Packit |
b5b901 |
.. c:function:: void uv_mutex_lock(uv_mutex_t* handle)
|
|
Packit |
b5b901 |
.. c:function:: int uv_mutex_trylock(uv_mutex_t* handle)
|
|
Packit |
b5b901 |
.. c:function:: void uv_mutex_unlock(uv_mutex_t* handle)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Read-write locks
|
|
Packit |
b5b901 |
^^^^^^^^^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Functions return 0 on success or an error code < 0 (unless the
|
|
Packit |
b5b901 |
return type is void, of course).
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_rwlock_init(uv_rwlock_t* rwlock)
|
|
Packit |
b5b901 |
.. c:function:: void uv_rwlock_destroy(uv_rwlock_t* rwlock)
|
|
Packit |
b5b901 |
.. c:function:: void uv_rwlock_rdlock(uv_rwlock_t* rwlock)
|
|
Packit |
b5b901 |
.. c:function:: int uv_rwlock_tryrdlock(uv_rwlock_t* rwlock)
|
|
Packit |
b5b901 |
.. c:function:: void uv_rwlock_rdunlock(uv_rwlock_t* rwlock)
|
|
Packit |
b5b901 |
.. c:function:: void uv_rwlock_wrlock(uv_rwlock_t* rwlock)
|
|
Packit |
b5b901 |
.. c:function:: int uv_rwlock_trywrlock(uv_rwlock_t* rwlock)
|
|
Packit |
b5b901 |
.. c:function:: void uv_rwlock_wrunlock(uv_rwlock_t* rwlock)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Semaphores
|
|
Packit |
b5b901 |
^^^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Functions return 0 on success or an error code < 0 (unless the
|
|
Packit |
b5b901 |
return type is void, of course).
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_sem_init(uv_sem_t* sem, unsigned int value)
|
|
Packit |
b5b901 |
.. c:function:: void uv_sem_destroy(uv_sem_t* sem)
|
|
Packit |
b5b901 |
.. c:function:: void uv_sem_post(uv_sem_t* sem)
|
|
Packit |
b5b901 |
.. c:function:: void uv_sem_wait(uv_sem_t* sem)
|
|
Packit |
b5b901 |
.. c:function:: int uv_sem_trywait(uv_sem_t* sem)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Conditions
|
|
Packit |
b5b901 |
^^^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Functions return 0 on success or an error code < 0 (unless the
|
|
Packit |
b5b901 |
return type is void, of course).
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note::
|
|
Packit |
b5b901 |
1. Callers should be prepared to deal with spurious wakeups on :c:func:`uv_cond_wait`
|
|
Packit |
b5b901 |
and :c:func:`uv_cond_timedwait`.
|
|
Packit |
b5b901 |
2. The timeout parameter for :c:func:`uv_cond_timedwait` is relative to the time
|
|
Packit |
b5b901 |
at which function is called.
|
|
Packit |
b5b901 |
3. On z/OS, the timeout parameter for :c:func:`uv_cond_timedwait` is converted to an
|
|
Packit |
b5b901 |
absolute system time at which the wait expires. If the current system clock time
|
|
Packit |
b5b901 |
passes the absolute time calculated before the condition is signaled, an ETIMEDOUT
|
|
Packit |
b5b901 |
error results. After the wait begins, the wait time is not affected by changes
|
|
Packit |
b5b901 |
to the system clock.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_cond_init(uv_cond_t* cond)
|
|
Packit |
b5b901 |
.. c:function:: void uv_cond_destroy(uv_cond_t* cond)
|
|
Packit |
b5b901 |
.. c:function:: void uv_cond_signal(uv_cond_t* cond)
|
|
Packit |
b5b901 |
.. c:function:: void uv_cond_broadcast(uv_cond_t* cond)
|
|
Packit |
b5b901 |
.. c:function:: void uv_cond_wait(uv_cond_t* cond, uv_mutex_t* mutex)
|
|
Packit |
b5b901 |
.. c:function:: int uv_cond_timedwait(uv_cond_t* cond, uv_mutex_t* mutex, uint64_t timeout)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Barriers
|
|
Packit |
b5b901 |
^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Functions return 0 on success or an error code < 0 (unless the
|
|
Packit |
b5b901 |
return type is void, of course).
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note::
|
|
Packit |
b5b901 |
:c:func:`uv_barrier_wait` returns a value > 0 to an arbitrarily chosen "serializer" thread
|
|
Packit |
b5b901 |
to facilitate cleanup, i.e.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
::
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
if (uv_barrier_wait(&barrier) > 0)
|
|
Packit |
b5b901 |
uv_barrier_destroy(&barrier);
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_barrier_init(uv_barrier_t* barrier, unsigned int count)
|
|
Packit |
b5b901 |
.. c:function:: void uv_barrier_destroy(uv_barrier_t* barrier)
|
|
Packit |
b5b901 |
.. c:function:: int uv_barrier_wait(uv_barrier_t* barrier)
|