PlatformMutex.h File Reference

Cross-platform mutex and synchronization primitives with pluggable backend. More...

#include <atomic>
#include <cstdint>

Include dependency graph for PlatformMutex.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	NullMutexBackend
	No-op mutex backend – all operations compile to nothing. More...
class	PlatformTime
class	PlatformMutexImpl< Backend >
	Recursive mutex templated on a backend policy. More...
class	PlatformSharedMutexImpl< Backend >
	Reader-writer mutex using two regular mutexes + atomic counters. More...
class	PlatformUniqueLock< Mutex >
	RAII exclusive lock guard for any mutex with lock()/try_lock_for()/unlock(). More...
class	PlatformSharedLock< SharedMutex >
	RAII shared (reader) lock guard for any shared mutex. More...

Typedefs
using	PlatformMutexActiveBackend = NullMutexBackend
	Default: all mutex operations compile to nothing.
using	PlatformMutex = PlatformMutexImpl< PlatformMutexActiveBackend >
	Concrete recursive mutex using the active backend.
using	PlatformSharedMutex = PlatformSharedMutexImpl< PlatformMutexActiveBackend >
	Concrete reader-writer mutex using the active backend.
using	PlatformMutexLockGuard = PlatformUniqueLock< PlatformMutex >
	RAII exclusive lock guard for PlatformMutex.
template<typename Mutex >
using	PlatformLockGuard = PlatformUniqueLock< Mutex >
	Generic RAII lock guard alias.

Detailed Description

Cross-platform mutex and synchronization primitives with pluggable backend.

This header is FULLY SELF-CONTAINED within hf-internal-interface-wrap. It has NO external dependencies beyond C++ standard headers (<atomic>, <cstdint>).

=== BACKEND ARCHITECTURE ===

All mutex operations delegate to a compile-time Backend policy class. By default, the backend is NullMutexBackend – all operations are constexpr inline no-ops that the optimizer eliminates completely (zero code generated).

At the core/ layer (where hf-internal-interface-wrap and hf-utils-rtos-wrap are brought together), a "PlatformMutexBackend.h" configuration header may be placed on the include path. This header defines a concrete backend struct that delegates to the RTOS abstraction layer (OsAbstraction.h) for real mutex protection under FreeRTOS or another RTOS.

=== ZERO-OVERHEAD PRINCIPLE ===

When no backend config is found (standalone interface-wrap builds, host builds, MCU=NONE, RTOS=NONE), NullMutexBackend is used:

• Every mutex operation is constexpr and compiles to nothing
• Handle types are uint8_t (1 byte member instead of pointer)
• No RTOS headers are included, no external dependencies exist

=== CUSTOMIZATION (for core/ layer or other consumers) ===

Create "PlatformMutexBackend.h" on the include path and:

1. Define a backend struct satisfying the same contract as NullMutexBackend
2. typedef: using PlatformMutexActiveBackend = YourBackendType;
3. #define PLATFORM_MUTEX_BACKEND_CONFIGURED

Author

Nebiyu Tadesse

Date

2025

Copyright

HardFOC

Typedef Documentation

PlatformLockGuard

template<typename Mutex >

using PlatformLockGuard = PlatformUniqueLock<Mutex>

Generic RAII lock guard alias.

PlatformMutex

using PlatformMutex = PlatformMutexImpl<PlatformMutexActiveBackend>

Concrete recursive mutex using the active backend.

PlatformMutexActiveBackend

using PlatformMutexActiveBackend = NullMutexBackend

Default: all mutex operations compile to nothing.

PlatformMutexLockGuard

using PlatformMutexLockGuard = PlatformUniqueLock<PlatformMutex>

RAII exclusive lock guard for PlatformMutex.

PlatformSharedMutex

using PlatformSharedMutex = PlatformSharedMutexImpl<PlatformMutexActiveBackend>

Concrete reader-writer mutex using the active backend.