Documentation

A means to serialize access to a resource between threads.

Mutexes (short for "mutual exclusion") are a synchronization primitive that allows exactly one thread to proceed at a time.

Wikipedia has a thorough explanation of the concept:

https://en.wikipedia.org/wiki/Mutex

C declaration

struct SDL_Mutex, defined at SDL3/SDL_mutex.h 296:16

Since: 3.2.0

A mutex that allows read-only threads to run in parallel.

A rwlock is roughly the same concept as SDL_Mutex, but allows threads that request read-only access to all hold the lock at the same time. If a thread requests write access, it will block until all read-only threads have released the lock, and no one else can hold the thread (for reading or writing) at the same time as the writing thread.

This can be more efficient in cases where several threads need to access data frequently, but changes to that data are rare.

There are other rules that apply to rwlocks that don't apply to mutexes, about how threads are scheduled and when they can be recursively locked. These are documented in the other rwlock functions.

C declaration

struct SDL_RWLock, defined at SDL3/SDL_mutex.h 438:16

Since: 3.2.0

A means to manage access to a resource, by count, between threads.

Semaphores (specifically, "counting semaphores"), let X number of threads request access at the same time, each thread granted access decrementing a counter. When the counter reaches zero, future requests block until a prior thread releases their request, incrementing the counter again.

Wikipedia has a thorough explanation of the concept:

https://en.wikipedia.org/wiki/Semaphore_(programming))

C declaration

struct SDL_Semaphore, defined at SDL3/SDL_mutex.h 684:16

Since: 3.2.0

A means to block multiple threads until a condition is satisfied.

Condition variables, paired with an SDL_Mutex, let an app halt multiple threads until a condition has occurred, at which time the app can release one or all waiting threads.

Wikipedia has a thorough explanation of the concept:

https://en.wikipedia.org/wiki/Condition_variable

C declaration

struct SDL_Condition, defined at SDL3/SDL_mutex.h 841:16

Since: 3.2.0

The current status of an SDL_InitState structure.

C declaration

enum SDL_InitStatus, defined at SDL3/SDL_mutex.h 975:14

Since: 3.2.0

C declaration

SDL_INIT_STATUS_UNINITIALIZED, defined at SDL3/SDL_mutex.h 977:5

C declaration

SDL_INIT_STATUS_INITIALIZING, defined at SDL3/SDL_mutex.h 978:5

C declaration

SDL_INIT_STATUS_INITIALIZED, defined at SDL3/SDL_mutex.h 979:5

C declaration

SDL_INIT_STATUS_UNINITIALIZING, defined at SDL3/SDL_mutex.h 980:5

A structure used for thread-safe initialization and shutdown.

Here is an example of using this:

    static SDL_InitState init;

    bool InitSystem(void)
    {
        if (!SDL_ShouldInit(&init)) {
            // The system is initialized
            return true;
        }

        // At this point, you should not leave this function without calling SDL_SetInitialized()

        bool initialized = DoInitTasks();
        SDL_SetInitialized(&init, initialized);
        return initialized;
    }

    bool UseSubsystem(void)
    {
        if (SDL_ShouldInit(&init)) {
            // Error, the subsystem isn't initialized
            SDL_SetInitialized(&init, false);
            return false;
        }

        // Do work using the initialized subsystem

        return true;
    }

    void QuitSystem(void)
    {
        if (!SDL_ShouldQuit(&init)) {
            // The system is not initialized
            return;
        }

        // At this point, you should not leave this function without calling SDL_SetInitialized()

        DoQuitTasks();
        SDL_SetInitialized(&init, false);
    }
    

Note that this doesn't protect any resources created during initialization, or guarantee that nobody is using those resources during cleanup. You should use other mechanisms to protect those, if that's a concern for your code.

C declaration

struct SDL_InitState, defined at SDL3/SDL_mutex.h 1039:16

Since: 3.2.0