Blame docs/src/threading.rst

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)