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)

Functions
Semaphore functions
SDL_sem *	SDL_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
SDL_cond *	SDL_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)

Mutex functions
#define	SDL_mutexP(m)   SDL_LockMutex(m)
#define	SDL_mutexV(m)   SDL_UnlockMutex(m)
SDL_mutex *	SDL_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)

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.

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.

Definition at line 106 of file SDL_syscond.c.

{
    if (!cond) {
        return SDL_SetError("Passed a NULL condition variable");
    }
 
    /* If there are waiting threads not already signalled, then
       signal the condition and wait for the thread to respond.
     */
    SDL_LockMutex(cond->lock);
    if (cond->waiting > cond->signals) {
        int i, num_waiting;
 
        num_waiting = (cond->waiting - cond->signals);
        cond->signals = cond->waiting;
        for (i = 0; i < num_waiting; ++i) {
            SDL_SemPost(cond->wait_sem);
        }
        /* Now all released threads are blocked here, waiting for us.
           Collect them all (and win fabulous prizes!) :-)
         */
        SDL_UnlockMutex(cond->lock);
        for (i = 0; i < num_waiting; ++i) {
            SDL_SemWait(cond->wait_done);
        }
    } else {
        SDL_UnlockMutex(cond->lock);
    }
 
    return 0;
}

References cond, i, retval, SDL_LockMutex, SDL_SemPost, SDL_SemWait, SDL_SetError, and SDL_UnlockMutex.

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.

Definition at line 82 of file SDL_syscond.c.

{
    if (!cond) {
        return SDL_SetError("Passed a NULL condition variable");
    }
 
    /* If there are waiting threads not already signalled, then
       signal the condition and wait for the thread to respond.
     */
    SDL_LockMutex(cond->lock);
    if (cond->waiting > cond->signals) {
        ++cond->signals;
        SDL_SemPost(cond->wait_sem);
        SDL_UnlockMutex(cond->lock);
        SDL_SemWait(cond->wait_done);
    } else {
        SDL_UnlockMutex(cond->lock);
    }
 
    return 0;
}

References cond, retval, SDL_LockMutex, SDL_SemPost, SDL_SemWait, SDL_SetError, and SDL_UnlockMutex.

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.

Definition at line 215 of file SDL_syscond.c.

{
    return SDL_CondWaitTimeout(cond, mutex, SDL_MUTEX_MAXWAIT);
}

References cond, SDL_mutex::id, mutex, SDL_CondWaitTimeout(), SDL_MUTEX_MAXWAIT, and SDL_SetError.

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.

Definition at line 160 of file SDL_syscond.c.

{
    int retval;
 
    if (!cond) {
        return SDL_SetError("Passed a NULL condition variable");
    }
 
    /* Obtain the protection mutex, and increment the number of waiters.
       This allows the signal mechanism to only perform a signal if there
       are waiting threads.
     */
    SDL_LockMutex(cond->lock);
    ++cond->waiting;
    SDL_UnlockMutex(cond->lock);
 
    /* Unlock the mutex, as is required by condition variable semantics */
    SDL_UnlockMutex(mutex);
 
    /* Wait for a signal */
    if (ms == SDL_MUTEX_MAXWAIT) {
        retval = SDL_SemWait(cond->wait_sem);
    } else {
        retval = SDL_SemWaitTimeout(cond->wait_sem, ms);
    }
 
    /* Let the signaler know we have completed the wait, otherwise
       the signaler can race ahead and get the condition semaphore
       if we are stopped between the mutex unlock and semaphore wait,
       giving a deadlock.  See the following URL for details:
       http://web.archive.org/web/20010914175514/http://www-classic.be.com/aboutbe/benewsletter/volume_III/Issue40.html#Workshop
     */
    SDL_LockMutex(cond->lock);
    if (cond->signals > 0) {
        /* If we timed out, we need to eat a condition signal */
        if (retval > 0) {
            SDL_SemWait(cond->wait_sem);
        }
        /* We always notify the signal thread that we are done */
        SDL_SemPost(cond->wait_done);
 
        /* Signal handshake complete */
        --cond->signals;
    }
    --cond->waiting;
    SDL_UnlockMutex(cond->lock);
 
    /* Lock the mutex, as is required by condition variable semantics */
    SDL_LockMutex(mutex);
 
    return retval;
}

References cond, SDL_mutex::cpp_mutex, SDL_mutex::id, mutex, NULL, retval, SDL_LockMutex, SDL_MUTEX_MAXWAIT, SDL_MUTEX_TIMEDOUT, SDL_SemPost, SDL_SemWait, SDL_SemWaitTimeout, SDL_SetError, and SDL_UnlockMutex.

Referenced by SDL_CondWait().

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.

Definition at line 42 of file SDL_syscond.c.

{
    SDL_cond *cond;
 
    cond = (SDL_cond *) SDL_malloc(sizeof(SDL_cond));
    if (cond) {
        cond->lock = SDL_CreateMutex();
        cond->wait_sem = SDL_CreateSemaphore(0);
        cond->wait_done = SDL_CreateSemaphore(0);
        cond->waiting = cond->signals = 0;
        if (!cond->lock || !cond->wait_sem || !cond->wait_done) {
            SDL_DestroyCond(cond);
            cond = NULL;
        }
    } else {
        SDL_OutOfMemory();
    }
    return (cond);
}

References cond, NULL, SDL_CreateMutex, SDL_CreateSemaphore, SDL_DestroyCond(), SDL_free, SDL_malloc, SDL_OutOfMemory, and SDL_SetError.

SDL_CreateMutex()

SDL_mutex* SDL_CreateMutex

(

void

)

Create a mutex, initialized unlocked.

Definition at line 38 of file SDL_sysmutex.c.

{
    SDL_mutex *mutex;
 
    /* Allocate mutex memory */
    mutex = (SDL_mutex *) SDL_malloc(sizeof(*mutex));
    if (mutex) {
        /* Create the mutex semaphore, with initial value 1 */
        mutex->sem = SDL_CreateSemaphore(1);
        mutex->recursive = 0;
        mutex->owner = 0;
        if (!mutex->sem) {
            SDL_free(mutex);
            mutex = NULL;
        }
    } else {
        SDL_OutOfMemory();
    }
    return mutex;
}

References SDL_mutex::id, mutex, NULL, SDL_mutex::owner, SDL_mutex::recursive, SDL_calloc, SDL_CreateSemaphore, SDL_free, SDL_malloc, SDL_OutOfMemory, SDL_SetError, and SDL_mutex::sem.

SDL_CreateSemaphore()

SDL_sem* SDL_CreateSemaphore

(

Uint32

initial_value

)

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

Definition at line 85 of file SDL_syssem.c.

{
    SDL_sem *sem;
 
    sem = (SDL_sem *) SDL_malloc(sizeof(*sem));
    if (!sem) {
        SDL_OutOfMemory();
        return NULL;
    }
    sem->count = initial_value;
    sem->waiters_count = 0;
 
    sem->count_lock = SDL_CreateMutex();
    sem->count_nonzero = SDL_CreateCond();
    if (!sem->count_lock || !sem->count_nonzero) {
        SDL_DestroySemaphore(sem);
        return NULL;
    }
 
    return sem;
}

References NULL, SDL_CreateCond, SDL_CreateMutex, SDL_DestroySemaphore(), SDL_free, SDL_malloc, SDL_OutOfMemory, SDL_SetError, and sem.

SDL_DestroyCond()

void SDL_DestroyCond

(

SDL_cond *

cond

)

Destroy a condition variable.

Definition at line 64 of file SDL_syscond.c.

{
    if (cond) {
        if (cond->wait_sem) {
            SDL_DestroySemaphore(cond->wait_sem);
        }
        if (cond->wait_done) {
            SDL_DestroySemaphore(cond->wait_done);
        }
        if (cond->lock) {
            SDL_DestroyMutex(cond->lock);
        }
        SDL_free(cond);
    }
}

References cond, SDL_DestroyMutex, SDL_DestroySemaphore, and SDL_free.

Referenced by SDL_CreateCond().

SDL_DestroyMutex()

void SDL_DestroyMutex

(

SDL_mutex *

mutex

)

Destroy a mutex.

Definition at line 61 of file SDL_sysmutex.c.

{
    if (mutex) {
        if (mutex->sem) {
            SDL_DestroySemaphore(mutex->sem);
        }
        SDL_free(mutex);
    }
}

References SDL_mutex::id, mutex, SDL_DestroySemaphore, SDL_free, and SDL_mutex::sem.

SDL_DestroySemaphore()

void SDL_DestroySemaphore

(

SDL_sem *

sem

)

Destroy a semaphore.

Definition at line 111 of file SDL_syssem.c.

{
    if (sem) {
        sem->count = 0xFFFFFFFF;
        while (sem->waiters_count > 0) {
            SDL_CondSignal(sem->count_nonzero);
            SDL_Delay(10);
        }
        SDL_DestroyCond(sem->count_nonzero);
        if (sem->count_lock) {
            SDL_LockMutex(sem->count_lock);
            SDL_UnlockMutex(sem->count_lock);
            SDL_DestroyMutex(sem->count_lock);
        }
        SDL_free(sem);
    }
}

References SDL_CondSignal, SDL_Delay, SDL_DestroyCond, SDL_DestroyMutex, SDL_free, SDL_LockMutex, SDL_UnlockMutex, and sem.

Referenced by SDL_CreateSemaphore().

SDL_LockMutex()

int SDL_LockMutex

(

SDL_mutex *

mutex

)

Definition at line 73 of file SDL_sysmutex.c.

{
#if SDL_THREADS_DISABLED
    return 0;
#else
    SDL_threadID this_thread;
 
    if (mutex == NULL) {
        return SDL_SetError("Passed a NULL mutex");
    }
 
    this_thread = SDL_ThreadID();
    if (mutex->owner == this_thread) {
        ++mutex->recursive;
    } else {
        /* The order of operations is important.
           We set the locking thread id after we obtain the lock
           so unlocks from other threads will fail.
         */
        SDL_SemWait(mutex->sem);
        mutex->owner = this_thread;
        mutex->recursive = 0;
    }
 
    return 0;
#endif /* SDL_THREADS_DISABLED */
}

References SDL_mutex::id, mutex, NULL, SDL_mutex::owner, SDL_mutex::recursive, SDL_SemWait, SDL_SetError, SDL_ThreadID, and SDL_mutex::sem.

SDL_SemPost()

int SDL_SemPost

(

SDL_sem *

sem

)

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

Returns

0, or -1 on error.

Definition at line 200 of file SDL_syssem.c.

{
    if (!sem) {
        return SDL_SetError("Passed a NULL semaphore");
    }
 
    SDL_LockMutex(sem->count_lock);
    if (sem->waiters_count > 0) {
        SDL_CondSignal(sem->count_nonzero);
    }
    ++sem->count;
    SDL_UnlockMutex(sem->count_lock);
 
    return 0;
}

References retval, SDL_CondSignal, SDL_LockMutex, SDL_SetError, SDL_UnlockMutex, and sem.

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.

Definition at line 130 of file SDL_syssem.c.

{
    int retval;
 
    if (!sem) {
        return SDL_SetError("Passed a NULL semaphore");
    }
 
    retval = SDL_MUTEX_TIMEDOUT;
    SDL_LockMutex(sem->count_lock);
    if (sem->count > 0) {
        --sem->count;
        retval = 0;
    }
    SDL_UnlockMutex(sem->count_lock);
 
    return retval;
}

References retval, SDL_LockMutex, SDL_MUTEX_TIMEDOUT, SDL_SetError, SDL_UnlockMutex, and sem.

Referenced by SDL_SemWaitTimeout().

SDL_SemValue()

Uint32 SDL_SemValue

(

SDL_sem *

sem

)

Returns the current count of the semaphore.

Definition at line 186 of file SDL_syssem.c.

{
    Uint32 value;
 
    value = 0;
    if (sem) {
        SDL_LockMutex(sem->count_lock);
        value = sem->count;
        SDL_UnlockMutex(sem->count_lock);
    }
    return value;
}

References SDL_LockMutex, SDL_UnlockMutex, and sem.

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.

Definition at line 180 of file SDL_syssem.c.

{
    return SDL_SemWaitTimeout(sem, SDL_MUTEX_MAXWAIT);
}

References retval, SDL_MUTEX_MAXWAIT, SDL_SemWaitTimeout(), SDL_SetError, and sem.

Referenced by SDL_SemWaitTimeout().

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.

Definition at line 150 of file SDL_syssem.c.

{
    int retval;
 
    if (!sem) {
        return SDL_SetError("Passed a NULL semaphore");
    }
 
    /* A timeout of 0 is an easy case */
    if (timeout == 0) {
        return SDL_SemTryWait(sem);
    }
 
    SDL_LockMutex(sem->count_lock);
    ++sem->waiters_count;
    retval = 0;
    while ((sem->count == 0) && (retval != SDL_MUTEX_TIMEDOUT)) {
        retval = SDL_CondWaitTimeout(sem->count_nonzero,
                                     sem->count_lock, timeout);
    }
    --sem->waiters_count;
    if (retval == 0) {
        --sem->count;
    }
    SDL_UnlockMutex(sem->count_lock);
 
    return retval;
}

References NULL, retval, SDL_CondWaitTimeout, SDL_Delay, SDL_GetTicks(), SDL_LockMutex, SDL_MUTEX_MAXWAIT, SDL_MUTEX_TIMEDOUT, SDL_SemTryWait(), SDL_SemWait(), SDL_SetError, SDL_TICKS_PASSED, SDL_UnlockMutex, and sem.

Referenced by SDL_SemWait().

SDL_TryLockMutex()

int SDL_TryLockMutex

(

SDL_mutex *

mutex

)

Try to lock the mutex

Returns

0, SDL_MUTEX_TIMEDOUT, or -1 on error

Definition at line 103 of file SDL_sysmutex.c.

{
#if SDL_THREADS_DISABLED
    return 0;
#else
    int retval = 0;
    SDL_threadID this_thread;
 
    if (mutex == NULL) {
        return SDL_SetError("Passed a NULL mutex");
    }
 
    this_thread = SDL_ThreadID();
    if (mutex->owner == this_thread) {
        ++mutex->recursive;
    } else {
        /* The order of operations is important.
         We set the locking thread id after we obtain the lock
         so unlocks from other threads will fail.
         */
        retval = SDL_SemWait(mutex->sem);
        if (retval == 0) {
            mutex->owner = this_thread;
            mutex->recursive = 0;
        }
    }
 
    return retval;
#endif /* SDL_THREADS_DISABLED */
}

References SDL_mutex::cpp_mutex, SDL_mutex::id, mutex, NULL, SDL_mutex::owner, SDL_mutex::recursive, retval, SDL_MUTEX_TIMEDOUT, SDL_SemWait, SDL_SetError, SDL_ThreadID, and SDL_mutex::sem.

SDL_UnlockMutex()

int SDL_UnlockMutex

(

SDL_mutex *

mutex

)

Definition at line 162 of file SDL_sysmutex.c.

{
    if (mutex == NULL) {
        return SDL_SetError("Passed a NULL mutex");
    }
 
#if FAKE_RECURSIVE_MUTEX
    /* We can only unlock the mutex if we own it */
    if (pthread_self() == mutex->owner) {
        if (mutex->recursive) {
            --mutex->recursive;
        } else {
            /* The order of operations is important.
               First reset the owner so another thread doesn't lock
               the mutex and set the ownership before we reset it,
               then release the lock semaphore.
             */
            mutex->owner = 0;
            pthread_mutex_unlock(&mutex->id);
        }
    } else {
        return SDL_SetError("mutex not owned by this thread");
    }
 
#else
    if (pthread_mutex_unlock(&mutex->id) != 0) {
        return SDL_SetError("pthread_mutex_unlock() failed");
    }
#endif /* FAKE_RECURSIVE_MUTEX */
 
    return 0;
}

References SDL_mutex::id, mutex, NULL, SDL_mutex::owner, SDL_mutex::recursive, and SDL_SetError.