SDL::SemaphoreRef Struct Reference

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

Inheritance diagram for SDL::SemaphoreRef:

Public Member Functions
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 from the underlying resource.
constexpr	Resource (const ResourceHandle< Resource< T > > auto &resource)
	Constructs from pointer like.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
Public Member Functions inherited from SDL::Resource< SDL_Semaphore * >
constexpr	Resource (SDL_Semaphore * resource={})
	Constructs from the underlying resource.
constexpr	Resource (const ResourceHandle< Resource< SDL_Semaphore * > > auto &resource)
	Constructs from pointer like.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
constexpr	operator bool () const
	True if contains a valid resource.
constexpr	operator value_type () const
	Converts back to underlying type.
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 const SDL_Semaphore *	operator-> () const
	Access to fields.
constexpr SDL_Semaphore *	operator-> ()
	Access to fields.

Static Public Member Functions
static void	reset (SDL_Semaphore *resource)
	Destroy a semaphore.

Additional Inherited Members
Public Types inherited from SDL::Resource< SDL_Semaphore * >
using	value_type = SDL_Semaphore *
	The raw resource type.

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

Member Function Documentation

GetValue()

Uint32 SDL::SemaphoreRef::GetValue ( ) const

inline

Returns

the current value of the semaphore.

Since

This function is available since SDL 3.2.0.

reset()

static void SDL::SemaphoreRef::reset ( SDL_Semaphore *  resource )

inlinestatic

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

Parameters

resource

the semaphore to destroy.

Since

This function is available since SDL 3.2.0.

See also

Semaphore.Create

Signal()

void SDL::SemaphoreRef::Signal ( )

inline

Since

This function is available since SDL 3.2.0.

See also

SemaphoreRef.TryWait

SemaphoreRef.Wait

SemaphoreRef.WaitTimeout

TryWait()

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

SemaphoreRef.Signal

SemaphoreRef.Wait

SemaphoreRef.WaitTimeout

Wait()

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

Since

This function is available since SDL 3.2.0.

See also

SemaphoreRef.Signal

SemaphoreRef.TryWait

SemaphoreRef.WaitTimeout

WaitTimeout()

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

SemaphoreRef.Signal

SemaphoreRef.TryWait

SemaphoreRef.Wait

---

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

• SDL3pp/SDL3pp_mutex.h