ove::Mutex Class Reference

RAII wrapper around an oveRTOS non-recursive mutex. More...

#include <sync.hpp>

Public Member Functions
	Mutex ()
	Constructs and initialises the mutex.
	~Mutex () noexcept
	Destroys the mutex, releasing the underlying kernel resource.
	Mutex (const Mutex &)=delete
Mutex &	operator= (const Mutex &)=delete
	Mutex (Mutex &&other) noexcept
	Move constructor — transfers ownership of the kernel handle.
Mutex &	operator= (Mutex &&other) noexcept
	Move-assignment operator — transfers ownership of the kernel handle.
void	lock ()
	Acquires the mutex, blocking indefinitely. std::mutex::lock analog.
bool	try_lock ()
	Attempts to acquire the mutex without blocking. Satisfies the Lockable named requirement (alongside lock / unlock).
template<class Rep , class Period >
Result< void >	try_lock_for (const std::chrono::duration< Rep, Period > &rel) noexcept
	Attempts to acquire the mutex within rel.
template<class Clock , class Duration >
Result< void >	try_lock_until (const std::chrono::time_point< Clock, Duration > &deadline) noexcept
	Attempts to acquire the mutex by deadline.
void	unlock ()
	Releases the mutex.
bool	valid () const
	Returns true if the underlying kernel handle is non-null.
ove_mutex_t	handle () const
	Returns the raw oveRTOS mutex handle.

Detailed Description

RAII wrapper around an oveRTOS non-recursive mutex.

Constructs the underlying kernel mutex object on creation and destroys it on destruction. With CONFIG_OVE_ZERO_HEAP the mutex storage is held inline in the wrapper; move operations are therefore disabled in that configuration because the kernel may hold a pointer to the internal buffer.

Note

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

lock() is marked [[nodiscard]]; ignoring its return value risks deadlock.

Constructor & Destructor Documentation

Mutex() [1/2]

ove::Mutex::Mutex ( )

inline

Constructs and initialises the mutex.

Calls ove_mutex_init (zero-heap) or ove_mutex_create (heap). Asserts at startup if initialisation fails.

~Mutex()

ove::Mutex::~Mutex ( )

inlinenoexcept

Destroys the mutex, releasing the underlying kernel resource.

If the handle is null (e.g., after a move), the destructor is a no-op.

Mutex() [2/2]

ove::Mutex::Mutex ( Mutex &&  other )

inlinenoexcept

Move constructor — transfers ownership of the kernel handle.

Parameters

other

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

Member Function Documentation

operator=()

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

inlinenoexcept

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

Parameters

other

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

Returns

Reference to this object.

lock()

void ove::Mutex::lock ( )

inline

Acquires the mutex, blocking indefinitely. std::mutex::lock analog.

Failure of an indefinite lock means the handle is unusable (moved-from, stale, or subsystem mid-deinit) — programming error, not a recoverable runtime condition. Aborts via OVE_STATIC_INIT_ASSERT on non-OK return; mirrors how Thread / Queue constructors handle similar failures.

Pairs with try_lock to satisfy the Lockable named requirement, enabling std::lock_guard<ove::Mutex> and std::scoped_lock(m1, m2) composition. Does not satisfy TimedLockable — try_lock_for and try_lock_until return Result<void> not bool, so std::unique_lock<> 's timeout overloads won't compile. Use those methods directly and switch on the Result instead.

try_lock()

bool ove::Mutex::try_lock ( )

inline

Attempts to acquire the mutex without blocking. Satisfies the Lockable named requirement (alongside lock / unlock).

Returns

true on acquisition, false if the mutex is held by another thread.

try_lock_for()

template<class Rep , class Period >

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

inlinenoexcept

Attempts to acquire the mutex within rel.

Templated over std::chrono::duration so any unit composes (100ms, 1s, 2us …). Does not satisfy the TimedLockable named requirement — that requires a bool return; this returns Result<void> so timeout (Error::Timeout) and substrate errors are reported distinctly. Consequence: std::unique_lock<ove::Mutex>::try_lock_for won't compile — use this method directly and switch on the Result instead.

Parameters

[in]

rel

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

Returns

Empty Result<void> on acquisition; unexpected Error::Timeout if the deadline elapsed without the lock being acquired; unexpected with another Error value on backend failure.

try_lock_until()

template<class Clock , class Duration >

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

inlinenoexcept

Attempts to acquire the mutex by deadline.

Templated over the clock so callers can pass std::chrono::steady_clock::now() + 100ms or ove::steady_clock::now() + 100ms interchangeably (the deadline is converted to a relative duration internally; the clock's epoch does not need to match ove::steady_clock).

Returns

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

unlock()

void ove::Mutex::unlock ( )

inline

Releases the mutex.

Must be called from the same thread context that acquired the lock.

valid()

bool ove::Mutex::valid ( ) const

inline

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

Returns

true when the mutex was successfully initialised.

handle()

ove_mutex_t ove::Mutex::handle ( ) const

inline

Returns the raw oveRTOS mutex handle.

Returns

The opaque ove_mutex_t handle.

---

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

• bindings/cpp/ove/sync.hpp