#include <counting_semaphore.h>

Public Types
using	native_handle_type = backend::NativeCountingSemaphoreHandle

Public Member Functions
	CountingSemaphore (const CountingSemaphore &)=delete

	CountingSemaphore (CountingSemaphore &&)=delete

CountingSemaphore &	operator= (const CountingSemaphore &)=delete

CountingSemaphore &	operator= (CountingSemaphore &&)=delete

void	release (ptrdiff_t update=1)

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
	Returns the internal counter's maximum possible value.

Detailed Description

The CountingSemaphore is a synchronization primitive that can be used for counting events and/or resource management where receiver(s) can block on acquire until notifier(s) signal by invoking release. Note that unlike Mutexes, priority inheritance is not used by semaphores meaning semaphores are subject to unbounded priority inversions. Pigweed does not recommend semaphores for mutual exclusion. The entire API is thread safe but only a subset is IRQ safe.

embed:rst:leading-asterisk
 
*  .. WARNING::
*     In order to support global statically constructed ``CountingSemaphores``
*     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 CountingSemaphore is initialized to being empty or having no tokens.

Member Function Documentation

◆ acquire()

void pw::sync::CountingSemaphore::acquire ( )

Decrements the internal counter by 1 or blocks indefinitely until it can.

This is thread safe, but not IRQ safe.

◆ release()

void pw::sync::CountingSemaphore::release ( ptrdiff_t update = 1 )

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

Precondition: update >= 0

Precondition: update <= max() - counter

◆ try_acquire()

bool pw::sync::CountingSemaphore::try_acquire ( )

noexcept

Tries to decrement by the internal counter by 1 without blocking. Returns true if the internal counter was decremented successfully.

This is IRQ safe.

◆ try_acquire_for()

bool pw::sync::CountingSemaphore::try_acquire_for ( chrono::SystemClock::duration timeout )

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

Returns true if the internal counter was decremented successfully. This is thread safe, but not IRQ safe.

◆ try_acquire_until()

bool pw::sync::CountingSemaphore::try_acquire_until ( chrono::SystemClock::time_point deadline )

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

Returns 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/counting_semaphore.h

Public Types

Public Member Functions