SDL::SemaphoreBase Struct Reference

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

Inheritance diagram for SDL::SemaphoreBase:

Public Member Functions
	SemaphoreBase (Uint32 initial_value)
	Create a semaphore.
void	Wait ()
	Wait until a semaphore has a positive value and then decrements it.
bool	TryWait ()
	See if a semaphore has a positive value and decrement it if it does.
bool	WaitTimeout (std::chrono::milliseconds timeout)
	Wait until a semaphore has a positive value and then decrements it.
void	Signal ()
	Atomically increment a semaphore's value and wake waiting threads.
Uint32	GetValue () const
	Get the current value of a semaphore.
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_Semaphore * >
constexpr	Resource (SDL_Semaphore * 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_Semaphore *	get () const
	Return contained resource;.
constexpr SDL_Semaphore *	release (SDL_Semaphore * newResource={})
	Return contained resource and empties or replace value.
constexpr const SDL_Semaphore *	operator-> () const
	Access to fields.
constexpr SDL_Semaphore *	operator-> ()
	Access to fields.

Detailed Description

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)

Since

This struct is available since SDL 3.2.0.

Category:

Resource

See also

Semaphore

SemaphoreRef

Constructor & Destructor Documentation

SemaphoreBase()

SDL::SemaphoreBase::SemaphoreBase ( 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.

Postcondition

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

Since

This function is available since SDL 3.2.0.

See also

SemaphoreBase.Signal

SemaphoreBase.TryWait

SemaphoreBase.GetValue

SemaphoreBase.Wait

SemaphoreBase.WaitTimeout

Member Function Documentation

GetValue()

Uint32 SDL::SemaphoreBase::GetValue ( ) const

inline

Returns

the current value of the semaphore.

Since

This function is available since SDL 3.2.0.

Signal()

void SDL::SemaphoreBase::Signal ( )

inline

Since

This function is available since SDL 3.2.0.

See also

SemaphoreBase.TryWait

SemaphoreBase.Wait

SemaphoreBase.WaitTimeout

TryWait()

bool SDL::SemaphoreBase::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

SemaphoreBase.Signal

SemaphoreBase.Wait

SemaphoreBase.WaitTimeout

Wait()

void SDL::SemaphoreBase::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 SemaphoreBase.WaitTimeout() with a time length of -1.

Since

This function is available since SDL 3.2.0.

See also

SemaphoreBase.Signal

SemaphoreBase.TryWait

SemaphoreBase.WaitTimeout

WaitTimeout()

bool SDL::SemaphoreBase::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

SemaphoreBase.Signal

SemaphoreBase.TryWait

SemaphoreBase.Wait

---

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

• SDL3pp/SDL3pp_mutex.h