sapi_mutex.h File Reference

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

#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"

Include dependency graph for sapi_mutex.h:

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

Go to the source code of this file.

Typedefs
typedef struct sapi_mutex_impl_s *	sapi_mutex_handle_t

Functions
	SAFEAPI_DECLARE_STORAGE (sapi_mutex_storage_t, 128U)
sapi_status_t	sapi_mutex_create (sapi_mutex_storage_t *storage, sapi_mutex_handle_t *out_handle)
	Creates (and initializes, unlocked) a mutex bound to caller-owned storage.
sapi_status_t	sapi_mutex_lock (sapi_mutex_handle_t handle)
	Blocks the calling task until it holds the mutex.
sapi_status_t	sapi_mutex_unlock (sapi_mutex_handle_t handle)
	Releases a mutex previously locked by the calling task.
sapi_status_t	sapi_mutex_destroy (sapi_mutex_handle_t handle)
	Destroys a mutex, releasing any backend 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 sapi_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 backend is meant to be swappable without touching application code). Added specifically to close that gap: found live in safeAPIRBC2oo2, which had been using pthread_mutex_t directly (see this ADR's own "Context" section, docs/architecture/ADR-033-sapi-mutex.md).

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 backend this framework ships today) - a caller needing recursive locking must track that itself.

Definition in file sapi_mutex.h.