1 2.. _threading: 3 4Threading and synchronization utilities 5======================================= 6 7libuv provides cross-platform implementations for multiple threading and 8synchronization primitives. The API largely follows the pthreads API. 9 10 11Data types 12---------- 13 14.. c:type:: uv_thread_t 15 16 Thread data type. 17 18.. c:type:: void (*uv_thread_cb)(void* arg) 19 20 Callback that is invoked to initialize thread execution. `arg` is the same 21 value that was passed to :c:func:`uv_thread_create`. 22 23.. c:type:: uv_key_t 24 25 Thread-local key data type. 26 27.. c:type:: uv_once_t 28 29 Once-only initializer data type. 30 31.. c:type:: uv_mutex_t 32 33 Mutex data type. 34 35.. c:type:: uv_rwlock_t 36 37 Read-write lock data type. 38 39.. c:type:: uv_sem_t 40 41 Semaphore data type. 42 43.. c:type:: uv_cond_t 44 45 Condition data type. 46 47.. c:type:: uv_barrier_t 48 49 Barrier data type. 50 51 52API 53--- 54 55Threads 56^^^^^^^ 57 58.. c:type:: uv_thread_options_t 59 60 Options for spawning a new thread (passed to :c:func:`uv_thread_create_ex`). 61 62 :: 63 64 typedef struct uv_thread_options_s { 65 enum { 66 UV_THREAD_NO_FLAGS = 0x00, 67 UV_THREAD_HAS_STACK_SIZE = 0x01 68 } flags; 69 size_t stack_size; 70 } uv_thread_options_t; 71 72 More fields may be added to this struct at any time, so its exact 73 layout and size should not be relied upon. 74 75 .. versionadded:: 1.26.0 76 77.. c:function:: int uv_thread_create(uv_thread_t* tid, uv_thread_cb entry, void* arg) 78 79 .. versionchanged:: 1.4.1 returns a UV_E* error code on failure 80 81.. c:function:: int uv_thread_create_ex(uv_thread_t* tid, const uv_thread_options_t* params, uv_thread_cb entry, void* arg) 82 83 Like :c:func:`uv_thread_create`, but additionally specifies options for creating a new thread. 84 85 If `UV_THREAD_HAS_STACK_SIZE` is set, `stack_size` specifies a stack size for the new thread. 86 `0` indicates that the default value should be used, i.e. behaves as if the flag was not set. 87 Other values will be rounded up to the nearest page boundary. 88 89 .. versionadded:: 1.26.0 90 91.. c:function:: uv_thread_t uv_thread_self(void) 92.. c:function:: int uv_thread_join(uv_thread_t *tid) 93.. c:function:: int uv_thread_equal(const uv_thread_t* t1, const uv_thread_t* t2) 94 95Thread-local storage 96^^^^^^^^^^^^^^^^^^^^ 97 98.. note:: 99 The total thread-local storage size may be limited. That is, it may not be possible to 100 create many TLS keys. 101 102.. c:function:: int uv_key_create(uv_key_t* key) 103.. c:function:: void uv_key_delete(uv_key_t* key) 104.. c:function:: void* uv_key_get(uv_key_t* key) 105.. c:function:: void uv_key_set(uv_key_t* key, void* value) 106 107Once-only initialization 108^^^^^^^^^^^^^^^^^^^^^^^^ 109 110Runs a function once and only once. Concurrent calls to :c:func:`uv_once` with the 111same guard will block all callers except one (it's unspecified which one). 112The guard should be initialized statically with the UV_ONCE_INIT macro. 113 114.. c:function:: void uv_once(uv_once_t* guard, void (*callback)(void)) 115 116Mutex locks 117^^^^^^^^^^^ 118 119Functions return 0 on success or an error code < 0 (unless the 120return type is void, of course). 121 122.. c:function:: int uv_mutex_init(uv_mutex_t* handle) 123.. c:function:: int uv_mutex_init_recursive(uv_mutex_t* handle) 124.. c:function:: void uv_mutex_destroy(uv_mutex_t* handle) 125.. c:function:: void uv_mutex_lock(uv_mutex_t* handle) 126.. c:function:: int uv_mutex_trylock(uv_mutex_t* handle) 127.. c:function:: void uv_mutex_unlock(uv_mutex_t* handle) 128 129Read-write locks 130^^^^^^^^^^^^^^^^ 131 132Functions return 0 on success or an error code < 0 (unless the 133return type is void, of course). 134 135.. c:function:: int uv_rwlock_init(uv_rwlock_t* rwlock) 136.. c:function:: void uv_rwlock_destroy(uv_rwlock_t* rwlock) 137.. c:function:: void uv_rwlock_rdlock(uv_rwlock_t* rwlock) 138.. c:function:: int uv_rwlock_tryrdlock(uv_rwlock_t* rwlock) 139.. c:function:: void uv_rwlock_rdunlock(uv_rwlock_t* rwlock) 140.. c:function:: void uv_rwlock_wrlock(uv_rwlock_t* rwlock) 141.. c:function:: int uv_rwlock_trywrlock(uv_rwlock_t* rwlock) 142.. c:function:: void uv_rwlock_wrunlock(uv_rwlock_t* rwlock) 143 144Semaphores 145^^^^^^^^^^ 146 147Functions return 0 on success or an error code < 0 (unless the 148return type is void, of course). 149 150.. c:function:: int uv_sem_init(uv_sem_t* sem, unsigned int value) 151.. c:function:: void uv_sem_destroy(uv_sem_t* sem) 152.. c:function:: void uv_sem_post(uv_sem_t* sem) 153.. c:function:: void uv_sem_wait(uv_sem_t* sem) 154.. c:function:: int uv_sem_trywait(uv_sem_t* sem) 155 156Conditions 157^^^^^^^^^^ 158 159Functions return 0 on success or an error code < 0 (unless the 160return type is void, of course). 161 162.. note:: 163 1. Callers should be prepared to deal with spurious wakeups on :c:func:`uv_cond_wait` 164 and :c:func:`uv_cond_timedwait`. 165 2. The timeout parameter for :c:func:`uv_cond_timedwait` is relative to the time 166 at which function is called. 167 3. On z/OS, the timeout parameter for :c:func:`uv_cond_timedwait` is converted to an 168 absolute system time at which the wait expires. If the current system clock time 169 passes the absolute time calculated before the condition is signaled, an ETIMEDOUT 170 error results. After the wait begins, the wait time is not affected by changes 171 to the system clock. 172 173.. c:function:: int uv_cond_init(uv_cond_t* cond) 174.. c:function:: void uv_cond_destroy(uv_cond_t* cond) 175.. c:function:: void uv_cond_signal(uv_cond_t* cond) 176.. c:function:: void uv_cond_broadcast(uv_cond_t* cond) 177.. c:function:: void uv_cond_wait(uv_cond_t* cond, uv_mutex_t* mutex) 178.. c:function:: int uv_cond_timedwait(uv_cond_t* cond, uv_mutex_t* mutex, uint64_t timeout) 179 180Barriers 181^^^^^^^^ 182 183Functions return 0 on success or an error code < 0 (unless the 184return type is void, of course). 185 186.. note:: 187 :c:func:`uv_barrier_wait` returns a value > 0 to an arbitrarily chosen "serializer" thread 188 to facilitate cleanup, i.e. 189 190 :: 191 192 if (uv_barrier_wait(&barrier) > 0) 193 uv_barrier_destroy(&barrier); 194 195.. c:function:: int uv_barrier_init(uv_barrier_t* barrier, unsigned int count) 196.. c:function:: void uv_barrier_destroy(uv_barrier_t* barrier) 197.. c:function:: int uv_barrier_wait(uv_barrier_t* barrier) 198