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_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
 
SDL_mutexSDL_CreateMutex (void)
 
int SDL_LockMutex (SDL_mutex *mutex)
 
int SDL_TryLockMutex (SDL_mutex *mutex)
 
int SDL_UnlockMutex (SDL_mutex *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 ms)
 
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_MUTEX_MAXWAIT

#define SDL_MUTEX_MAXWAIT   (~(Uint32)0)

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

Definition at line 49 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 44 of file SDL_mutex.h.

◆ SDL_mutexP

#define SDL_mutexP (   m)    SDL_LockMutex(m)

Lock the mutex.

Returns
0, or -1 on error.

Definition at line 71 of file SDL_mutex.h.

◆ SDL_mutexV

#define SDL_mutexV (   m)    SDL_UnlockMutex(m)

Unlock the mutex.

Returns
0, or -1 on error.
Warning
It is an error to unlock a mutex that has not been locked by the current thread, and doing so results in undefined behavior.

Definition at line 89 of file SDL_mutex.h.

Typedef Documentation

◆ SDL_cond

typedef struct SDL_cond SDL_cond

Definition at line 167 of file SDL_mutex.h.

◆ SDL_mutex

typedef struct SDL_mutex SDL_mutex

Definition at line 59 of file SDL_mutex.h.

◆ SDL_sem

typedef struct SDL_semaphore SDL_sem

Definition at line 107 of file SDL_mutex.h.

Function Documentation

◆ SDL_CondBroadcast()

int SDL_CondBroadcast ( SDL_cond cond)

Restart all threads that are waiting on the condition variable.

Returns
0 or -1 on error.

◆ SDL_CondSignal()

int SDL_CondSignal ( SDL_cond cond)

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

Returns
0 or -1 on error.

◆ SDL_CondWait()

int SDL_CondWait ( SDL_cond cond,
SDL_mutex mutex 
)

Wait on the condition variable, unlocking the provided mutex.

Warning
The mutex must be locked before entering this function!

The mutex is re-locked once the condition variable is signaled.

Returns
0 when it is signaled, or -1 on error.

◆ SDL_CondWaitTimeout()

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

Waits for at most ms milliseconds, and returns 0 if the condition variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not signaled in the allotted time, and -1 on error.

Warning
On some platforms this function is implemented by looping with a delay of 1 ms, and so should be avoided if possible.

◆ SDL_CreateCond()

SDL_cond* SDL_CreateCond ( void  )

Create a condition variable.

Typical use of condition variables:

Thread A: SDL_LockMutex(lock); while ( ! condition ) { SDL_CondWait(cond, lock); } SDL_UnlockMutex(lock);

Thread B: SDL_LockMutex(lock); ... condition = true; ... SDL_CondSignal(cond); SDL_UnlockMutex(lock);

There is some discussion whether to signal the condition variable with the mutex locked or not. There is some potential performance benefit to unlocking first on some platforms, but there are some potential race conditions depending on how your code is structured.

In general it's safer to signal the condition variable while the mutex is locked.

◆ SDL_CreateMutex()

SDL_mutex* SDL_CreateMutex ( void  )

Create a mutex, initialized unlocked.

◆ SDL_CreateSemaphore()

SDL_sem* SDL_CreateSemaphore ( Uint32  initial_value)

Create a semaphore, initialized with value, returns NULL on failure.

◆ SDL_DestroyCond()

void SDL_DestroyCond ( SDL_cond cond)

Destroy a condition variable.

◆ SDL_DestroyMutex()

void SDL_DestroyMutex ( SDL_mutex mutex)

Destroy a mutex.

◆ SDL_DestroySemaphore()

void SDL_DestroySemaphore ( SDL_sem sem)

Destroy a semaphore.

◆ SDL_LockMutex()

int SDL_LockMutex ( SDL_mutex mutex)

◆ SDL_SemPost()

int SDL_SemPost ( SDL_sem sem)

Atomically increases the semaphore's count (not blocking).

Returns
0, or -1 on error.

◆ SDL_SemTryWait()

int SDL_SemTryWait ( SDL_sem sem)

Non-blocking variant of SDL_SemWait().

Returns
0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.

◆ SDL_SemValue()

Uint32 SDL_SemValue ( SDL_sem sem)

Returns the current count of the semaphore.

◆ SDL_SemWait()

int SDL_SemWait ( SDL_sem sem)

This function suspends the calling thread until the semaphore pointed to by sem has a positive count. It then atomically decreases the semaphore count.

◆ SDL_SemWaitTimeout()

int SDL_SemWaitTimeout ( SDL_sem sem,
Uint32  ms 
)

Variant of SDL_SemWait() with a timeout in milliseconds.

Returns
0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in the allotted time, and -1 on error.
Warning
On some platforms this function is implemented by looping with a delay of 1 ms, and so should be avoided if possible.

◆ SDL_TryLockMutex()

int SDL_TryLockMutex ( SDL_mutex mutex)

Try to lock the mutex

Returns
0, SDL_MUTEX_TIMEDOUT, or -1 on error

◆ SDL_UnlockMutex()

int SDL_UnlockMutex ( SDL_mutex mutex)