SDL_mutex.h File Reference

#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "begin_code.h"
#include "close_code.h"

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
DECLSPEC SDL_mutex *SDLCALL	SDL_CreateMutex (void)
DECLSPEC int SDLCALL	SDL_LockMutex (SDL_mutex *mutex)
DECLSPEC int SDLCALL	SDL_TryLockMutex (SDL_mutex *mutex)
DECLSPEC int SDLCALL	SDL_UnlockMutex (SDL_mutex *mutex)
DECLSPEC void SDLCALL	SDL_DestroyMutex (SDL_mutex *mutex)

Semaphore functions
typedef struct SDL_semaphore	SDL_sem
DECLSPEC SDL_sem *SDLCALL	SDL_CreateSemaphore (Uint32 initial_value)
DECLSPEC void SDLCALL	SDL_DestroySemaphore (SDL_sem *sem)
DECLSPEC int SDLCALL	SDL_SemWait (SDL_sem *sem)
DECLSPEC int SDLCALL	SDL_SemTryWait (SDL_sem *sem)
DECLSPEC int SDLCALL	SDL_SemWaitTimeout (SDL_sem *sem, Uint32 ms)
DECLSPEC int SDLCALL	SDL_SemPost (SDL_sem *sem)
DECLSPEC Uint32 SDLCALL	SDL_SemValue (SDL_sem *sem)

Condition variable functions
typedef struct SDL_cond	SDL_cond
DECLSPEC SDL_cond *SDLCALL	SDL_CreateCond (void)
DECLSPEC void SDLCALL	SDL_DestroyCond (SDL_cond *cond)
DECLSPEC int SDLCALL	SDL_CondSignal (SDL_cond *cond)
DECLSPEC int SDLCALL	SDL_CondBroadcast (SDL_cond *cond)
DECLSPEC int SDLCALL	SDL_CondWait (SDL_cond *cond, SDL_mutex *mutex)
DECLSPEC int SDLCALL	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()

DECLSPEC int SDLCALL SDL_CondBroadcast

(

SDL_cond *

cond

)

Restart all threads that are waiting on the condition variable.

Returns

0 or -1 on error.

SDL_CondSignal()

DECLSPEC int SDLCALL 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()

DECLSPEC int SDLCALL 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()

DECLSPEC int SDLCALL 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()

DECLSPEC SDL_cond* SDLCALL 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()

DECLSPEC SDL_mutex* SDLCALL SDL_CreateMutex

(

void

)

Create a mutex, initialized unlocked.

SDL_CreateSemaphore()

DECLSPEC SDL_sem* SDLCALL SDL_CreateSemaphore

(

Uint32

initial_value

)

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

SDL_DestroyCond()

DECLSPEC void SDLCALL SDL_DestroyCond

(

SDL_cond *

cond

)

Destroy a condition variable.

SDL_DestroyMutex()

DECLSPEC void SDLCALL SDL_DestroyMutex

(

SDL_mutex *

mutex

)

Destroy a mutex.

SDL_DestroySemaphore()

DECLSPEC void SDLCALL SDL_DestroySemaphore

(

SDL_sem *

sem

)

Destroy a semaphore.

SDL_LockMutex()

DECLSPEC int SDLCALL SDL_LockMutex

(

SDL_mutex *

mutex

)

SDL_SemPost()

DECLSPEC int SDLCALL SDL_SemPost

(

SDL_sem *

sem

)

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

Returns

0, or -1 on error.

SDL_SemTryWait()

DECLSPEC int SDLCALL 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()

DECLSPEC Uint32 SDLCALL SDL_SemValue

(

SDL_sem *

sem

)

Returns the current count of the semaphore.

SDL_SemWait()

DECLSPEC int SDLCALL 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()

DECLSPEC int SDLCALL 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()

DECLSPEC int SDLCALL SDL_TryLockMutex

(

SDL_mutex *

mutex

)

Try to lock the mutex

Returns

0, SDL_MUTEX_TIMEDOUT, or -1 on error

SDL_UnlockMutex()

DECLSPEC int SDLCALL SDL_UnlockMutex

(

SDL_mutex *

mutex

)