SDL 2.0
SDL_mutex.h File Reference
#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "begin_code.h"
#include "close_code.h"
+ Include dependency graph for SDL_mutex.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x)   /* no-op */
 
#define SDL_CAPABILITY(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x))
 
#define SDL_SCOPED_CAPABILITY    SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
 
#define SDL_GUARDED_BY(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
 
#define SDL_PT_GUARDED_BY(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
 
#define SDL_ACQUIRED_BEFORE(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x))
 
#define SDL_ACQUIRED_AFTER(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x))
 
#define SDL_REQUIRES(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x))
 
#define SDL_REQUIRES_SHARED(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x))
 
#define SDL_ACQUIRE(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x))
 
#define SDL_ACQUIRE_SHARED(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x))
 
#define SDL_RELEASE(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x))
 
#define SDL_RELEASE_SHARED(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x))
 
#define SDL_RELEASE_GENERIC(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x))
 
#define SDL_TRY_ACQUIRE(x, y)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y))
 
#define SDL_TRY_ACQUIRE_SHARED(x, y)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y))
 
#define SDL_EXCLUDES(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x))
 
#define SDL_ASSERT_CAPABILITY(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
 
#define SDL_ASSERT_SHARED_CAPABILITY(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
 
#define SDL_RETURN_CAPABILITY(x)    SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
 
#define SDL_NO_THREAD_SAFETY_ANALYSIS    SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
 
#define SDL_MUTEX_TIMEDOUT   1
 
#define SDL_MUTEX_MAXWAIT   (~(Uint32)0)
 

Mutex functions

#define SDL_mutexP(m)   SDL_LockMutex(m)
 
#define SDL_mutexV(m)   SDL_UnlockMutex(m)
 
typedef struct SDL_mutex SDL_mutex
 
int mutex
 
SDL_mutexSDL_CreateMutex (void)
 
int SDL_LockMutex (SDL_mutex *mutex) SDL_ACQUIRE(mutex)
 
int SDL_TryLockMutex (SDL_mutex *mutex) SDL_TRY_ACQUIRE(0
 
int SDL_UnlockMutex (SDL_mutex *mutex) SDL_RELEASE(mutex)
 
void SDL_DestroyMutex (SDL_mutex *mutex)
 

Semaphore functions

typedef struct SDL_semaphore SDL_sem
 
SDL_semSDL_CreateSemaphore (Uint32 initial_value)
 
void SDL_DestroySemaphore (SDL_sem *sem)
 
int SDL_SemWait (SDL_sem *sem)
 
int SDL_SemTryWait (SDL_sem *sem)
 
int SDL_SemWaitTimeout (SDL_sem *sem, Uint32 timeout)
 
int SDL_SemPost (SDL_sem *sem)
 
Uint32 SDL_SemValue (SDL_sem *sem)
 

Condition variable functions

typedef struct SDL_cond SDL_cond
 
SDL_condSDL_CreateCond (void)
 
void SDL_DestroyCond (SDL_cond *cond)
 
int SDL_CondSignal (SDL_cond *cond)
 
int SDL_CondBroadcast (SDL_cond *cond)
 
int SDL_CondWait (SDL_cond *cond, SDL_mutex *mutex)
 
int SDL_CondWaitTimeout (SDL_cond *cond, SDL_mutex *mutex, Uint32 ms)
 

Detailed Description

Functions to provide thread synchronization primitives.

Definition in file SDL_mutex.h.

Macro Definition Documentation

◆ SDL_ACQUIRE

#define SDL_ACQUIRE (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x))

Definition at line 69 of file SDL_mutex.h.

110 {
111#endif
112
113/**
114 * Synchronization functions which can time out return this value
115 * if they time out.
116 */
117#define SDL_MUTEX_TIMEDOUT 1
118
119/**
120 * This is the timeout value which corresponds to never time out.
121 */
122#define SDL_MUTEX_MAXWAIT (~(Uint32)0)
123
124
125/**
126 * \name Mutex functions
127 */
128/* @{ */
129
130/* The SDL mutex structure, defined in SDL_sysmutex.c */
131struct SDL_mutex;
132typedef struct SDL_mutex SDL_mutex;
133
134/**
135 * Create a new mutex.
136 *
137 * All newly-created mutexes begin in the _unlocked_ state.
138 *
139 * Calls to SDL_LockMutex() will not return while the mutex is locked by
140 * another thread. See SDL_TryLockMutex() to attempt to lock without blocking.
141 *
142 * SDL mutexes are reentrant.
143 *
144 * \returns the initialized and unlocked mutex or NULL on failure; call
145 * SDL_GetError() for more information.
146 *
147 * \since This function is available since SDL 2.0.0.
148 *
149 * \sa SDL_DestroyMutex
150 * \sa SDL_LockMutex
151 * \sa SDL_TryLockMutex
152 * \sa SDL_UnlockMutex
153 */
154extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
155
156/**
157 * Lock the mutex.
158 *
159 * This will block until the mutex is available, which is to say it is in the
160 * unlocked state and the OS has chosen the caller as the next thread to lock
161 * it. Of all threads waiting to lock the mutex, only one may do so at a time.
162 *
163 * It is legal for the owning thread to lock an already-locked mutex. It must
164 * unlock it the same number of times before it is actually made available for
165 * other threads in the system (this is known as a "recursive mutex").
166 *
167 * \param mutex the mutex to lock
168 * \return 0, or -1 on error.
169 *
170 * \since This function is available since SDL 2.0.0.
171 */
172extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex) SDL_ACQUIRE(mutex);
173#define SDL_mutexP(m) SDL_LockMutex(m)
174
175/**
176 * Try to lock a mutex without blocking.
177 *
178 * This works just like SDL_LockMutex(), but if the mutex is not available,
179 * this function returns `SDL_MUTEX_TIMEOUT` immediately.
180 *
181 * This technique is useful if you need exclusive access to a resource but
182 * don't want to wait for it, and will return to it to try again later.
183 *
184 * \param mutex the mutex to try to lock
185 * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for
186 * more information.
187 *
188 * \since This function is available since SDL 2.0.0.
189 *
190 * \sa SDL_CreateMutex
191 * \sa SDL_DestroyMutex
192 * \sa SDL_LockMutex
193 * \sa SDL_UnlockMutex
194 */
195extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex) SDL_TRY_ACQUIRE(0, mutex);
196
197/**
198 * Unlock the mutex.
199 *
200 * It is legal for the owning thread to lock an already-locked mutex. It must
201 * unlock it the same number of times before it is actually made available for
202 * other threads in the system (this is known as a "recursive mutex").
203 *
204 * It is an error to unlock a mutex that has not been locked by the current
205 * thread, and doing so results in undefined behavior.
206 *
207 * It is also an error to unlock a mutex that isn't locked at all.
208 *
209 * \param mutex the mutex to unlock.
210 * \returns 0, or -1 on error.
211 *
212 * \since This function is available since SDL 2.0.0.
213 */
214extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex) SDL_RELEASE(mutex);
215#define SDL_mutexV(m) SDL_UnlockMutex(m)
216
217/**
218 * Destroy a mutex created with SDL_CreateMutex().
219 *
220 * This function must be called on any mutex that is no longer needed. Failure
221 * to destroy a mutex will result in a system memory or resource leak. While
222 * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt
223 * to destroy a locked mutex, and may result in undefined behavior depending
224 * on the platform.
225 *
226 * \param mutex the mutex to destroy
227 *
228 * \since This function is available since SDL 2.0.0.
229 *
230 * \sa SDL_CreateMutex
231 * \sa SDL_LockMutex
232 * \sa SDL_TryLockMutex
233 * \sa SDL_UnlockMutex
234 */
235extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
236
237/* @} *//* Mutex functions */
238
239
240/**
241 * \name Semaphore functions
242 */
243/* @{ */
244
245/* The SDL semaphore structure, defined in SDL_syssem.c */
246struct SDL_semaphore;
247typedef struct SDL_semaphore SDL_sem;
248
249/**
250 * Create a semaphore.
251 *
252 * This function creates a new semaphore and initializes it with the value
253 * `initial_value`. Each wait operation on the semaphore will atomically
254 * decrement the semaphore value and potentially block if the semaphore value
255 * is 0. Each post operation will atomically increment the semaphore value and
256 * wake waiting threads and allow them to retry the wait operation.
257 *
258 * \param initial_value the starting value of the semaphore
259 * \returns a new semaphore or NULL on failure; call SDL_GetError() for more
260 * information.
261 *
262 * \since This function is available since SDL 2.0.0.
263 *
264 * \sa SDL_DestroySemaphore
265 * \sa SDL_SemPost
266 * \sa SDL_SemTryWait
267 * \sa SDL_SemValue
268 * \sa SDL_SemWait
269 * \sa SDL_SemWaitTimeout
270 */
271extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
272
273/**
274 * Destroy a semaphore.
275 *
276 * It is not safe to destroy a semaphore if there are threads currently
277 * waiting on it.
278 *
279 * \param sem the semaphore to destroy
280 *
281 * \since This function is available since SDL 2.0.0.
282 *
283 * \sa SDL_CreateSemaphore
284 * \sa SDL_SemPost
285 * \sa SDL_SemTryWait
286 * \sa SDL_SemValue
287 * \sa SDL_SemWait
288 * \sa SDL_SemWaitTimeout
289 */
290extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
291
292/**
293 * Wait until a semaphore has a positive value and then decrements it.
294 *
295 * This function suspends the calling thread until either the semaphore
296 * pointed to by `sem` has a positive value or the call is interrupted by a
297 * signal or error. If the call is successful it will atomically decrement the
298 * semaphore value.
299 *
300 * This function is the equivalent of calling SDL_SemWaitTimeout() with a time
301 * length of `SDL_MUTEX_MAXWAIT`.
302 *
303 * \param sem the semaphore wait on
304 * \returns 0 on success or a negative error code on failure; call
305 * SDL_GetError() for more information.
306 *
307 * \since This function is available since SDL 2.0.0.
308 *
309 * \sa SDL_CreateSemaphore
310 * \sa SDL_DestroySemaphore
311 * \sa SDL_SemPost
312 * \sa SDL_SemTryWait
313 * \sa SDL_SemValue
314 * \sa SDL_SemWait
315 * \sa SDL_SemWaitTimeout
316 */
317extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
318
319/**
320 * See if a semaphore has a positive value and decrement it if it does.
321 *
322 * This function checks to see if the semaphore pointed to by `sem` has a
323 * positive value and atomically decrements the semaphore value if it does. If
324 * the semaphore doesn't have a positive value, the function immediately
325 * returns SDL_MUTEX_TIMEDOUT.
326 *
327 * \param sem the semaphore to wait on
328 * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would
329 * block, or a negative error code on failure; call SDL_GetError()
330 * for more information.
331 *
332 * \since This function is available since SDL 2.0.0.
333 *
334 * \sa SDL_CreateSemaphore
335 * \sa SDL_DestroySemaphore
336 * \sa SDL_SemPost
337 * \sa SDL_SemValue
338 * \sa SDL_SemWait
339 * \sa SDL_SemWaitTimeout
340 */
341extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
342
343/**
344 * Wait until a semaphore has a positive value and then decrements it.
345 *
346 * This function suspends the calling thread until either the semaphore
347 * pointed to by `sem` has a positive value, the call is interrupted by a
348 * signal or error, or the specified time has elapsed. If the call is
349 * successful it will atomically decrement the semaphore value.
350 *
351 * \param sem the semaphore to wait on
352 * \param timeout the length of the timeout, in milliseconds
353 * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
354 * succeed in the allotted time, or a negative error code on failure;
355 * call SDL_GetError() for more information.
356 *
357 * \since This function is available since SDL 2.0.0.
358 *
359 * \sa SDL_CreateSemaphore
360 * \sa SDL_DestroySemaphore
361 * \sa SDL_SemPost
362 * \sa SDL_SemTryWait
363 * \sa SDL_SemValue
364 * \sa SDL_SemWait
365 */
366extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout);
367
368/**
369 * Atomically increment a semaphore's value and wake waiting threads.
370 *
371 * \param sem the semaphore to increment
372 * \returns 0 on success or a negative error code on failure; call
373 * SDL_GetError() for more information.
374 *
375 * \since This function is available since SDL 2.0.0.
376 *
377 * \sa SDL_CreateSemaphore
378 * \sa SDL_DestroySemaphore
379 * \sa SDL_SemTryWait
380 * \sa SDL_SemValue
381 * \sa SDL_SemWait
382 * \sa SDL_SemWaitTimeout
383 */
384extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
385
386/**
387 * Get the current value of a semaphore.
388 *
389 * \param sem the semaphore to query
390 * \returns the current value of the semaphore.
391 *
392 * \since This function is available since SDL 2.0.0.
393 *
394 * \sa SDL_CreateSemaphore
395 */
396extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
397
398/* @} *//* Semaphore functions */
399
400
401/**
402 * \name Condition variable functions
403 */
404/* @{ */
405
406/* The SDL condition variable structure, defined in SDL_syscond.c */
407struct SDL_cond;
408typedef struct SDL_cond SDL_cond;
409
410/**
411 * Create a condition variable.
412 *
413 * \returns a new condition variable or NULL on failure; call SDL_GetError()
414 * for more information.
415 *
416 * \since This function is available since SDL 2.0.0.
417 *
418 * \sa SDL_CondBroadcast
419 * \sa SDL_CondSignal
420 * \sa SDL_CondWait
421 * \sa SDL_CondWaitTimeout
422 * \sa SDL_DestroyCond
423 */
424extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
425
426/**
427 * Destroy a condition variable.
428 *
429 * \param cond the condition variable to destroy
430 *
431 * \since This function is available since SDL 2.0.0.
432 *
433 * \sa SDL_CondBroadcast
434 * \sa SDL_CondSignal
435 * \sa SDL_CondWait
436 * \sa SDL_CondWaitTimeout
437 * \sa SDL_CreateCond
438 */
439extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
440
441/**
442 * Restart one of the threads that are waiting on the condition variable.
443 *
444 * \param cond the condition variable to signal
445 * \returns 0 on success or a negative error code on failure; call
446 * SDL_GetError() for more information.
447 *
448 * \since This function is available since SDL 2.0.0.
449 *
450 * \sa SDL_CondBroadcast
451 * \sa SDL_CondWait
452 * \sa SDL_CondWaitTimeout
453 * \sa SDL_CreateCond
454 * \sa SDL_DestroyCond
455 */
456extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
457
458/**
459 * Restart all threads that are waiting on the condition variable.
460 *
461 * \param cond the condition variable to signal
462 * \returns 0 on success or a negative error code on failure; call
463 * SDL_GetError() for more information.
464 *
465 * \since This function is available since SDL 2.0.0.
466 *
467 * \sa SDL_CondSignal
468 * \sa SDL_CondWait
469 * \sa SDL_CondWaitTimeout
470 * \sa SDL_CreateCond
471 * \sa SDL_DestroyCond
472 */
473extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
474
475/**
476 * Wait until a condition variable is signaled.
477 *
478 * This function unlocks the specified `mutex` and waits for another thread to
479 * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
480 * `cond`. Once the condition variable is signaled, the mutex is re-locked and
481 * the function returns.
482 *
483 * The mutex must be locked before calling this function.
484 *
485 * This function is the equivalent of calling SDL_CondWaitTimeout() with a
486 * time length of `SDL_MUTEX_MAXWAIT`.
487 *
488 * \param cond the condition variable to wait on
489 * \param mutex the mutex used to coordinate thread access
490 * \returns 0 when it is signaled or a negative error code on failure; call
491 * SDL_GetError() for more information.
492 *
493 * \since This function is available since SDL 2.0.0.
494 *
495 * \sa SDL_CondBroadcast
496 * \sa SDL_CondSignal
497 * \sa SDL_CondWaitTimeout
498 * \sa SDL_CreateCond
499 * \sa SDL_DestroyCond
500 */
501extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
502
503/**
504 * Wait until a condition variable is signaled or a certain time has passed.
505 *
506 * This function unlocks the specified `mutex` and waits for another thread to
507 * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
508 * `cond`, or for the specified time to elapse. Once the condition variable is
509 * signaled or the time elapsed, the mutex is re-locked and the function
510 * returns.
511 *
512 * The mutex must be locked before calling this function.
513 *
514 * \param cond the condition variable to wait on
515 * \param mutex the mutex used to coordinate thread access
516 * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
517 * to wait indefinitely
518 * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
519 * the condition is not signaled in the allotted time, or a negative
520 * error code on failure; call SDL_GetError() for more information.
521 *
522 * \since This function is available since SDL 2.0.0.
523 *
524 * \sa SDL_CondBroadcast
525 * \sa SDL_CondSignal
526 * \sa SDL_CondWait
527 * \sa SDL_CreateCond
528 * \sa SDL_DestroyCond
529 */
530extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
531 SDL_mutex * mutex, Uint32 ms);
532
533/* @} *//* Condition variable functions */
534
535
536/* Ends C function definitions when using C++ */
537#ifdef __cplusplus
538}
539#endif
540#include "close_code.h"
541
542#endif /* SDL_mutex_h_ */
543
544/* vi: set ts=4 sw=4 expandtab: */
int SDL_SemWait(SDL_sem *sem)
#define SDL_ACQUIRE(x)
Definition SDL_mutex.h:69
#define SDL_TRY_ACQUIRE(x, y)
Definition SDL_mutex.h:84
int SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout)
int SDL_TryLockMutex(SDL_mutex *mutex) SDL_TRY_ACQUIRE(0
void SDL_DestroyMutex(SDL_mutex *mutex)
SDL_cond * SDL_CreateCond(void)
SDL_sem * SDL_CreateSemaphore(Uint32 initial_value)
void SDL_DestroySemaphore(SDL_sem *sem)
int SDL_CondBroadcast(SDL_cond *cond)
int mutex
Definition SDL_mutex.h:196
int SDL_SemPost(SDL_sem *sem)
int SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms)
int SDL_CondSignal(SDL_cond *cond)
void SDL_DestroyCond(SDL_cond *cond)
int SDL_UnlockMutex(SDL_mutex *mutex) SDL_RELEASE(mutex)
struct SDL_semaphore SDL_sem
Definition SDL_mutex.h:248
int SDL_LockMutex(SDL_mutex *mutex) SDL_ACQUIRE(mutex)
struct SDL_mutex SDL_mutex
Definition SDL_mutex.h:133
struct SDL_cond SDL_cond
Definition SDL_mutex.h:409
#define SDL_RELEASE(x)
Definition SDL_mutex.h:75
SDL_mutex * SDL_CreateMutex(void)
Uint32 SDL_SemValue(SDL_sem *sem)
int SDL_SemTryWait(SDL_sem *sem)
int SDL_CondWait(SDL_cond *cond, SDL_mutex *mutex)
uint32_t Uint32
Definition SDL_stdinc.h:222

◆ SDL_ACQUIRE_SHARED

#define SDL_ACQUIRE_SHARED (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x))

Definition at line 72 of file SDL_mutex.h.

◆ SDL_ACQUIRED_AFTER

#define SDL_ACQUIRED_AFTER (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x))

Definition at line 60 of file SDL_mutex.h.

◆ SDL_ACQUIRED_BEFORE

#define SDL_ACQUIRED_BEFORE (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x))

Definition at line 57 of file SDL_mutex.h.

◆ SDL_ASSERT_CAPABILITY

#define SDL_ASSERT_CAPABILITY (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))

Definition at line 93 of file SDL_mutex.h.

◆ SDL_ASSERT_SHARED_CAPABILITY

#define SDL_ASSERT_SHARED_CAPABILITY (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))

Definition at line 96 of file SDL_mutex.h.

◆ SDL_CAPABILITY

#define SDL_CAPABILITY (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x))

Definition at line 45 of file SDL_mutex.h.

◆ SDL_EXCLUDES

#define SDL_EXCLUDES (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x))

Definition at line 90 of file SDL_mutex.h.

◆ SDL_GUARDED_BY

#define SDL_GUARDED_BY (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))

Definition at line 51 of file SDL_mutex.h.

◆ SDL_MUTEX_MAXWAIT

#define SDL_MUTEX_MAXWAIT   (~(Uint32)0)

This is the timeout value which corresponds to never time out.

Definition at line 123 of file SDL_mutex.h.

◆ SDL_MUTEX_TIMEDOUT

#define SDL_MUTEX_TIMEDOUT   1

Synchronization functions which can time out return this value if they time out.

Definition at line 118 of file SDL_mutex.h.

◆ SDL_mutexP

#define SDL_mutexP (   m)    SDL_LockMutex(m)

Definition at line 174 of file SDL_mutex.h.

◆ SDL_mutexV

#define SDL_mutexV (   m)    SDL_UnlockMutex(m)

Definition at line 216 of file SDL_mutex.h.

◆ SDL_NO_THREAD_SAFETY_ANALYSIS

#define SDL_NO_THREAD_SAFETY_ANALYSIS    SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)

Definition at line 102 of file SDL_mutex.h.

◆ SDL_PT_GUARDED_BY

#define SDL_PT_GUARDED_BY (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))

Definition at line 54 of file SDL_mutex.h.

◆ SDL_RELEASE

#define SDL_RELEASE (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x))

Definition at line 75 of file SDL_mutex.h.

◆ SDL_RELEASE_GENERIC

#define SDL_RELEASE_GENERIC (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x))

Definition at line 81 of file SDL_mutex.h.

◆ SDL_RELEASE_SHARED

#define SDL_RELEASE_SHARED (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x))

Definition at line 78 of file SDL_mutex.h.

◆ SDL_REQUIRES

#define SDL_REQUIRES (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x))

Definition at line 63 of file SDL_mutex.h.

◆ SDL_REQUIRES_SHARED

#define SDL_REQUIRES_SHARED (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x))

Definition at line 66 of file SDL_mutex.h.

◆ SDL_RETURN_CAPABILITY

#define SDL_RETURN_CAPABILITY (   x)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))

Definition at line 99 of file SDL_mutex.h.

◆ SDL_SCOPED_CAPABILITY

#define SDL_SCOPED_CAPABILITY    SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)

Definition at line 48 of file SDL_mutex.h.

◆ SDL_THREAD_ANNOTATION_ATTRIBUTE__

#define SDL_THREAD_ANNOTATION_ATTRIBUTE__ (   x)    /* no-op */

Definition at line 42 of file SDL_mutex.h.

◆ SDL_TRY_ACQUIRE

#define SDL_TRY_ACQUIRE (   x,
 
)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y))

Definition at line 84 of file SDL_mutex.h.

◆ SDL_TRY_ACQUIRE_SHARED

#define SDL_TRY_ACQUIRE_SHARED (   x,
 
)     SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y))

Definition at line 87 of file SDL_mutex.h.

Typedef Documentation

◆ SDL_cond

typedef struct SDL_cond SDL_cond

Definition at line 409 of file SDL_mutex.h.

◆ SDL_mutex

typedef struct SDL_mutex SDL_mutex

Definition at line 133 of file SDL_mutex.h.

◆ SDL_sem

typedef struct SDL_semaphore SDL_sem

Definition at line 248 of file SDL_mutex.h.

Function Documentation

◆ SDL_CondBroadcast()

int SDL_CondBroadcast ( SDL_cond cond)
extern

Restart all threads that are waiting on the condition variable.

Parameters
condthe condition variable to signal
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CondSignal
SDL_CondWait
SDL_CondWaitTimeout
SDL_CreateCond
SDL_DestroyCond

◆ SDL_CondSignal()

int SDL_CondSignal ( SDL_cond cond)
extern

Restart one of the threads that are waiting on the condition variable.

Parameters
condthe condition variable to signal
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CondBroadcast
SDL_CondWait
SDL_CondWaitTimeout
SDL_CreateCond
SDL_DestroyCond

◆ SDL_CondWait()

int SDL_CondWait ( SDL_cond cond,
SDL_mutex mutex 
)
extern

Wait until a condition variable is signaled.

This function unlocks the specified mutex and waits for another thread to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable cond. Once the condition variable is signaled, the mutex is re-locked and the function returns.

The mutex must be locked before calling this function.

This function is the equivalent of calling SDL_CondWaitTimeout() with a time length of SDL_MUTEX_MAXWAIT.

Parameters
condthe condition variable to wait on
mutexthe mutex used to coordinate thread access
Returns
0 when it is signaled or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CondBroadcast
SDL_CondSignal
SDL_CondWaitTimeout
SDL_CreateCond
SDL_DestroyCond

◆ SDL_CondWaitTimeout()

int SDL_CondWaitTimeout ( SDL_cond cond,
SDL_mutex mutex,
Uint32  ms 
)
extern

Wait until a condition variable is signaled or a certain time has passed.

This function unlocks the specified mutex and waits for another thread to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable cond, or for the specified time to elapse. Once the condition variable is signaled or the time elapsed, the mutex is re-locked and the function returns.

The mutex must be locked before calling this function.

Parameters
condthe condition variable to wait on
mutexthe mutex used to coordinate thread access
msthe maximum time to wait, in milliseconds, or SDL_MUTEX_MAXWAIT to wait indefinitely
Returns
0 if the condition variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not signaled in the allotted time, or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CondBroadcast
SDL_CondSignal
SDL_CondWait
SDL_CreateCond
SDL_DestroyCond

◆ SDL_CreateCond()

SDL_cond * SDL_CreateCond ( void  )
extern

Create a condition variable.

Returns
a new condition variable or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CondBroadcast
SDL_CondSignal
SDL_CondWait
SDL_CondWaitTimeout
SDL_DestroyCond

◆ SDL_CreateMutex()

SDL_mutex * SDL_CreateMutex ( void  )
extern

Create a new mutex.

All newly-created mutexes begin in the unlocked state.

Calls to SDL_LockMutex() will not return while the mutex is locked by another thread. See SDL_TryLockMutex() to attempt to lock without blocking.

SDL mutexes are reentrant.

Returns
the initialized and unlocked mutex or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_DestroyMutex
SDL_LockMutex
SDL_TryLockMutex
SDL_UnlockMutex

◆ SDL_CreateSemaphore()

SDL_sem * SDL_CreateSemaphore ( Uint32  initial_value)
extern

Create a semaphore.

This function creates a new semaphore and initializes it with the value initial_value. Each wait operation on the semaphore will atomically decrement the semaphore value and potentially block if the semaphore value is 0. Each post operation will atomically increment the semaphore value and wake waiting threads and allow them to retry the wait operation.

Parameters
initial_valuethe starting value of the semaphore
Returns
a new semaphore or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_DestroySemaphore
SDL_SemPost
SDL_SemTryWait
SDL_SemValue
SDL_SemWait
SDL_SemWaitTimeout

◆ SDL_DestroyCond()

void SDL_DestroyCond ( SDL_cond cond)
extern

Destroy a condition variable.

Parameters
condthe condition variable to destroy
Since
This function is available since SDL 2.0.0.
See also
SDL_CondBroadcast
SDL_CondSignal
SDL_CondWait
SDL_CondWaitTimeout
SDL_CreateCond

◆ SDL_DestroyMutex()

void SDL_DestroyMutex ( SDL_mutex mutex)
extern

Destroy a mutex created with SDL_CreateMutex().

This function must be called on any mutex that is no longer needed. Failure to destroy a mutex will result in a system memory or resource leak. While it is safe to destroy a mutex that is unlocked, it is not safe to attempt to destroy a locked mutex, and may result in undefined behavior depending on the platform.

Parameters
mutexthe mutex to destroy
Since
This function is available since SDL 2.0.0.
See also
SDL_CreateMutex
SDL_LockMutex
SDL_TryLockMutex
SDL_UnlockMutex

◆ SDL_DestroySemaphore()

void SDL_DestroySemaphore ( SDL_sem sem)
extern

Destroy a semaphore.

It is not safe to destroy a semaphore if there are threads currently waiting on it.

Parameters
semthe semaphore to destroy
Since
This function is available since SDL 2.0.0.
See also
SDL_CreateSemaphore
SDL_SemPost
SDL_SemTryWait
SDL_SemValue
SDL_SemWait
SDL_SemWaitTimeout

◆ SDL_LockMutex()

int SDL_LockMutex ( SDL_mutex mutex)
extern

Lock the mutex.

This will block until the mutex is available, which is to say it is in the unlocked state and the OS has chosen the caller as the next thread to lock it. Of all threads waiting to lock the mutex, only one may do so at a time.

It is legal for the owning thread to lock an already-locked mutex. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive mutex").

Parameters
mutexthe mutex to lock
Returns
0, or -1 on error.
Since
This function is available since SDL 2.0.0.

◆ SDL_SemPost()

int SDL_SemPost ( SDL_sem sem)
extern

Atomically increment a semaphore's value and wake waiting threads.

Parameters
semthe semaphore to increment
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CreateSemaphore
SDL_DestroySemaphore
SDL_SemTryWait
SDL_SemValue
SDL_SemWait
SDL_SemWaitTimeout

◆ SDL_SemTryWait()

int SDL_SemTryWait ( SDL_sem sem)
extern

See if a semaphore has a positive value and decrement it if it does.

This function checks to see if the semaphore pointed to by sem has a positive value and atomically decrements the semaphore value if it does. If the semaphore doesn't have a positive value, the function immediately returns SDL_MUTEX_TIMEDOUT.

Parameters
semthe semaphore to wait on
Returns
0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait would block, or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CreateSemaphore
SDL_DestroySemaphore
SDL_SemPost
SDL_SemValue
SDL_SemWait
SDL_SemWaitTimeout

◆ SDL_SemValue()

Uint32 SDL_SemValue ( SDL_sem sem)
extern

Get the current value of a semaphore.

Parameters
semthe semaphore to query
Returns
the current value of the semaphore.
Since
This function is available since SDL 2.0.0.
See also
SDL_CreateSemaphore

◆ SDL_SemWait()

int SDL_SemWait ( SDL_sem sem)
extern

Wait until a semaphore has a positive value and then decrements it.

This function suspends the calling thread until either the semaphore pointed to by sem has a positive value or the call is interrupted by a signal or error. If the call is successful it will atomically decrement the semaphore value.

This function is the equivalent of calling SDL_SemWaitTimeout() with a time length of SDL_MUTEX_MAXWAIT.

Parameters
semthe semaphore wait on
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CreateSemaphore
SDL_DestroySemaphore
SDL_SemPost
SDL_SemTryWait
SDL_SemValue
SDL_SemWait
SDL_SemWaitTimeout

◆ SDL_SemWaitTimeout()

int SDL_SemWaitTimeout ( SDL_sem sem,
Uint32  timeout 
)
extern

Wait until a semaphore has a positive value and then decrements it.

This function suspends the calling thread until either the semaphore pointed to by sem has a positive value, the call is interrupted by a signal or error, or the specified time has elapsed. If the call is successful it will atomically decrement the semaphore value.

Parameters
semthe semaphore to wait on
timeoutthe length of the timeout, in milliseconds
Returns
0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in the allotted time, or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CreateSemaphore
SDL_DestroySemaphore
SDL_SemPost
SDL_SemTryWait
SDL_SemValue
SDL_SemWait

◆ SDL_TryLockMutex()

int SDL_TryLockMutex ( SDL_mutex mutex)
extern

Try to lock a mutex without blocking.

This works just like SDL_LockMutex(), but if the mutex is not available, this function returns SDL_MUTEX_TIMEOUT immediately.

This technique is useful if you need exclusive access to a resource but don't want to wait for it, and will return to it to try again later.

Parameters
mutexthe mutex to try to lock
Returns
0, SDL_MUTEX_TIMEDOUT, or -1 on error; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_CreateMutex
SDL_DestroyMutex
SDL_LockMutex
SDL_UnlockMutex

◆ SDL_UnlockMutex()

int SDL_UnlockMutex ( SDL_mutex mutex)
extern

Unlock the mutex.

It is legal for the owning thread to lock an already-locked mutex. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive mutex").

It is an error to unlock a mutex that has not been locked by the current thread, and doing so results in undefined behavior.

It is also an error to unlock a mutex that isn't locked at all.

Parameters
mutexthe mutex to unlock.
Returns
0, or -1 on error.
Since
This function is available since SDL 2.0.0.

Variable Documentation

◆ mutex

int mutex

Definition at line 196 of file SDL_mutex.h.