ove::Semaphore Class Reference

RAII wrapper around an oveRTOS counting semaphore. More...

#include <sync.hpp>

Public Member Functions
	Semaphore (unsigned int initial=0, unsigned int max=1)
	Constructs and initialises the semaphore.
	~Semaphore () noexcept
	Destroys the semaphore, releasing the underlying kernel resource.
	Semaphore (const Semaphore &)=delete
Semaphore &	operator= (const Semaphore &)=delete
	Semaphore (Semaphore &&other) noexcept
	Move constructor — transfers ownership of the kernel handle.
Semaphore &	operator= (Semaphore &&other) noexcept
	Move-assignment operator — transfers ownership of the kernel handle.
void	acquire ()
	Decrements the semaphore count, blocking indefinitely.
bool	try_acquire ()
	Non-blocking acquisition attempt. std::counting_semaphore::try_acquire analog.
template<class Rep , class Period >
Result< void >	try_acquire_for (const std::chrono::duration< Rep, Period > &rel) noexcept
	Bounded-wait acquisition.
template<class Clock , class Duration >
Result< void >	try_acquire_until (const std::chrono::time_point< Clock, Duration > &deadline) noexcept
	Deadline-based acquisition templated over the clock.
void	release ()
	Increments the semaphore count, unblocking a waiting task if any.
bool	valid () const
	Returns true if the underlying kernel handle is non-null.
ove_sem_t	handle () const
	Returns the raw oveRTOS semaphore handle.

Detailed Description

RAII wrapper around an oveRTOS counting semaphore.

A counting semaphore with a configurable initial count and maximum count. Commonly used as a binary semaphore (initial = 0, max = 1) for signalling between tasks or from an ISR.

With CONFIG_OVE_ZERO_HEAP the semaphore storage is held inline and move operations are disabled.

Note

Not copyable. Move-only when heap allocation is enabled.

take() is marked [[nodiscard]]; the return value indicates whether the semaphore was actually decremented.

Constructor & Destructor Documentation

Semaphore() [1/2]

ove::Semaphore::Semaphore ( unsigned int  initial = 0, unsigned int  max = 1  )

inlineexplicit

Constructs and initialises the semaphore.

Parameters

[in]	initial	Initial count value (default: 0).
[in]	max	Maximum count value (default: 1, binary semaphore).

Asserts at startup if initialisation fails.

Semaphore() [2/2]

ove::Semaphore::Semaphore ( Semaphore &&  other )

inlinenoexcept

Move constructor — transfers ownership of the kernel handle.

Parameters

other

The source; its handle is set to null after the move.

Member Function Documentation

operator=()

Semaphore & ove::Semaphore::operator= ( Semaphore &&  other )

inlinenoexcept

Move-assignment operator — transfers ownership of the kernel handle.

Parameters

other

The source; its handle is set to null after the move.

Returns

Reference to this object.

acquire()

void ove::Semaphore::acquire ( )

inline

Decrements the semaphore count, blocking indefinitely.

std::counting_semaphore::acquire analog. Failure of an indefinite wait means the handle is unusable — programming error. Aborts via OVE_STATIC_INIT_ASSERT on non-OK return (same shape as Mutex::lock).

try_acquire()

bool ove::Semaphore::try_acquire ( )

inline

Non-blocking acquisition attempt. std::counting_semaphore::try_acquire analog.

Returns

true on acquisition, false if the count was zero.

try_acquire_for()

template<class Rep , class Period >

Result< void > ove::Semaphore::try_acquire_for ( const std::chrono::duration< Rep, Period > &  rel )

inlinenoexcept

Bounded-wait acquisition.

Loosely analogous to std::counting_semaphore::try_acquire_for but with a Result<void> return instead of bool — timeout and backend errors are reported distinctly via Error. This means std::counting_semaphore's interface is not strictly satisfied; the standard has no concept for it, so the mismatch shows up only if you try to substitute the type into a generic template that expects the standard shape.

Parameters

[in]

rel

Relative timeout (any std::chrono::duration unit).

Returns

Empty Result<void> on acquisition; unexpected Error::Timeout if the count was zero at the deadline; unexpected with another Error value on backend failure.

try_acquire_until()

template<class Clock , class Duration >

Result< void > ove::Semaphore::try_acquire_until ( const std::chrono::time_point< Clock, Duration > &  deadline )

inlinenoexcept

Deadline-based acquisition templated over the clock.

Same clock-templating rationale as Mutex::try_lock_until (deadline converted to a relative duration internally; clock's epoch need not match ove::steady_clock).

Returns

As try_acquire_for — Result<void> with Error::Timeout on timeout.

release()

void ove::Semaphore::release ( )

inline

Increments the semaphore count, unblocking a waiting task if any.

std::counting_semaphore::release analog. Safe to call from both task and ISR context. Increments by 1; batched form release(unsigned n) is not yet available pending substrate ove_sem_give_n (tracked in c-substrate-findings.md).

valid()

bool ove::Semaphore::valid ( ) const

inline

Returns true if the underlying kernel handle is non-null.

Returns

true when the semaphore was successfully initialised.

handle()

ove_sem_t ove::Semaphore::handle ( ) const

inline

Returns the raw oveRTOS semaphore handle.

Returns

The opaque ove_sem_t handle.

---

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

• bindings/cpp/ove/sync.hpp