Mercurial

comparison third_party/libuv/docs/src/threading.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
1
2 .. _threading:
3
4 Threading and synchronization utilities
5 =======================================
6
7 libuv provides cross-platform implementations for multiple threading and
8 synchronization primitives. The API largely follows the pthreads API.
9
10
11 Data 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
52 API
53 ---
54
55 Threads
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_detach(uv_thread_t* tid)
82
83 Detaches a thread. Detached threads automatically release their
84 resources upon termination, eliminating the need for the application to
85 call `uv_thread_join`.
86
87 .. versionadded:: 1.50.0
88
89 .. c:function:: int uv_thread_create_ex(uv_thread_t* tid, const uv_thread_options_t* params, uv_thread_cb entry, void* arg)
90
91 Like :c:func:`uv_thread_create`, but additionally specifies options for creating a new thread.
92
93 If `UV_THREAD_HAS_STACK_SIZE` is set, `stack_size` specifies a stack size for the new thread.
94 `0` indicates that the default value should be used, i.e. behaves as if the flag was not set.
95 Other values will be rounded up to the nearest page boundary.
96
97 .. versionadded:: 1.26.0
98
99 .. c:function:: int uv_thread_setaffinity(uv_thread_t* tid, char* cpumask, char* oldmask, size_t mask_size)
100
101 Sets the specified thread's affinity to cpumask, which is specified in
102 bytes. Optionally returning the previous affinity setting in oldmask.
103 On Unix, uses :man:`pthread_getaffinity_np(3)` to get the affinity setting
104 and maps the cpu_set_t to bytes in oldmask. Then maps the bytes in cpumask
105 to a cpu_set_t and uses :man:`pthread_setaffinity_np(3)`. On Windows, maps
106 the bytes in cpumask to a bitmask and uses SetThreadAffinityMask() which
107 returns the previous affinity setting.
108
109 The mask_size specifies the number of entries (bytes) in cpumask / oldmask,
110 and must be greater-than-or-equal-to :c:func:`uv_cpumask_size`.
111
112 .. note::
113 Thread affinity setting is not atomic on Windows. Unsupported on macOS.
114
115 .. versionadded:: 1.45.0
116
117 .. c:function:: int uv_thread_getaffinity(uv_thread_t* tid, char* cpumask, size_t mask_size)
118
119 Gets the specified thread's affinity setting. On Unix, this maps the
120 cpu_set_t returned by :man:`pthread_getaffinity_np(3)` to bytes in cpumask.
121
122 The mask_size specifies the number of entries (bytes) in cpumask,
123 and must be greater-than-or-equal-to :c:func:`uv_cpumask_size`.
124
125 .. note::
126 Thread affinity getting is not atomic on Windows. Unsupported on macOS.
127
128 .. versionadded:: 1.45.0
129
130 .. c:function:: int uv_thread_getcpu(void)
131
132 Gets the CPU number on which the calling thread is running.
133
134 .. note::
135 Currently only implemented on Windows, Linux and FreeBSD.
136
137 .. versionadded:: 1.45.0
138
139 .. c:function:: uv_thread_t uv_thread_self(void)
140 .. c:function:: int uv_thread_join(uv_thread_t *tid)
141 .. c:function:: int uv_thread_equal(const uv_thread_t* t1, const uv_thread_t* t2)
142
143 .. c:function:: int uv_thread_setname(const char* name)
144
145 Sets the name of the current thread. Different platforms define different limits on the max number of characters
146 a thread name can be: Linux, IBM i (16), macOS (64), Windows (32767), and NetBSD (32), etc. `uv_thread_setname()`
147 will truncate it in case `name` is larger than the limit of the platform.
148
149 Not supported on Windows Server 2016, returns `UV_ENOSYS`.
150
151 .. versionadded:: 1.50.0
152
153 .. c:function:: int uv_thread_getname(uv_thread_t* tid, char* name, size_t* size)
154
155 Gets the name of the thread specified by `tid`. The thread name is copied, with the trailing NUL, into the buffer
156 pointed to by `name`. The `size` parameter specifies the size of the buffer pointed to by `name`.
157 The buffer should be large enough to hold the name of the thread plus the trailing NUL, or it will be truncated to fit
158 with the trailing NUL.
159
160 Not supported on Windows Server 2016, returns `UV_ENOSYS`.
161
162 .. versionadded:: 1.50.0
163
164 .. c:function:: int uv_thread_setpriority(uv_thread_t tid, int priority)
165
166 If the function succeeds, the return value is 0.
167 If the function fails, the return value is less than zero.
168 Sets the scheduling priority of the thread specified by tid. It requires elevated
169 privilege to set specific priorities on some platforms.
170 The priority can be set to the following constants. UV_THREAD_PRIORITY_HIGHEST,
171 UV_THREAD_PRIORITY_ABOVE_NORMAL, UV_THREAD_PRIORITY_NORMAL,
172 UV_THREAD_PRIORITY_BELOW_NORMAL, UV_THREAD_PRIORITY_LOWEST.
173
174 .. c:function:: int uv_thread_getpriority(uv_thread_t tid, int* priority)
175
176 If the function succeeds, the return value is 0.
177 If the function fails, the return value is less than zero.
178 Retrieves the scheduling priority of the thread specified by tid. The value in the
179 output parameter priority is platform dependent.
180 For Linux, when schedule policy is SCHED_OTHER (default), priority is 0.
181
182 Thread-local storage
183 ^^^^^^^^^^^^^^^^^^^^
184
185 .. note::
186 The total thread-local storage size may be limited. That is, it may not be possible to
187 create many TLS keys.
188
189 .. c:function:: int uv_key_create(uv_key_t* key)
190 .. c:function:: void uv_key_delete(uv_key_t* key)
191 .. c:function:: void* uv_key_get(uv_key_t* key)
192 .. c:function:: void uv_key_set(uv_key_t* key, void* value)
193
194 Once-only initialization
195 ^^^^^^^^^^^^^^^^^^^^^^^^
196
197 Runs a function once and only once. Concurrent calls to :c:func:`uv_once` with the
198 same guard will block all callers except one (it's unspecified which one).
199 The guard should be initialized statically with the UV_ONCE_INIT macro.
200
201 .. c:function:: void uv_once(uv_once_t* guard, void (*callback)(void))
202
203 Mutex locks
204 ^^^^^^^^^^^
205
206 Functions return 0 on success or an error code < 0 (unless the
207 return type is void, of course).
208
209 .. c:function:: int uv_mutex_init(uv_mutex_t* handle)
210 .. c:function:: int uv_mutex_init_recursive(uv_mutex_t* handle)
211 .. c:function:: void uv_mutex_destroy(uv_mutex_t* handle)
212 .. c:function:: void uv_mutex_lock(uv_mutex_t* handle)
213 .. c:function:: int uv_mutex_trylock(uv_mutex_t* handle)
214 .. c:function:: void uv_mutex_unlock(uv_mutex_t* handle)
215
216 Read-write locks
217 ^^^^^^^^^^^^^^^^
218
219 Functions return 0 on success or an error code < 0 (unless the
220 return type is void, of course).
221
222 .. c:function:: int uv_rwlock_init(uv_rwlock_t* rwlock)
223 .. c:function:: void uv_rwlock_destroy(uv_rwlock_t* rwlock)
224 .. c:function:: void uv_rwlock_rdlock(uv_rwlock_t* rwlock)
225 .. c:function:: int uv_rwlock_tryrdlock(uv_rwlock_t* rwlock)
226 .. c:function:: void uv_rwlock_rdunlock(uv_rwlock_t* rwlock)
227 .. c:function:: void uv_rwlock_wrlock(uv_rwlock_t* rwlock)
228 .. c:function:: int uv_rwlock_trywrlock(uv_rwlock_t* rwlock)
229 .. c:function:: void uv_rwlock_wrunlock(uv_rwlock_t* rwlock)
230
231 Semaphores
232 ^^^^^^^^^^
233
234 Functions return 0 on success or an error code < 0 (unless the
235 return type is void, of course).
236
237 .. c:function:: int uv_sem_init(uv_sem_t* sem, unsigned int value)
238 .. c:function:: void uv_sem_destroy(uv_sem_t* sem)
239 .. c:function:: void uv_sem_post(uv_sem_t* sem)
240 .. c:function:: void uv_sem_wait(uv_sem_t* sem)
241 .. c:function:: int uv_sem_trywait(uv_sem_t* sem)
242
243 Conditions
244 ^^^^^^^^^^
245
246 Functions return 0 on success or an error code < 0 (unless the
247 return type is void, of course).
248
249 .. note::
250 1. Callers should be prepared to deal with spurious wakeups on :c:func:`uv_cond_wait`
251 and :c:func:`uv_cond_timedwait`.
252 2. The timeout parameter for :c:func:`uv_cond_timedwait` is relative to the time
253 at which function is called.
254 3. On z/OS, the timeout parameter for :c:func:`uv_cond_timedwait` is converted to an
255 absolute system time at which the wait expires. If the current system clock time
256 passes the absolute time calculated before the condition is signaled, an ETIMEDOUT
257 error results. After the wait begins, the wait time is not affected by changes
258 to the system clock.
259
260 .. c:function:: int uv_cond_init(uv_cond_t* cond)
261 .. c:function:: void uv_cond_destroy(uv_cond_t* cond)
262 .. c:function:: void uv_cond_signal(uv_cond_t* cond)
263 .. c:function:: void uv_cond_broadcast(uv_cond_t* cond)
264 .. c:function:: void uv_cond_wait(uv_cond_t* cond, uv_mutex_t* mutex)
265 .. c:function:: int uv_cond_timedwait(uv_cond_t* cond, uv_mutex_t* mutex, uint64_t timeout)
266
267 Barriers
268 ^^^^^^^^
269
270 Functions return 0 on success or an error code < 0 (unless the
271 return type is void, of course).
272
273 .. note::
274 :c:func:`uv_barrier_wait` returns a value > 0 to an arbitrarily chosen "serializer" thread
275 to facilitate cleanup, i.e.
276
277 ::
278
279 if (uv_barrier_wait(&barrier) > 0)
280 uv_barrier_destroy(&barrier);
281
282 .. c:function:: int uv_barrier_init(uv_barrier_t* barrier, unsigned int count)
283 .. c:function:: void uv_barrier_destroy(uv_barrier_t* barrier)
284 .. c:function:: int uv_barrier_wait(uv_barrier_t* barrier)