Mutex Service

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

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

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

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

Typedef Documentation

rte_mutex_handle_t

typedef struct rte_mutex_impl_s* rte_mutex_handle_t

Opaque handle bound to a rte_mutex_storage_t after rte_mutex_create().

Definition at line 47 of file rte_mutex.h.

Function Documentation

RTE_DECLARE_STORAGE()

RTE_DECLARE_STORAGE	(	rte_mutex_storage_t	,
		128U	)

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

rte_mutex_create()

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).

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

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM for a bad argument; RTE_STATUS_NOT_INITIALIZED if no OSAdapter is registered (rte_osadapter_mutex_register()); RTE_STATUS_NOT_SUPPORTED if the registered OSAdapter does not implement create; RTE_STATUS_INVALID_STATE if the application's setup phase is already locked (ADR-026) - a mutex is a setup-only resource, same posture as rte_timer_create()/rte_task_create(); RTE_STATUS_INTERNAL_ERROR if the OSAdapter cannot create a priority-inheritance mutex (OSA rule R2) - the refusal is reported as DEGRADED / RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE and there is no fallback to a plain mutex. REQ-OAL-MUTEX-010

Definition at line 44 of file rte_mutex.c.

rte_mutex_lock()

rte_status_t rte_mutex_lock

(

rte_mutex_handle_t

handle

)

Blocks the calling task until it holds the mutex.

Parameters

handle

Mutex to lock. Must not be NULL.

Returns

RTE_STATUS_OK, RTE_STATUS_INVALID_PARAM, RTE_STATUS_NOT_INITIALIZED, RTE_STATUS_NOT_SUPPORTED (see rte_mutex_create()), or RTE_STATUS_INTERNAL_ERROR if the OSAdapter itself reports a failure (e.g. a detected deadlock). REQ-OAL-MUTEX-011

Definition at line 74 of file rte_mutex.c.

rte_mutex_lock_timed()

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).

Not gated by the setup-phase lock: an operational call, like rte_mutex_lock(). On RTE_STATUS_OK the calling task holds the mutex and must release it with rte_mutex_unlock(); on any other status it does not hold it.

Parameters

handle	Mutex to lock. Must not be NULL.
timeout_ms	Maximum time to wait for the mutex, in milliseconds. 0 is one non-blocking try (same rule as rte_ipc_send()/rte_ipc_receive()).

Returns

RTE_STATUS_OK with the lock held; RTE_STATUS_TIMEOUT if the lock was not acquired within timeout_ms (lock not held); RTE_STATUS_INVALID_PARAM for a NULL handle; RTE_STATUS_NOT_INITIALIZED if no OSAdapter is registered; RTE_STATUS_NOT_SUPPORTED if the registered OSAdapter does not implement lock_timed; RTE_STATUS_INTERNAL_ERROR for any other OSAdapter failure. REQ-OAL-MUTEX-014

Definition at line 91 of file rte_mutex.c.

rte_mutex_unlock()

rte_status_t rte_mutex_unlock

(

rte_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 rte_mutex_lock(). REQ-OAL-MUTEX-012

Definition at line 111 of file rte_mutex.c.

rte_mutex_destroy()

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.

Parameters

handle

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

Returns

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

Definition at line 128 of file rte_mutex.c.