rte_mutex.h File Reference

OS Abstraction Layer - Mutual exclusion service. More...

#include "rte/utils/status/rte_status.h"
#include "rte/utils/types/rte_types.h"

Include dependency graph for rte_mutex.h:

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

Go to the source code of this file.

Typedefs
typedef struct rte_mutex_impl_s *	rte_mutex_handle_t

Functions
	RTE_DECLARE_STORAGE (rte_mutex_storage_t, 128U)
rte_status_t	rte_mutex_create (rte_mutex_storage_t *storage, rte_mutex_handle_t *out_handle)
	Creates (and initializes, unlocked) a priority-inheritance mutex bound to caller-owned storage (REQ-OAL-MUTEX-004).
rte_status_t	rte_mutex_lock (rte_mutex_handle_t handle)
	Blocks the calling task until it holds the mutex.
rte_status_t	rte_mutex_lock_timed (rte_mutex_handle_t handle, rte_duration_ms_t timeout_ms)
	Waits at most timeout_ms for the mutex (OSA rule R2: every wait bounded).
rte_status_t	rte_mutex_unlock (rte_mutex_handle_t handle)
	Releases a mutex previously locked by the calling task.
rte_status_t	rte_mutex_destroy (rte_mutex_handle_t handle)
	Destroys a mutex, releasing any OSAdapter resources bound to it. Must not be called while any task holds or is waiting on the lock.

Detailed Description

OS Abstraction Layer - Mutual exclusion service.

A portable, non-recursive blocking mutex for guarding a shared resource accessed from more than one rte_task (e.g. a single netlink handle sent on by both the application's own cyclic executive and a background rx task's own reconnect/echo path). REQ-OAL-MUTEX-001 (ADR-033): an application shall never call a platform threading primitive (pthread_*, a raw RTOS semaphore API, etc.) directly to guard its own state - doing so ties that application code to one specific OS/RTOS, defeating the whole point of building on this framework's OAL in the first place (a OSAdapter is meant to be swappable without touching application code). Added specifically to close that gap: found live in RBC_GP, which had been using pthread_mutex_t directly (see this ADR's own "Context" section, docs/architecture/ADR-033-sapi-mutex.dox).

REQ-OAL-MUTEX-002: no dynamic allocation; caller supplies storage. REQ-OAL-MUTEX-003: non-recursive - locking twice from the same task without an intervening unlock is undefined behavior (matches pthread's own PTHREAD_MUTEX_DEFAULT/_NORMAL semantics on Linux/macOS, the only OSAdapter this framework ships today) - a caller needing recursive locking must track that itself. REQ-OAL-MUTEX-004: every mutex uses priority inheritance (OSA rule R2); an OSAdapter that cannot provide it fails the create and never falls back to a plain mutex.

Definition in file rte_mutex.h.