pw::sync::BinarySemaphore Class Reference

#include <binary_semaphore.h>

Public Types
using	native_handle_type = backend::NativeBinarySemaphoreHandle

Public Member Functions
	BinarySemaphore (const BinarySemaphore &)=delete
	BinarySemaphore (BinarySemaphore &&)=delete
BinarySemaphore &	operator= (const BinarySemaphore &)=delete
BinarySemaphore &	operator= (BinarySemaphore &&)=delete
void	release ()
void	acquire ()
bool	try_acquire () noexcept
bool	try_acquire_for (chrono::SystemClock::duration timeout)
bool	try_acquire_until (chrono::SystemClock::time_point deadline)
native_handle_type	native_handle ()

Static Public Member Functions
static constexpr ptrdiff_t	max () noexcept

Detailed Description

BinarySemaphore is a specialization of CountingSemaphore with an arbitrary token limit of 1. Note that that max() is >= 1, meaning it may be released up to max() times but only acquired once for those N releases. Implementations of BinarySemaphore are typically more efficient than the default implementation of CountingSemaphore. The entire API is thread safe but only a subset is IRQ safe.

WARNING: In order to support global statically constructed BinarySemaphores, the user and/or backend MUST ensure that any initialization required in your environment is done prior to the creation and/or initialization of the native synchronization primitives (e.g. kernel initialization).

The BinarySemaphore is initialized to being empty or having no tokens.

Member Function Documentation

acquire()

void pw::sync::BinarySemaphore::acquire

(

)

Decrements the internal counter to 0 or blocks indefinitely until it can.

This is thread safe, but not IRQ safe.

max()

static constexpr ptrdiff_t pw::sync::BinarySemaphore::max ( )

inlinestaticconstexprnoexcept

Return values

backend::kBinarySemaphoreMaxValue

the internal counter's maximum possible value.

release()

void pw::sync::BinarySemaphore::release

(

)

Atomically increments the internal counter by 1. Any thread(s) waiting for the counter to be greater than 0, i.e. blocked in acquire, will subsequently be unblocked. This is thread and IRQ safe.

There exists an overflow risk if one releases more than max() times between acquires because many RTOS implementations internally increment the counter past one where it is only cleared when acquired.

PRECONDITION: 1 <= max() - counter

try_acquire()

bool pw::sync::BinarySemaphore::try_acquire ( )

noexcept

Tries to decrement by the internal counter to 0 without blocking.

Return values

true	if the internal counter was reset successfully.

This is thread and IRQ safe.

try_acquire_for()

bool pw::sync::BinarySemaphore::try_acquire_for

(

chrono::SystemClock::duration

timeout

)

Tries to decrement the internal counter to 0. Blocks until the specified timeout has elapsed or the counter was decremented to 0, whichever comes first.

Return values

true	if the internal counter was decremented successfully.

This is thread safe, but not IRQ safe.

try_acquire_until()

bool pw::sync::BinarySemaphore::try_acquire_until

(

chrono::SystemClock::time_point

deadline

)

Tries to decrement the internal counter to 0. Blocks until the specified deadline has been reached or the counter was decremented to 0, whichever comes first.

Return values

true	if the internal counter was decremented successfully.

This is thread safe, but not IRQ safe.

---

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

• pw_sync/public/pw_sync/binary_semaphore.h