Mutex Service

Non-recursive blocking mutual exclusion (ADR-033). More...

Files
file	src/oal/mutex/sapi_mutex.c
	Mutex service: validates parameters, then dispatches to the backend registered via sapi_mutex_register_backend() (ADR-033).

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

Non-recursive blocking mutual exclusion (ADR-033).

Typedef Documentation

sapi_mutex_handle_t

typedef struct sapi_mutex_impl_s* sapi_mutex_handle_t

Opaque handle bound to a sapi_mutex_storage_t after sapi_mutex_create().

Definition at line 44 of file sapi_mutex.h.

Function Documentation

SAFEAPI_DECLARE_STORAGE()

SAFEAPI_DECLARE_STORAGE	(	sapi_mutex_storage_t	,
		128U	)

Opaque caller-owned storage for one mutex instance. Size is part of the ABI.

sapi_mutex_create()

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.

Parameters

storage	Caller-owned storage the mutex's state is placed into. Must not be NULL and must outlive the mutex.
out_handle	Receives the created mutex's handle. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_NOT_INITIALIZED if no backend is registered (sapi_mutex_register_backend()); SAPI_STATUS_NOT_SUPPORTED if the registered backend does not implement create; SAPI_STATUS_INVALID_STATE if the application's setup phase is already locked (ADR-026) - a mutex is a setup-only resource, same posture as sapi_timer_create()/sapi_task_create(). REQ-OAL-MUTEX-010

Definition at line 44 of file sapi_mutex.c.

sapi_mutex_lock()

sapi_status_t sapi_mutex_lock

(

sapi_mutex_handle_t

handle

)

Blocks the calling task until it holds the mutex.

Parameters

handle

Mutex to lock. Must not be NULL.

Returns

SAPI_STATUS_OK, SAPI_STATUS_INVALID_PARAM, SAPI_STATUS_NOT_INITIALIZED, SAPI_STATUS_NOT_SUPPORTED (see sapi_mutex_create()), or SAPI_STATUS_INTERNAL_ERROR if the backend itself reports a failure (e.g. a detected deadlock). REQ-OAL-MUTEX-011

Definition at line 74 of file sapi_mutex.c.

sapi_mutex_unlock()

sapi_status_t sapi_mutex_unlock

(

sapi_mutex_handle_t

handle

)

Releases a mutex previously locked by the calling task.

Parameters

handle

Mutex to unlock. Must not be NULL. Unlocking a mutex the calling task does not hold is undefined behavior (same as pthread_mutex_unlock()).

Returns

See sapi_mutex_lock(). REQ-OAL-MUTEX-012

Definition at line 91 of file sapi_mutex.c.

sapi_mutex_destroy()

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.

Parameters

handle

Mutex to destroy. Must not be NULL. Invalid to use after this call.

Returns

See sapi_mutex_lock(). REQ-OAL-MUTEX-013

Definition at line 108 of file sapi_mutex.c.