Code Map
module lib.sdl2.mutex;
//! Synchronization functions which can time out return this value if they
//! time out.
enum SDL_MUTEX_TIMEDOUT;
//! \name Mutex functions
struct SDL_mutex
{
}
//! \name Semaphore functions
struct SDL_semaphore
{
}
//! \name Condition variable functions
struct SDL_cond
{
}
//! This is the timeout value which corresponds to never time out.
fn SDL_MUTEX_MAXWAIT() Uint32 { }
//! Create a mutex, initialized unlocked.
fn SDL_CreateMutex() SDL_mutex*;
//! Lock the mutex.
fn SDL_LockMutex(mutex: SDL_mutex*) i32;
//! Try to lock the mutex
fn SDL_TryLockMutex(mutex: SDL_mutex*) i32;
//! Unlock the mutex.
fn SDL_UnlockMutex(mutex: SDL_mutex*) i32;
//! Destroy a mutex.
fn SDL_DestroyMutex(mutex: SDL_mutex*);
//! Create a semaphore, initialized with value, returns NULL on failure.
fn SDL_CreateSemaphore(initial_value: Uint32) SDL_semaphore*;
//! Destroy a semaphore.
fn SDL_DestroySemaphore(sem: SDL_semaphore*);
//! This function suspends the calling thread until the semaphore pointed
//! to by \c sem has a positive count. It then atomically decreases the
//! semaphore count.
fn SDL_SemWait(sem: SDL_semaphore*) i32;
//! Non-blocking variant of SDL_SemWait().
fn SDL_SemTryWait(sem: SDL_semaphore*) i32;
//! Variant of SDL_SemWait() with a timeout in milliseconds.
fn SDL_SemWaitTimeout(sem: SDL_semaphore*, ms: Uint32) i32;
//! Atomically increases the semaphore's count (not blocking).
fn SDL_SemPost(sem: SDL_semaphore*) i32;
//! Returns the current count of the semaphore.
fn SDL_SemValue(sem: SDL_semaphore*) Uint32;
//! Create a condition variable.
fn SDL_CreateCond() SDL_cond*;
//! Destroy a condition variable.
fn SDL_DestroyCond(cond: SDL_cond*);
//! Restart one of the threads that are waiting on the condition variable.
fn SDL_CondSignal(cond: SDL_cond*) i32;
//! Restart all threads that are waiting on the condition variable.
fn SDL_CondBroadcast(cond: SDL_cond*) i32;
//! Wait on the condition variable, unlocking the provided mutex.
fn SDL_CondWait(cond: SDL_cond*, mutex: SDL_mutex*) i32;
//! Waits for at most \c 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.
fn SDL_CondWaitTimeout(cond: SDL_cond*, mutex: SDL_mutex*, ms: Uint32) i32;
Synchronization functions which can time out return this value if they time out.
This is the timeout value which corresponds to never time out.
\name Mutex functions
Create a mutex, initialized unlocked.
Lock the mutex.
\return 0, or -1 on error.
Try to lock the mutex
\return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
Unlock the mutex.
\return 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.
Destroy a mutex.
\name Semaphore functions
Create a semaphore, initialized with value, returns NULL on failure.
Destroy a semaphore.
This function suspends the calling thread until the semaphore pointed to by \c sem has a positive count. It then atomically decreases the semaphore count.
Non-blocking variant of SDL_SemWait().
\return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
Variant of SDL_SemWait() with a timeout in milliseconds.
\return 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.
Atomically increases the semaphore's count (not blocking).
\return 0, or -1 on error.
Returns the current count of the semaphore.
\name Condition variable functions
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.
Destroy a condition variable.
Restart one of the threads that are waiting on the condition variable.
\return 0 or -1 on error.
Restart all threads that are waiting on the condition variable.
\return 0 or -1 on error.
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.
\return 0 when it is signaled, or -1 on error.
Waits for at most \c 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.