SDL::ConditionBase Struct Reference

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

Inheritance diagram for SDL::ConditionBase:

Public Member Functions
	ConditionBase ()
	Create a condition variable.
void	Signal ()
	Restart one of the threads that are waiting on the condition variable.
void	Broadcast ()
	Restart all threads that are waiting on the condition variable.
void	Wait (MutexBase &mutex)
	Wait until a condition variable is signaled.
bool	WaitTimeout (MutexBase &mutex, std::chrono::milliseconds timeout)
	Wait until a condition variable is signaled or a certain time has passed.
constexpr	Resource (T resource={})
	Constructs the underlying resource.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
	Resource (const Resource &other)=delete
	Resource (Resource &&other)=delete
Public Member Functions inherited from SDL::Resource< SDL_Condition * >
constexpr	Resource (SDL_Condition * resource={})
	Constructs the underlying resource.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
	Resource (const Resource &other)=delete
	Resource (Resource &&other)=delete
Resource &	operator= (const Resource &other)=delete
Resource &	operator= (Resource &&other)=delete
constexpr	operator bool () const
	True if contains a valid resource.
constexpr bool	operator== (const Resource &other) const=default
	Comparison.
constexpr bool	operator== (std::nullopt_t) const
	Comparison.
constexpr bool	operator== (std::nullptr_t) const
	Comparison.
constexpr SDL_Condition *	get () const
	Return contained resource;.
constexpr SDL_Condition *	release (SDL_Condition * newResource={})
	Return contained resource and empties or replace value.
constexpr const SDL_Condition *	operator-> () const
	Access to fields.
constexpr SDL_Condition *	operator-> ()
	Access to fields.

Detailed Description

Condition variables, paired with an MutexBase, 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

Since

This struct is available since SDL 3.2.0.

Category:

Resource

See also

Condition

ConditionRef

Constructor & Destructor Documentation

ConditionBase()

SDL::ConditionBase::ConditionBase ( )

inline

Postcondition

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

ConditionBase.Broadcast

ConditionBase.Signal

ConditionBase.Wait

ConditionBase.WaitTimeout

Member Function Documentation

Broadcast()

void SDL::ConditionBase::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

ConditionBase.Signal

ConditionBase.Wait

ConditionBase.WaitTimeout

Signal()

void SDL::ConditionBase::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

ConditionBase.Broadcast

ConditionBase.Wait

ConditionBase.WaitTimeout

Wait()

void SDL::ConditionBase::Wait ( MutexBase &  mutex )

inline

This function unlocks the specified mutex and waits for another thread to call ConditionBase.Signal() or ConditionBase.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 ConditionBase.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

ConditionBase.Broadcast

ConditionBase.Signal

ConditionBase.WaitTimeout

WaitTimeout()

bool SDL::ConditionBase::WaitTimeout ( MutexBase &  mutex, std::chrono::milliseconds  timeout  )

inline

This function unlocks the specified mutex and waits for another thread to call ConditionBase.Signal() or ConditionBase.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

ConditionBase.Broadcast

ConditionBase.Signal

ConditionBase.Wait

---

The documentation for this struct was generated from the following file:

• SDL3pp/SDL3pp_mutex.h