/Users/hercules/trunk/SDL-1.2/include/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.

Defines
#define	SDL_MUTEX_TIMEDOUT   1
#define	SDL_MUTEX_MAXWAIT   (~(Uint32)0)
Typedefs
Condition_variable_functions
typedef struct SDL_cond	SDL_cond
Functions
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 *mut)
DECLSPEC int SDLCALL	SDL_CondWaitTimeout (SDL_cond *cond, SDL_mutex *mutex, Uint32 ms)
Mutex functions
#define	SDL_LockMutex(m)   SDL_mutexP(m)
#define	SDL_UnlockMutex(m)   SDL_mutexV(m)
typedef struct SDL_mutex	SDL_mutex
DECLSPEC SDL_mutex *SDLCALL	SDL_CreateMutex (void)
DECLSPEC int SDLCALL	SDL_mutexP (SDL_mutex *mutex)
DECLSPEC int SDLCALL	SDL_mutexV (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)

---

Detailed Description

Functions to provide thread synchronization primitives

Note:

These are independent of the other SDL routines.

---

Define Documentation

#define SDL_MUTEX_MAXWAIT   (~(Uint32)0)

This is the timeout value which corresponds to never time out

#define SDL_MUTEX_TIMEDOUT   1

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

---

Function Documentation

DECLSPEC int SDLCALL SDL_CondBroadcast

(

SDL_cond *

cond

)

Restart all threads that are waiting on the condition variable,

Returns:

0 or -1 on error.

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.

DECLSPEC int SDLCALL SDL_CondWait	(	SDL_cond *	cond,
		SDL_mutex *	mut
	)

Wait on the condition variable, unlocking the provided mutex. 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.

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. On some platforms this function is implemented by looping with a delay of 1 ms, and so should be avoided if possible.

DECLSPEC SDL_cond* SDLCALL SDL_CreateCond

(

void

)

Create a condition variable

DECLSPEC SDL_mutex* SDLCALL SDL_CreateMutex

(

void

)

Create a mutex, initialized unlocked

DECLSPEC SDL_sem* SDLCALL SDL_CreateSemaphore

(

Uint32

initial_value

)

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

DECLSPEC void SDLCALL SDL_DestroyCond

(

SDL_cond *

cond

)

Destroy a condition variable

DECLSPEC void SDLCALL SDL_DestroyMutex

(

SDL_mutex *

mutex

)

Destroy a mutex

DECLSPEC void SDLCALL SDL_DestroySemaphore

(

SDL_sem *

sem

)

Destroy a semaphore

DECLSPEC int SDLCALL SDL_mutexP

(

SDL_mutex *

mutex

)

Lock the mutex

Returns:

0, or -1 on error

DECLSPEC int SDLCALL SDL_mutexV

(

SDL_mutex *

mutex

)

Unlock the mutex

Returns:

0, or -1 on error

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

DECLSPEC int SDLCALL SDL_SemPost

(

SDL_sem *

sem

)

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

Returns:

0, or -1 on error.

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.

DECLSPEC Uint32 SDLCALL SDL_SemValue

(

SDL_sem *

sem

)

Returns the current count of the semaphore

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.

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.

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