SDL offers several thread synchronization primitives. More...

Collaboration diagram for Thread Synchronization Primitives:

Classes
struct	SDL::MutexParam
	Safely wrap Mutex for non owning parameters. More...

struct	SDL::RWLockParam
	Safely wrap RWLock for non owning parameters. More...

struct	SDL::SemaphoreParam
	Safely wrap Semaphore for non owning parameters. More...

struct	SDL::ConditionParam
	Safely wrap Condition for non owning parameters. More...

class	SDL::Mutex
	A means to serialize access to a resource between threads. More...

struct	SDL::MutexRef
	Semi-safe reference for Mutex. More...

class	SDL::RWLock
	A mutex that allows read-only threads to run in parallel. More...

struct	SDL::RWLockRef
	Semi-safe reference for RWLock. More...

class	SDL::Semaphore
	A means to manage access to a resource, by count, between threads. More...

struct	SDL::SemaphoreRef
	Semi-safe reference for Semaphore. More...

class	SDL::Condition
	A means to block multiple threads until a condition is satisfied. More...

struct	SDL::ConditionRef
	Semi-safe reference for Condition. More...

struct	SDL::InitState
	A structure used for thread-safe initialization and shutdown. More...

Typedefs
using	SDL::MutexRaw = SDL_Mutex *
	Alias to raw representation for Mutex.

using	SDL::RWLockRaw = SDL_RWLock *
	Alias to raw representation for RWLock.

using	SDL::SemaphoreRaw = SDL_Semaphore *
	Alias to raw representation for Semaphore.

using	SDL::ConditionRaw = SDL_Condition *
	Alias to raw representation for Condition.

using	SDL::InitStateRaw = SDL_InitState
	Alias to raw representation for InitState.

using	SDL::InitStatus = SDL_InitStatus
	The current status of an InitState structure. More...

Functions
Mutex	SDL::CreateMutex ()
	Create a new mutex. More...

void	SDL::LockMutex (MutexParam mutex)
	Lock the mutex. More...

void	SDL::TryLockMutex (MutexParam mutex)
	Try to lock a mutex without blocking. More...

void	SDL::UnlockMutex (MutexParam mutex)
	Unlock the mutex. More...

void	SDL::DestroyMutex (MutexRaw mutex)
	Destroy a mutex created with Mutex.Mutex(). More...

RWLock	SDL::CreateRWLock ()
	Create a new read/write lock. More...

void	SDL::LockRWLockForReading (RWLockParam rwlock)
	Lock the read/write lock for read only operations. More...

void	SDL::LockRWLockForWriting (RWLockParam rwlock)
	Lock the read/write lock for write operations. More...

void	SDL::TryLockRWLockForReading (RWLockParam rwlock)
	Try to lock a read/write lock for reading without blocking. More...

void	SDL::TryLockRWLockForWriting (RWLockParam rwlock)
	Try to lock a read/write lock for writing without blocking. More...

void	SDL::UnlockRWLock (RWLockParam rwlock)
	Unlock the read/write lock. More...

void	SDL::DestroyRWLock (RWLockRaw rwlock)
	Destroy a read/write lock created with RWLock.RWLock(). More...

Semaphore	SDL::CreateSemaphore (Uint32 initial_value)
	Create a semaphore. More...

void	SDL::DestroySemaphore (SemaphoreRaw sem)
	Destroy a semaphore. More...

void	SDL::WaitSemaphore (SemaphoreParam sem)
	Wait until a semaphore has a positive value and then decrements it. More...

bool	SDL::TryWaitSemaphore (SemaphoreParam sem)
	See if a semaphore has a positive value and decrement it if it does. More...

bool	SDL::WaitSemaphoreTimeout (SemaphoreParam sem, std::chrono::milliseconds timeout)
	Wait until a semaphore has a positive value and then decrements it. More...

void	SDL::SignalSemaphore (SemaphoreParam sem)
	Atomically increment a semaphore's value and wake waiting threads. More...

Uint32	SDL::GetSemaphoreValue (SemaphoreParam sem)
	Get the current value of a semaphore. More...

Condition	SDL::CreateCondition ()
	Create a condition variable. More...

void	SDL::DestroyCondition (ConditionRaw cond)
	Destroy a condition variable. More...

void	SDL::SignalCondition (ConditionParam cond)
	Restart one of the threads that are waiting on the condition variable. More...

void	SDL::BroadcastCondition (ConditionParam cond)
	Restart all threads that are waiting on the condition variable. More...

void	SDL::WaitCondition (ConditionParam cond, MutexParam mutex)
	Wait until a condition variable is signaled. More...

bool	SDL::WaitConditionTimeout (ConditionParam cond, MutexParam mutex, std::chrono::milliseconds timeout)
	Wait until a condition variable is signaled or a certain time has passed. More...

bool	SDL::ShouldInit (InitStateRaw *state)
	Return whether initialization should be done. More...

bool	SDL::ShouldQuit (InitStateRaw *state)
	Return whether cleanup should be done. More...

void	SDL::SetInitialized (InitStateRaw *state, bool initialized)
	Finish an initialization state transition. More...

void	SDL::Mutex::Lock ()
	Lock the mutex. More...

void	SDL::Mutex::TryLock ()
	Try to lock a mutex without blocking. More...

void	SDL::Mutex::Unlock ()
	Unlock the mutex. More...

void	SDL::Mutex::Destroy ()
	Destroy a mutex created with Mutex.Mutex(). More...

void	SDL::RWLock::LockForReading ()
	Lock the read/write lock for read only operations. More...

void	SDL::RWLock::LockForWriting ()
	Lock the read/write lock for write operations. More...

void	SDL::RWLock::TryLockForReading ()
	Try to lock a read/write lock for reading without blocking. More...

void	SDL::RWLock::TryLockForWriting ()
	Try to lock a read/write lock for writing without blocking. More...

void	SDL::RWLock::Unlock ()
	Unlock the read/write lock. More...

void	SDL::RWLock::Destroy ()
	Destroy a read/write lock created with RWLock.RWLock(). More...

void	SDL::Semaphore::Destroy ()
	Destroy a semaphore. More...

void	SDL::Semaphore::Wait ()
	Wait until a semaphore has a positive value and then decrements it. More...

bool	SDL::Semaphore::TryWait ()
	See if a semaphore has a positive value and decrement it if it does. More...

bool	SDL::Semaphore::WaitTimeout (std::chrono::milliseconds timeout)
	Wait until a semaphore has a positive value and then decrements it. More...

void	SDL::Semaphore::Signal ()
	Atomically increment a semaphore's value and wake waiting threads. More...

Uint32	SDL::Semaphore::GetValue () const
	Get the current value of a semaphore. More...

void	SDL::Condition::Destroy ()
	Destroy a condition variable. More...

void	SDL::Condition::Signal ()
	Restart one of the threads that are waiting on the condition variable. More...

void	SDL::Condition::Broadcast ()
	Restart all threads that are waiting on the condition variable. More...

void	SDL::Condition::Wait (MutexParam mutex)
	Wait until a condition variable is signaled. More...

bool	SDL::Condition::WaitTimeout (MutexParam mutex, std::chrono::milliseconds timeout)
	Wait until a condition variable is signaled or a certain time has passed. More...

bool	SDL::InitState::ShouldInit ()
	Return whether initialization should be done. More...

bool	SDL::InitState::ShouldQuit ()
	Return whether cleanup should be done. More...

void	SDL::InitState::SetInitialized (bool initialized)
	Finish an initialization state transition. More...

Variables
constexpr InitStatus	SDL::INIT_STATUS_UNINITIALIZED
	INIT_STATUS_UNINITIALIZED. More...

constexpr InitStatus	SDL::INIT_STATUS_INITIALIZING
	INIT_STATUS_INITIALIZING. More...

constexpr InitStatus	SDL::INIT_STATUS_INITIALIZED
	INIT_STATUS_INITIALIZED. More...

constexpr InitStatus	SDL::INIT_STATUS_UNINITIALIZING
	INIT_STATUS_UNINITIALIZING. More...

Detailed Description

This document can't cover the complicated topic of thread safety, but reading up on what each of these primitives are, why they are useful, and how to correctly use them is vital to writing correct and safe multithreaded programs.

Mutexes: Mutex.Mutex()
Read/Write locks: RWLock.RWLock()
Semaphores: Semaphore.Semaphore()
Condition variables: Condition.Condition()

SDL also offers a datatype, InitState, which can be used to make sure only one thread initializes/deinitializes some resource that several threads might try to use for the first time simultaneously.

Typedef Documentation

◆ InitStatus

using SDL::InitStatus = typedef SDL_InitStatus

Since: This enum is available since SDL 3.2.0.

Function Documentation

◆ Broadcast()

void SDL::Condition::Broadcast ( )

inline

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Condition.Signal; Condition.Wait; Condition.WaitTimeout

◆ BroadcastCondition()

void SDL::BroadcastCondition ( ConditionParam cond )

inline

Parameters

cond	the condition variable to signal.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Condition.Signal; Condition.Wait; Condition.WaitTimeout

◆ CreateCondition()

Condition SDL::CreateCondition ( )

inline

Returns: a new condition variable or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: Condition.Broadcast; Condition.Signal; Condition.Wait; Condition.WaitTimeout; Condition.Destroy

◆ CreateMutex()

Mutex SDL::CreateMutex ( )

inline

All newly-created mutexes begin in the unlocked state.

Calls to Mutex.Lock() will not return while the mutex is locked by another thread. See Mutex.TryLock() to attempt to lock without blocking.

SDL mutexes are reentrant.

Returns: the initialized and unlocked mutex or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: Mutex.Destroy; Mutex.Lock; Mutex.TryLock; Mutex.Unlock

◆ CreateRWLock()

RWLock SDL::CreateRWLock ( )

inline

A read/write lock is useful for situations where you have multiple threads trying to access a resource that is rarely updated. All threads requesting a read-only lock will be allowed to run in parallel; if a thread requests a write lock, it will be provided exclusive access. This makes it safe for multiple threads to use a resource at the same time if they promise not to change it, and when it has to be changed, the rwlock will serve as a gateway to make sure those changes can be made safely.

In the right situation, a rwlock can be more efficient than a mutex, which only lets a single thread proceed at a time, even if it won't be modifying the data.

All newly-created read/write locks begin in the unlocked state.

Calls to RWLock.LockForReading() and RWLock.LockForWriting will not return while the rwlock is locked for writing by another thread. See RWLock.TryLockForReading() and RWLock.TryLockForWriting() to attempt to lock without blocking.

SDL read/write locks are only recursive for read-only locks! They are not guaranteed to be fair, or provide access in a FIFO manner! They are not guaranteed to favor writers. You may not lock a rwlock for both read-only and write access at the same time from the same thread (so you can't promote your read-only lock to a write lock without unlocking first).

Returns: the initialized and unlocked read/write lock or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: RWLock.Destroy; RWLock.LockForReading; RWLock.LockForWriting; RWLock.TryLockForReading; RWLock.TryLockForWriting; RWLock.Unlock

◆ CreateSemaphore()

Semaphore SDL::CreateSemaphore ( Uint32 initial_value )

inline

This function creates a new semaphore and initializes it with the value initial_value. Each wait operation on the semaphore will atomically decrement the semaphore value and potentially block if the semaphore value is 0. Each post operation will atomically increment the semaphore value and wake waiting threads and allow them to retry the wait operation.

Parameters

initial_value the starting value of the semaphore.

Returns: a new semaphore or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Destroy; Semaphore.Signal; Semaphore.TryWait; Semaphore.GetValue; Semaphore.Wait; Semaphore.WaitTimeout

◆ Destroy() [1/4]

void SDL::Mutex::Destroy ( )

inline

This function must be called on any mutex that is no longer needed. Failure to destroy a mutex will result in a system memory or resource leak. While it is safe to destroy a mutex that is unlocked, it is not safe to attempt to destroy a locked mutex, and may result in undefined behavior depending on the platform.

Since: This function is available since SDL 3.2.0.

See also: Mutex.Mutex

◆ Destroy() [2/4]

void SDL::RWLock::Destroy ( )

inline

This function must be called on any read/write lock that is no longer needed. Failure to destroy a rwlock will result in a system memory or resource leak. While it is safe to destroy a rwlock that is unlocked, it is not safe to attempt to destroy a locked rwlock, and may result in undefined behavior depending on the platform.

Since: This function is available since SDL 3.2.0.

See also: RWLock.RWLock

◆ Destroy() [3/4]

void SDL::Semaphore::Destroy ( )

inline

It is not safe to destroy a semaphore if there are threads currently waiting on it.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Semaphore

◆ Destroy() [4/4]

void SDL::Condition::Destroy ( )

inline

Since: This function is available since SDL 3.2.0.

See also: Condition.Condition

◆ DestroyCondition()

void SDL::DestroyCondition ( ConditionRaw cond )

inline

Parameters

cond	the condition variable to destroy.

Since: This function is available since SDL 3.2.0.

See also: Condition.Condition

◆ DestroyMutex()

void SDL::DestroyMutex ( MutexRaw mutex )

inline

This function must be called on any mutex that is no longer needed. Failure to destroy a mutex will result in a system memory or resource leak. While it is safe to destroy a mutex that is unlocked, it is not safe to attempt to destroy a locked mutex, and may result in undefined behavior depending on the platform.

Parameters

mutex the mutex to destroy.

Since: This function is available since SDL 3.2.0.

See also: Mutex.Mutex

◆ DestroyRWLock()

void SDL::DestroyRWLock ( RWLockRaw rwlock )

inline

This function must be called on any read/write lock that is no longer needed. Failure to destroy a rwlock will result in a system memory or resource leak. While it is safe to destroy a rwlock that is unlocked, it is not safe to attempt to destroy a locked rwlock, and may result in undefined behavior depending on the platform.

Parameters

rwlock the rwlock to destroy.

Since: This function is available since SDL 3.2.0.

See also: RWLock.RWLock

◆ DestroySemaphore()

void SDL::DestroySemaphore ( SemaphoreRaw sem )

inline

It is not safe to destroy a semaphore if there are threads currently waiting on it.

Parameters

sem	the semaphore to destroy.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Semaphore

◆ GetSemaphoreValue()

Uint32 SDL::GetSemaphoreValue ( SemaphoreParam sem )

inline

Parameters

sem	the semaphore to query.

Returns: the current value of the semaphore.

Since: This function is available since SDL 3.2.0.

◆ GetValue()

Uint32 SDL::Semaphore::GetValue ( ) const

inline

Returns: the current value of the semaphore.

Since: This function is available since SDL 3.2.0.

◆ Lock()

void SDL::Mutex::Lock ( )

inline

This will block until the mutex is available, which is to say it is in the unlocked state and the OS has chosen the caller as the next thread to lock it. Of all threads waiting to lock the mutex, only one may do so at a time.

It is legal for the owning thread to lock an already-locked mutex. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive mutex").

This function does not fail; if mutex is nullptr, it will return immediately having locked nothing. If the mutex is valid, this function will always block until it can lock the mutex, and return with it locked.

Since: This function is available since SDL 3.2.0.

See also: Mutex.TryLock; Mutex.Unlock

◆ LockForReading()

void SDL::RWLock::LockForReading ( )

inline

This will block until the rwlock is available, which is to say it is not locked for writing by any other thread. Of all threads waiting to lock the rwlock, all may do so at the same time as long as they are requesting read-only access; if a thread wants to lock for writing, only one may do so at a time, and no other threads, read-only or not, may hold the lock at the same time.

It is legal for the owning thread to lock an already-locked rwlock for reading. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive rwlock").

Note that locking for writing is not recursive (this is only available to read-only locks).

It is illegal to request a read-only lock from a thread that already holds the write lock. Doing so results in undefined behavior. Unlock the write lock before requesting a read-only lock. (But, of course, if you have the write lock, you don't need further locks to read in any case.)

This function does not fail; if rwlock is nullptr, it will return immediately having locked nothing. If the rwlock is valid, this function will always block until it can lock the mutex, and return with it locked.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForWriting; RWLock.TryLockForReading; RWLock.Unlock

◆ LockForWriting()

void SDL::RWLock::LockForWriting ( )

inline

This will block until the rwlock is available, which is to say it is not locked for reading or writing by any other thread. Only one thread may hold the lock when it requests write access; all other threads, whether they also want to write or only want read-only access, must wait until the writer thread has released the lock.

It is illegal for the owning thread to lock an already-locked rwlock for writing (read-only may be locked recursively, writing can not). Doing so results in undefined behavior.

It is illegal to request a write lock from a thread that already holds a read-only lock. Doing so results in undefined behavior. Unlock the read-only lock before requesting a write lock.

This function does not fail; if rwlock is nullptr, it will return immediately having locked nothing. If the rwlock is valid, this function will always block until it can lock the mutex, and return with it locked.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForReading; RWLock.TryLockForWriting; RWLock.Unlock

◆ LockMutex()

void SDL::LockMutex ( MutexParam mutex )

inline

This will block until the mutex is available, which is to say it is in the unlocked state and the OS has chosen the caller as the next thread to lock it. Of all threads waiting to lock the mutex, only one may do so at a time.

It is legal for the owning thread to lock an already-locked mutex. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive mutex").

This function does not fail; if mutex is nullptr, it will return immediately having locked nothing. If the mutex is valid, this function will always block until it can lock the mutex, and return with it locked.

Parameters

mutex the mutex to lock.

Since: This function is available since SDL 3.2.0.

See also: Mutex.TryLock; Mutex.Unlock

◆ LockRWLockForReading()

void SDL::LockRWLockForReading ( RWLockParam rwlock )

inline

This will block until the rwlock is available, which is to say it is not locked for writing by any other thread. Of all threads waiting to lock the rwlock, all may do so at the same time as long as they are requesting read-only access; if a thread wants to lock for writing, only one may do so at a time, and no other threads, read-only or not, may hold the lock at the same time.

It is legal for the owning thread to lock an already-locked rwlock for reading. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive rwlock").

Note that locking for writing is not recursive (this is only available to read-only locks).

It is illegal to request a read-only lock from a thread that already holds the write lock. Doing so results in undefined behavior. Unlock the write lock before requesting a read-only lock. (But, of course, if you have the write lock, you don't need further locks to read in any case.)

This function does not fail; if rwlock is nullptr, it will return immediately having locked nothing. If the rwlock is valid, this function will always block until it can lock the mutex, and return with it locked.

Parameters

rwlock the read/write lock to lock.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForWriting; RWLock.TryLockForReading; RWLock.Unlock

◆ LockRWLockForWriting()

void SDL::LockRWLockForWriting ( RWLockParam rwlock )

inline

This will block until the rwlock is available, which is to say it is not locked for reading or writing by any other thread. Only one thread may hold the lock when it requests write access; all other threads, whether they also want to write or only want read-only access, must wait until the writer thread has released the lock.

It is illegal for the owning thread to lock an already-locked rwlock for writing (read-only may be locked recursively, writing can not). Doing so results in undefined behavior.

It is illegal to request a write lock from a thread that already holds a read-only lock. Doing so results in undefined behavior. Unlock the read-only lock before requesting a write lock.

This function does not fail; if rwlock is nullptr, it will return immediately having locked nothing. If the rwlock is valid, this function will always block until it can lock the mutex, and return with it locked.

Parameters

rwlock the read/write lock to lock.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForReading; RWLock.TryLockForWriting; RWLock.Unlock

◆ SetInitialized() [1/2]

void SDL::InitState::SetInitialized ( bool initialized )

inline

This function sets the status of the passed in state to INIT_STATUS_INITIALIZED or INIT_STATUS_UNINITIALIZED and allows any threads waiting for the status to proceed.

Parameters

initialized the new initialization state.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: InitState.ShouldInit; InitState.ShouldQuit

◆ SetInitialized() [2/2]

void SDL::SetInitialized	(	InitStateRaw *	state,
		bool	initialized
	)

inline

This function sets the status of the passed in state to INIT_STATUS_INITIALIZED or INIT_STATUS_UNINITIALIZED and allows any threads waiting for the status to proceed.

Parameters

state	the initialization state to check.
initialized	the new initialization state.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: InitState.ShouldInit; InitState.ShouldQuit

◆ ShouldInit() [1/2]

bool SDL::InitState::ShouldInit ( )

inline

This function checks the passed in state and if initialization should be done, sets the status to INIT_STATUS_INITIALIZING and returns true. If another thread is already modifying this state, it will wait until that's done before returning.

If this function returns true, the calling code must call InitState.SetInitialized() to complete the initialization.

Returns: true if initialization needs to be done, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: InitState.SetInitialized; InitState.ShouldQuit

◆ ShouldInit() [2/2]

bool SDL::ShouldInit ( InitStateRaw * state )

inline

This function checks the passed in state and if initialization should be done, sets the status to INIT_STATUS_INITIALIZING and returns true. If another thread is already modifying this state, it will wait until that's done before returning.

If this function returns true, the calling code must call InitState.SetInitialized() to complete the initialization.

Parameters

state the initialization state to check.

Returns: true if initialization needs to be done, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: InitState.SetInitialized; InitState.ShouldQuit

◆ ShouldQuit() [1/2]

bool SDL::InitState::ShouldQuit ( )

inline

This function checks the passed in state and if cleanup should be done, sets the status to INIT_STATUS_UNINITIALIZING and returns true.

If this function returns true, the calling code must call InitState.SetInitialized() to complete the cleanup.

Returns: true if cleanup needs to be done, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: InitState.SetInitialized; InitState.ShouldInit

◆ ShouldQuit() [2/2]

bool SDL::ShouldQuit ( InitStateRaw * state )

inline

This function checks the passed in state and if cleanup should be done, sets the status to INIT_STATUS_UNINITIALIZING and returns true.

If this function returns true, the calling code must call InitState.SetInitialized() to complete the cleanup.

Parameters

state the initialization state to check.

Returns: true if cleanup needs to be done, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: InitState.SetInitialized; InitState.ShouldInit

◆ Signal() [1/2]

void SDL::Semaphore::Signal ( )

inline

Since: This function is available since SDL 3.2.0.

See also: Semaphore.TryWait; Semaphore.Wait; Semaphore.WaitTimeout

◆ Signal() [2/2]

void SDL::Condition::Signal ( )

inline

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Condition.Broadcast; Condition.Wait; Condition.WaitTimeout

◆ SignalCondition()

void SDL::SignalCondition ( ConditionParam cond )

inline

Parameters

cond	the condition variable to signal.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Condition.Broadcast; Condition.Wait; Condition.WaitTimeout

◆ SignalSemaphore()

void SDL::SignalSemaphore ( SemaphoreParam sem )

inline

Parameters

sem	the semaphore to increment.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.TryWait; Semaphore.Wait; Semaphore.WaitTimeout

◆ TryLock()

void SDL::Mutex::TryLock ( )

inline

This works just like Mutex.Lock(), but if the mutex is not available, this function returns false immediately.

This technique is useful if you need exclusive access to a resource but don't want to wait for it, and will return to it to try again later.

This function returns true if passed a nullptr mutex.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: Mutex.Lock; Mutex.Unlock

◆ TryLockForReading()

void SDL::RWLock::TryLockForReading ( )

inline

This works just like RWLock.LockForReading(), but if the rwlock is not available, then this function returns false immediately.

This technique is useful if you need access to a resource but don't want to wait for it, and will return to it to try again later.

Trying to lock for read-only access can succeed if other threads are holding read-only locks, as this won't prevent access.

This function returns true if passed a nullptr rwlock.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForReading; RWLock.TryLockForWriting; RWLock.Unlock

◆ TryLockForWriting()

void SDL::RWLock::TryLockForWriting ( )

inline

This works just like RWLock.LockForWriting(), but if the rwlock is not available, then this function returns false immediately.

This technique is useful if you need exclusive access to a resource but don't want to wait for it, and will return to it to try again later.

It is illegal for the owning thread to lock an already-locked rwlock for writing (read-only may be locked recursively, writing can not). Doing so results in undefined behavior.

It is illegal to request a write lock from a thread that already holds a read-only lock. Doing so results in undefined behavior. Unlock the read-only lock before requesting a write lock.

This function returns true if passed a nullptr rwlock.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForWriting; RWLock.TryLockForReading; RWLock.Unlock

◆ TryLockMutex()

void SDL::TryLockMutex ( MutexParam mutex )

inline

This works just like Mutex.Lock(), but if the mutex is not available, this function returns false immediately.

This technique is useful if you need exclusive access to a resource but don't want to wait for it, and will return to it to try again later.

This function returns true if passed a nullptr mutex.

Parameters

mutex the mutex to try to lock.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: Mutex.Lock; Mutex.Unlock

◆ TryLockRWLockForReading()

void SDL::TryLockRWLockForReading ( RWLockParam rwlock )

inline

This works just like RWLock.LockForReading(), but if the rwlock is not available, then this function returns false immediately.

This technique is useful if you need access to a resource but don't want to wait for it, and will return to it to try again later.

Trying to lock for read-only access can succeed if other threads are holding read-only locks, as this won't prevent access.

This function returns true if passed a nullptr rwlock.

Parameters

rwlock the rwlock to try to lock.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForReading; RWLock.TryLockForWriting; RWLock.Unlock

◆ TryLockRWLockForWriting()

void SDL::TryLockRWLockForWriting ( RWLockParam rwlock )

inline

This works just like RWLock.LockForWriting(), but if the rwlock is not available, then this function returns false immediately.

This technique is useful if you need exclusive access to a resource but don't want to wait for it, and will return to it to try again later.

It is illegal for the owning thread to lock an already-locked rwlock for writing (read-only may be locked recursively, writing can not). Doing so results in undefined behavior.

It is illegal to request a write lock from a thread that already holds a read-only lock. Doing so results in undefined behavior. Unlock the read-only lock before requesting a write lock.

This function returns true if passed a nullptr rwlock.

Parameters

rwlock the rwlock to try to lock.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForWriting; RWLock.TryLockForReading; RWLock.Unlock

◆ TryWait()

bool SDL::Semaphore::TryWait ( )

inline

This function checks to see if the semaphore pointed to by sem has a positive value and atomically decrements the semaphore value if it does. If the semaphore doesn't have a positive value, the function immediately returns false.

Returns: true if the wait succeeds, false if the wait would block.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Signal; Semaphore.Wait; Semaphore.WaitTimeout

◆ TryWaitSemaphore()

bool SDL::TryWaitSemaphore ( SemaphoreParam sem )

inline

This function checks to see if the semaphore pointed to by sem has a positive value and atomically decrements the semaphore value if it does. If the semaphore doesn't have a positive value, the function immediately returns false.

Parameters

sem	the semaphore to wait on.

Returns: true if the wait succeeds, false if the wait would block.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Signal; Semaphore.Wait; Semaphore.WaitTimeout

◆ Unlock() [1/2]

void SDL::Mutex::Unlock ( )

inline

It is legal for the owning thread to lock an already-locked mutex. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive mutex").

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

Since: This function is available since SDL 3.2.0.

See also: Mutex.Lock; Mutex.TryLock

◆ Unlock() [2/2]

void SDL::RWLock::Unlock ( )

inline

Use this function to unlock the rwlock, whether it was locked for read-only or write operations.

It is legal for the owning thread to lock an already-locked read-only lock. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive rwlock").

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

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForReading; RWLock.LockForWriting; RWLock.TryLockForReading; RWLock.TryLockForWriting

◆ UnlockMutex()

void SDL::UnlockMutex ( MutexParam mutex )

inline

It is legal for the owning thread to lock an already-locked mutex. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive mutex").

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

Parameters

mutex the mutex to unlock.

Since: This function is available since SDL 3.2.0.

See also: Mutex.Lock; Mutex.TryLock

◆ UnlockRWLock()

void SDL::UnlockRWLock ( RWLockParam rwlock )

inline

Use this function to unlock the rwlock, whether it was locked for read-only or write operations.

It is legal for the owning thread to lock an already-locked read-only lock. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive rwlock").

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

Parameters

rwlock the rwlock to unlock.

Since: This function is available since SDL 3.2.0.

See also: RWLock.LockForReading; RWLock.LockForWriting; RWLock.TryLockForReading; RWLock.TryLockForWriting

◆ Wait() [1/2]

void SDL::Semaphore::Wait ( )

inline

This function suspends the calling thread until the semaphore pointed to by sem has a positive value, and then atomically decrement the semaphore value.

This function is the equivalent of calling Semaphore.WaitTimeout() with a time length of -1.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Signal; Semaphore.TryWait; Semaphore.WaitTimeout

◆ Wait() [2/2]

void SDL::Condition::Wait ( MutexParam mutex )

inline

This function unlocks the specified mutex and waits for another thread to call Condition.Signal() or Condition.Broadcast() on the condition variable cond. Once the condition variable is signaled, the mutex is re-locked and the function returns.

The mutex must be locked before calling this function. Locking the mutex recursively (more than once) is not supported and leads to undefined behavior.

This function is the equivalent of calling Condition.WaitTimeout() with a time length of -1.

Parameters

mutex the mutex used to coordinate thread access.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Condition.Broadcast; Condition.Signal; Condition.WaitTimeout

◆ WaitCondition()

void SDL::WaitCondition	(	ConditionParam	cond,
		MutexParam	mutex
	)

inline

This function unlocks the specified mutex and waits for another thread to call Condition.Signal() or Condition.Broadcast() on the condition variable cond. Once the condition variable is signaled, the mutex is re-locked and the function returns.

The mutex must be locked before calling this function. Locking the mutex recursively (more than once) is not supported and leads to undefined behavior.

This function is the equivalent of calling Condition.WaitTimeout() with a time length of -1.

Parameters

cond	the condition variable to wait on.
mutex	the mutex used to coordinate thread access.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Condition.Broadcast; Condition.Signal; Condition.WaitTimeout

◆ WaitConditionTimeout()

bool SDL::WaitConditionTimeout	(	ConditionParam	cond,
		MutexParam	mutex,
		std::chrono::milliseconds	timeout
	)

inline

This function unlocks the specified mutex and waits for another thread to call Condition.Signal() or Condition.Broadcast() on the condition variable cond, or for the specified time to elapse. Once the condition variable is signaled or the time elapsed, the mutex is re-locked and the function returns.

The mutex must be locked before calling this function. Locking the mutex recursively (more than once) is not supported and leads to undefined behavior.

Parameters

cond	the condition variable to wait on.
mutex	the mutex used to coordinate thread access.
timeout	the maximum time to wait, in milliseconds, or -1 to wait indefinitely.

Returns: true if the condition variable is signaled, false if the condition is not signaled in the allotted time.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Condition.Broadcast; Condition.Signal; Condition.Wait

◆ WaitSemaphore()

void SDL::WaitSemaphore ( SemaphoreParam sem )

inline

This function suspends the calling thread until the semaphore pointed to by sem has a positive value, and then atomically decrement the semaphore value.

This function is the equivalent of calling Semaphore.WaitTimeout() with a time length of -1.

Parameters

sem	the semaphore wait on.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Signal; Semaphore.TryWait; Semaphore.WaitTimeout

◆ WaitSemaphoreTimeout()

bool SDL::WaitSemaphoreTimeout	(	SemaphoreParam	sem,
		std::chrono::milliseconds	timeout
	)

inline

This function suspends the calling thread until either the semaphore pointed to by sem has a positive value or the specified time has elapsed. If the call is successful it will atomically decrement the semaphore value.

Parameters

sem	the semaphore to wait on.
timeout	the length of the timeout, in milliseconds, or -1 to wait indefinitely.

Returns: true if the wait succeeds or false if the wait times out.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Signal; Semaphore.TryWait; Semaphore.Wait

◆ WaitTimeout() [1/2]

bool SDL::Condition::WaitTimeout	(	MutexParam	mutex,
		std::chrono::milliseconds	timeout
	)

inline

This function unlocks the specified mutex and waits for another thread to call Condition.Signal() or Condition.Broadcast() on the condition variable cond, or for the specified time to elapse. Once the condition variable is signaled or the time elapsed, the mutex is re-locked and the function returns.

The mutex must be locked before calling this function. Locking the mutex recursively (more than once) is not supported and leads to undefined behavior.

Parameters

mutex	the mutex used to coordinate thread access.
timeout	the maximum time to wait, in milliseconds, or -1 to wait indefinitely.

Returns: true if the condition variable is signaled, false if the condition is not signaled in the allotted time.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Condition.Broadcast; Condition.Signal; Condition.Wait

◆ WaitTimeout() [2/2]

bool SDL::Semaphore::WaitTimeout ( std::chrono::milliseconds timeout )

inline

This function suspends the calling thread until either the semaphore pointed to by sem has a positive value or the specified time has elapsed. If the call is successful it will atomically decrement the semaphore value.

Parameters

timeout the length of the timeout, in milliseconds, or -1 to wait indefinitely.

Returns: true if the wait succeeds or false if the wait times out.

Since: This function is available since SDL 3.2.0.

See also: Semaphore.Signal; Semaphore.TryWait; Semaphore.Wait

Variable Documentation

◆ INIT_STATUS_INITIALIZED

constexpr InitStatus SDL::INIT_STATUS_INITIALIZED

constexpr

Initial value:

=

SDL_INIT_STATUS_INITIALIZED

◆ INIT_STATUS_INITIALIZING

constexpr InitStatus SDL::INIT_STATUS_INITIALIZING

constexpr

Initial value:

=

SDL_INIT_STATUS_INITIALIZING

◆ INIT_STATUS_UNINITIALIZED

constexpr InitStatus SDL::INIT_STATUS_UNINITIALIZED

constexpr

Initial value:

=

SDL_INIT_STATUS_UNINITIALIZED

◆ INIT_STATUS_UNINITIALIZING

constexpr InitStatus SDL::INIT_STATUS_UNINITIALIZING

constexpr

Initial value:

=

SDL_INIT_STATUS_UNINITIALIZING

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ InitStatus

Function Documentation

◆ Broadcast()

◆ BroadcastCondition()

◆ CreateCondition()

◆ CreateMutex()

◆ CreateRWLock()

◆ CreateSemaphore()

◆ Destroy() [1/4]

◆ Destroy() [2/4]

◆ Destroy() [3/4]

◆ Destroy() [4/4]

◆ DestroyCondition()

◆ DestroyMutex()

◆ DestroyRWLock()

◆ DestroySemaphore()

◆ GetSemaphoreValue()

◆ GetValue()

◆ Lock()

◆ LockForReading()

◆ LockForWriting()

◆ LockMutex()

◆ LockRWLockForReading()

◆ LockRWLockForWriting()

◆ SetInitialized() [1/2]

◆ SetInitialized() [2/2]

◆ ShouldInit() [1/2]

◆ ShouldInit() [2/2]

◆ ShouldQuit() [1/2]

◆ ShouldQuit() [2/2]

◆ Signal() [1/2]

◆ Signal() [2/2]

◆ SignalCondition()

◆ SignalSemaphore()

◆ TryLock()

◆ TryLockForReading()

◆ TryLockForWriting()

◆ TryLockMutex()

◆ TryLockRWLockForReading()

◆ TryLockRWLockForWriting()

◆ TryWait()

◆ TryWaitSemaphore()

◆ Unlock() [1/2]

◆ Unlock() [2/2]

◆ UnlockMutex()

◆ UnlockRWLock()

◆ Wait() [1/2]

◆ Wait() [2/2]

◆ WaitCondition()

◆ WaitConditionTimeout()

◆ WaitSemaphore()

◆ WaitSemaphoreTimeout()

◆ WaitTimeout() [1/2]

◆ WaitTimeout() [2/2]

Variable Documentation

◆ INIT_STATUS_INITIALIZED

◆ INIT_STATUS_INITIALIZING

◆ INIT_STATUS_UNINITIALIZED

◆ INIT_STATUS_UNINITIALIZING