1 | /* |
2 | Simple DirectMedia Layer |
3 | Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org> |
4 | |
5 | This software is provided 'as-is', without any express or implied |
6 | warranty. In no event will the authors be held liable for any damages |
7 | arising from the use of this software. |
8 | |
9 | Permission is granted to anyone to use this software for any purpose, |
10 | including commercial applications, and to alter it and redistribute it |
11 | freely, subject to the following restrictions: |
12 | |
13 | 1. The origin of this software must not be misrepresented; you must not |
14 | claim that you wrote the original software. If you use this software |
15 | in a product, an acknowledgment in the product documentation would be |
16 | appreciated but is not required. |
17 | 2. Altered source versions must be plainly marked as such, and must not be |
18 | misrepresented as being the original software. |
19 | 3. This notice may not be removed or altered from any source distribution. |
20 | */ |
21 | |
22 | #ifndef SDL_mutex_h_ |
23 | #define SDL_mutex_h_ |
24 | |
25 | /** |
26 | * \file SDL_mutex.h |
27 | * |
28 | * Functions to provide thread synchronization primitives. |
29 | */ |
30 | |
31 | #include "SDL_stdinc.h" |
32 | #include "SDL_error.h" |
33 | |
34 | /******************************************************************************/ |
35 | /* Enable thread safety attributes only with clang. |
36 | * The attributes can be safely erased when compiling with other compilers. |
37 | */ |
38 | #if defined(SDL_THREAD_SAFETY_ANALYSIS) && \ |
39 | defined(__clang__) && (!defined(SWIG)) |
40 | #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) |
41 | #else |
42 | #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) /* no-op */ |
43 | #endif |
44 | |
45 | #define SDL_CAPABILITY(x) \ |
46 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) |
47 | |
48 | #define SDL_SCOPED_CAPABILITY \ |
49 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) |
50 | |
51 | #define SDL_GUARDED_BY(x) \ |
52 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) |
53 | |
54 | #define SDL_PT_GUARDED_BY(x) \ |
55 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) |
56 | |
57 | #define SDL_ACQUIRED_BEFORE(x) \ |
58 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) |
59 | |
60 | #define SDL_ACQUIRED_AFTER(x) \ |
61 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) |
62 | |
63 | #define SDL_REQUIRES(x) \ |
64 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x)) |
65 | |
66 | #define SDL_REQUIRES_SHARED(x) \ |
67 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x)) |
68 | |
69 | #define SDL_ACQUIRE(x) \ |
70 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x)) |
71 | |
72 | #define SDL_ACQUIRE_SHARED(x) \ |
73 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x)) |
74 | |
75 | #define SDL_RELEASE(x) \ |
76 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x)) |
77 | |
78 | #define SDL_RELEASE_SHARED(x) \ |
79 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x)) |
80 | |
81 | #define SDL_RELEASE_GENERIC(x) \ |
82 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x)) |
83 | |
84 | #define SDL_TRY_ACQUIRE(x, y) \ |
85 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y)) |
86 | |
87 | #define SDL_TRY_ACQUIRE_SHARED(x, y) \ |
88 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y)) |
89 | |
90 | #define SDL_EXCLUDES(x) \ |
91 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) |
92 | |
93 | #define SDL_ASSERT_CAPABILITY(x) \ |
94 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) |
95 | |
96 | #define SDL_ASSERT_SHARED_CAPABILITY(x) \ |
97 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) |
98 | |
99 | #define SDL_RETURN_CAPABILITY(x) \ |
100 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) |
101 | |
102 | #define SDL_NO_THREAD_SAFETY_ANALYSIS \ |
103 | SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) |
104 | |
105 | /******************************************************************************/ |
106 | |
107 | |
108 | #include "begin_code.h" |
109 | /* Set up for C function definitions, even when using C++ */ |
110 | #ifdef __cplusplus |
111 | extern "C" { |
112 | #endif |
113 | |
114 | /** |
115 | * Synchronization functions which can time out return this value |
116 | * if they time out. |
117 | */ |
118 | #define SDL_MUTEX_TIMEDOUT 1 |
119 | |
120 | /** |
121 | * This is the timeout value which corresponds to never time out. |
122 | */ |
123 | #define SDL_MUTEX_MAXWAIT (~(Uint32)0) |
124 | |
125 | |
126 | /** |
127 | * \name Mutex functions |
128 | */ |
129 | /* @{ */ |
130 | |
131 | /* The SDL mutex structure, defined in SDL_sysmutex.c */ |
132 | struct SDL_mutex; |
133 | typedef struct SDL_mutex SDL_mutex; |
134 | |
135 | /** |
136 | * Create a new mutex. |
137 | * |
138 | * All newly-created mutexes begin in the _unlocked_ state. |
139 | * |
140 | * Calls to SDL_LockMutex() will not return while the mutex is locked by |
141 | * another thread. See SDL_TryLockMutex() to attempt to lock without blocking. |
142 | * |
143 | * SDL mutexes are reentrant. |
144 | * |
145 | * \returns the initialized and unlocked mutex or NULL on failure; call |
146 | * SDL_GetError() for more information. |
147 | * |
148 | * \since This function is available since SDL 2.0.0. |
149 | * |
150 | * \sa SDL_DestroyMutex |
151 | * \sa SDL_LockMutex |
152 | * \sa SDL_TryLockMutex |
153 | * \sa SDL_UnlockMutex |
154 | */ |
155 | extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); |
156 | |
157 | /** |
158 | * Lock the mutex. |
159 | * |
160 | * This will block until the mutex is available, which is to say it is in the |
161 | * unlocked state and the OS has chosen the caller as the next thread to lock |
162 | * it. Of all threads waiting to lock the mutex, only one may do so at a time. |
163 | * |
164 | * It is legal for the owning thread to lock an already-locked mutex. It must |
165 | * unlock it the same number of times before it is actually made available for |
166 | * other threads in the system (this is known as a "recursive mutex"). |
167 | * |
168 | * \param mutex the mutex to lock |
169 | * \return 0, or -1 on error. |
170 | * |
171 | * \since This function is available since SDL 2.0.0. |
172 | */ |
173 | extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex) SDL_ACQUIRE(mutex); |
174 | #define SDL_mutexP(m) SDL_LockMutex(m) |
175 | |
176 | /** |
177 | * Try to lock a mutex without blocking. |
178 | * |
179 | * This works just like SDL_LockMutex(), but if the mutex is not available, |
180 | * this function returns `SDL_MUTEX_TIMEOUT` immediately. |
181 | * |
182 | * This technique is useful if you need exclusive access to a resource but |
183 | * don't want to wait for it, and will return to it to try again later. |
184 | * |
185 | * \param mutex the mutex to try to lock |
186 | * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for |
187 | * more information. |
188 | * |
189 | * \since This function is available since SDL 2.0.0. |
190 | * |
191 | * \sa SDL_CreateMutex |
192 | * \sa SDL_DestroyMutex |
193 | * \sa SDL_LockMutex |
194 | * \sa SDL_UnlockMutex |
195 | */ |
196 | extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex) SDL_TRY_ACQUIRE(0, mutex); |
197 | |
198 | /** |
199 | * Unlock the mutex. |
200 | * |
201 | * It is legal for the owning thread to lock an already-locked mutex. It must |
202 | * unlock it the same number of times before it is actually made available for |
203 | * other threads in the system (this is known as a "recursive mutex"). |
204 | * |
205 | * It is an error to unlock a mutex that has not been locked by the current |
206 | * thread, and doing so results in undefined behavior. |
207 | * |
208 | * It is also an error to unlock a mutex that isn't locked at all. |
209 | * |
210 | * \param mutex the mutex to unlock. |
211 | * \returns 0, or -1 on error. |
212 | * |
213 | * \since This function is available since SDL 2.0.0. |
214 | */ |
215 | extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex) SDL_RELEASE(mutex); |
216 | #define SDL_mutexV(m) SDL_UnlockMutex(m) |
217 | |
218 | /** |
219 | * Destroy a mutex created with SDL_CreateMutex(). |
220 | * |
221 | * This function must be called on any mutex that is no longer needed. Failure |
222 | * to destroy a mutex will result in a system memory or resource leak. While |
223 | * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt |
224 | * to destroy a locked mutex, and may result in undefined behavior depending |
225 | * on the platform. |
226 | * |
227 | * \param mutex the mutex to destroy |
228 | * |
229 | * \since This function is available since SDL 2.0.0. |
230 | * |
231 | * \sa SDL_CreateMutex |
232 | * \sa SDL_LockMutex |
233 | * \sa SDL_TryLockMutex |
234 | * \sa SDL_UnlockMutex |
235 | */ |
236 | extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex); |
237 | |
238 | /* @} *//* Mutex functions */ |
239 | |
240 | |
241 | /** |
242 | * \name Semaphore functions |
243 | */ |
244 | /* @{ */ |
245 | |
246 | /* The SDL semaphore structure, defined in SDL_syssem.c */ |
247 | struct SDL_semaphore; |
248 | typedef struct SDL_semaphore SDL_sem; |
249 | |
250 | /** |
251 | * Create a semaphore. |
252 | * |
253 | * This function creates a new semaphore and initializes it with the value |
254 | * `initial_value`. Each wait operation on the semaphore will atomically |
255 | * decrement the semaphore value and potentially block if the semaphore value |
256 | * is 0. Each post operation will atomically increment the semaphore value and |
257 | * wake waiting threads and allow them to retry the wait operation. |
258 | * |
259 | * \param initial_value the starting value of the semaphore |
260 | * \returns a new semaphore or NULL on failure; call SDL_GetError() for more |
261 | * information. |
262 | * |
263 | * \since This function is available since SDL 2.0.0. |
264 | * |
265 | * \sa SDL_DestroySemaphore |
266 | * \sa SDL_SemPost |
267 | * \sa SDL_SemTryWait |
268 | * \sa SDL_SemValue |
269 | * \sa SDL_SemWait |
270 | * \sa SDL_SemWaitTimeout |
271 | */ |
272 | extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); |
273 | |
274 | /** |
275 | * Destroy a semaphore. |
276 | * |
277 | * It is not safe to destroy a semaphore if there are threads currently |
278 | * waiting on it. |
279 | * |
280 | * \param sem the semaphore to destroy |
281 | * |
282 | * \since This function is available since SDL 2.0.0. |
283 | * |
284 | * \sa SDL_CreateSemaphore |
285 | * \sa SDL_SemPost |
286 | * \sa SDL_SemTryWait |
287 | * \sa SDL_SemValue |
288 | * \sa SDL_SemWait |
289 | * \sa SDL_SemWaitTimeout |
290 | */ |
291 | extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); |
292 | |
293 | /** |
294 | * Wait until a semaphore has a positive value and then decrements it. |
295 | * |
296 | * This function suspends the calling thread until either the semaphore |
297 | * pointed to by `sem` has a positive value or the call is interrupted by a |
298 | * signal or error. If the call is successful it will atomically decrement the |
299 | * semaphore value. |
300 | * |
301 | * This function is the equivalent of calling SDL_SemWaitTimeout() with a time |
302 | * length of `SDL_MUTEX_MAXWAIT`. |
303 | * |
304 | * \param sem the semaphore wait on |
305 | * \returns 0 on success or a negative error code on failure; call |
306 | * SDL_GetError() for more information. |
307 | * |
308 | * \since This function is available since SDL 2.0.0. |
309 | * |
310 | * \sa SDL_CreateSemaphore |
311 | * \sa SDL_DestroySemaphore |
312 | * \sa SDL_SemPost |
313 | * \sa SDL_SemTryWait |
314 | * \sa SDL_SemValue |
315 | * \sa SDL_SemWait |
316 | * \sa SDL_SemWaitTimeout |
317 | */ |
318 | extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem); |
319 | |
320 | /** |
321 | * See if a semaphore has a positive value and decrement it if it does. |
322 | * |
323 | * This function checks to see if the semaphore pointed to by `sem` has a |
324 | * positive value and atomically decrements the semaphore value if it does. If |
325 | * the semaphore doesn't have a positive value, the function immediately |
326 | * returns SDL_MUTEX_TIMEDOUT. |
327 | * |
328 | * \param sem the semaphore to wait on |
329 | * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would |
330 | * block, or a negative error code on failure; call SDL_GetError() |
331 | * for more information. |
332 | * |
333 | * \since This function is available since SDL 2.0.0. |
334 | * |
335 | * \sa SDL_CreateSemaphore |
336 | * \sa SDL_DestroySemaphore |
337 | * \sa SDL_SemPost |
338 | * \sa SDL_SemValue |
339 | * \sa SDL_SemWait |
340 | * \sa SDL_SemWaitTimeout |
341 | */ |
342 | extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); |
343 | |
344 | /** |
345 | * Wait until a semaphore has a positive value and then decrements it. |
346 | * |
347 | * This function suspends the calling thread until either the semaphore |
348 | * pointed to by `sem` has a positive value, the call is interrupted by a |
349 | * signal or error, or the specified time has elapsed. If the call is |
350 | * successful it will atomically decrement the semaphore value. |
351 | * |
352 | * \param sem the semaphore to wait on |
353 | * \param timeout the length of the timeout, in milliseconds |
354 | * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not |
355 | * succeed in the allotted time, or a negative error code on failure; |
356 | * call SDL_GetError() for more information. |
357 | * |
358 | * \since This function is available since SDL 2.0.0. |
359 | * |
360 | * \sa SDL_CreateSemaphore |
361 | * \sa SDL_DestroySemaphore |
362 | * \sa SDL_SemPost |
363 | * \sa SDL_SemTryWait |
364 | * \sa SDL_SemValue |
365 | * \sa SDL_SemWait |
366 | */ |
367 | extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout); |
368 | |
369 | /** |
370 | * Atomically increment a semaphore's value and wake waiting threads. |
371 | * |
372 | * \param sem the semaphore to increment |
373 | * \returns 0 on success or a negative error code on failure; call |
374 | * SDL_GetError() for more information. |
375 | * |
376 | * \since This function is available since SDL 2.0.0. |
377 | * |
378 | * \sa SDL_CreateSemaphore |
379 | * \sa SDL_DestroySemaphore |
380 | * \sa SDL_SemTryWait |
381 | * \sa SDL_SemValue |
382 | * \sa SDL_SemWait |
383 | * \sa SDL_SemWaitTimeout |
384 | */ |
385 | extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem); |
386 | |
387 | /** |
388 | * Get the current value of a semaphore. |
389 | * |
390 | * \param sem the semaphore to query |
391 | * \returns the current value of the semaphore. |
392 | * |
393 | * \since This function is available since SDL 2.0.0. |
394 | * |
395 | * \sa SDL_CreateSemaphore |
396 | */ |
397 | extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem); |
398 | |
399 | /* @} *//* Semaphore functions */ |
400 | |
401 | |
402 | /** |
403 | * \name Condition variable functions |
404 | */ |
405 | /* @{ */ |
406 | |
407 | /* The SDL condition variable structure, defined in SDL_syscond.c */ |
408 | struct SDL_cond; |
409 | typedef struct SDL_cond SDL_cond; |
410 | |
411 | /** |
412 | * Create a condition variable. |
413 | * |
414 | * \returns a new condition variable or NULL on failure; call SDL_GetError() |
415 | * for more information. |
416 | * |
417 | * \since This function is available since SDL 2.0.0. |
418 | * |
419 | * \sa SDL_CondBroadcast |
420 | * \sa SDL_CondSignal |
421 | * \sa SDL_CondWait |
422 | * \sa SDL_CondWaitTimeout |
423 | * \sa SDL_DestroyCond |
424 | */ |
425 | extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void); |
426 | |
427 | /** |
428 | * Destroy a condition variable. |
429 | * |
430 | * \param cond the condition variable to destroy |
431 | * |
432 | * \since This function is available since SDL 2.0.0. |
433 | * |
434 | * \sa SDL_CondBroadcast |
435 | * \sa SDL_CondSignal |
436 | * \sa SDL_CondWait |
437 | * \sa SDL_CondWaitTimeout |
438 | * \sa SDL_CreateCond |
439 | */ |
440 | extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond); |
441 | |
442 | /** |
443 | * Restart one of the threads that are waiting on the condition variable. |
444 | * |
445 | * \param cond the condition variable to signal |
446 | * \returns 0 on success or a negative error code on failure; call |
447 | * SDL_GetError() for more information. |
448 | * |
449 | * \since This function is available since SDL 2.0.0. |
450 | * |
451 | * \sa SDL_CondBroadcast |
452 | * \sa SDL_CondWait |
453 | * \sa SDL_CondWaitTimeout |
454 | * \sa SDL_CreateCond |
455 | * \sa SDL_DestroyCond |
456 | */ |
457 | extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond); |
458 | |
459 | /** |
460 | * Restart all threads that are waiting on the condition variable. |
461 | * |
462 | * \param cond the condition variable to signal |
463 | * \returns 0 on success or a negative error code on failure; call |
464 | * SDL_GetError() for more information. |
465 | * |
466 | * \since This function is available since SDL 2.0.0. |
467 | * |
468 | * \sa SDL_CondSignal |
469 | * \sa SDL_CondWait |
470 | * \sa SDL_CondWaitTimeout |
471 | * \sa SDL_CreateCond |
472 | * \sa SDL_DestroyCond |
473 | */ |
474 | extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); |
475 | |
476 | /** |
477 | * Wait until a condition variable is signaled. |
478 | * |
479 | * This function unlocks the specified `mutex` and waits for another thread to |
480 | * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable |
481 | * `cond`. Once the condition variable is signaled, the mutex is re-locked and |
482 | * the function returns. |
483 | * |
484 | * The mutex must be locked before calling this function. |
485 | * |
486 | * This function is the equivalent of calling SDL_CondWaitTimeout() with a |
487 | * time length of `SDL_MUTEX_MAXWAIT`. |
488 | * |
489 | * \param cond the condition variable to wait on |
490 | * \param mutex the mutex used to coordinate thread access |
491 | * \returns 0 when it is signaled or a negative error code on failure; call |
492 | * SDL_GetError() for more information. |
493 | * |
494 | * \since This function is available since SDL 2.0.0. |
495 | * |
496 | * \sa SDL_CondBroadcast |
497 | * \sa SDL_CondSignal |
498 | * \sa SDL_CondWaitTimeout |
499 | * \sa SDL_CreateCond |
500 | * \sa SDL_DestroyCond |
501 | */ |
502 | extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex); |
503 | |
504 | /** |
505 | * Wait until a condition variable is signaled or a certain time has passed. |
506 | * |
507 | * This function unlocks the specified `mutex` and waits for another thread to |
508 | * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable |
509 | * `cond`, or for the specified time to elapse. Once the condition variable is |
510 | * signaled or the time elapsed, the mutex is re-locked and the function |
511 | * returns. |
512 | * |
513 | * The mutex must be locked before calling this function. |
514 | * |
515 | * \param cond the condition variable to wait on |
516 | * \param mutex the mutex used to coordinate thread access |
517 | * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT` |
518 | * to wait indefinitely |
519 | * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if |
520 | * the condition is not signaled in the allotted time, or a negative |
521 | * error code on failure; call SDL_GetError() for more information. |
522 | * |
523 | * \since This function is available since SDL 2.0.0. |
524 | * |
525 | * \sa SDL_CondBroadcast |
526 | * \sa SDL_CondSignal |
527 | * \sa SDL_CondWait |
528 | * \sa SDL_CreateCond |
529 | * \sa SDL_DestroyCond |
530 | */ |
531 | extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond, |
532 | SDL_mutex * mutex, Uint32 ms); |
533 | |
534 | /* @} *//* Condition variable functions */ |
535 | |
536 | |
537 | /* Ends C function definitions when using C++ */ |
538 | #ifdef __cplusplus |
539 | } |
540 | #endif |
541 | #include "close_code.h" |
542 | |
543 | #endif /* SDL_mutex_h_ */ |
544 | |
545 | /* vi: set ts=4 sw=4 expandtab: */ |
546 | |