File syn_mutex.h¶

FileList > sched > syn_mutex.h

Priority-inheriting mutual exclusion primitive for tasks and protothreads. More...

#include "../common/syn_defs.h"
#include "../pt/syn_pt.h"
#include "syn_task.h"
#include <stdbool.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_Mutex Priority-inheriting recursive mutex structure.

Public Functions¶

Type	Name
SYN_Task *	syn_mutex_get_owner (const SYN_Mutex * mutex) Get the current owner of the mutex.
SYN_Status	syn_mutex_init (SYN_Mutex * mutex) Initialize a mutex in unlocked state.
bool	syn_mutex_is_locked (const SYN_Mutex * mutex) Check if the mutex is currently locked.
SYN_Status	syn_mutex_try_lock (SYN_Mutex * mutex, SYN_Task * task) Attempt to acquire the mutex without blocking.
SYN_Status	syn_mutex_unlock (SYN_Mutex * mutex, SYN_Task * task) Release a previously acquired mutex.

Macros¶

Type	Name
define	PT_MUTEX_INIT (mutex) `[syn\_mutex\_init](syn__mutex_8c.md#function-syn_mutex_init)(mutex)` Initialize a mutex.
define	PT_MUTEX_LOCK (pt, task, mutex) `[PT\_WAIT\_UNTIL](syn__pt_8h.md#define-pt_wait_until)(pt, [syn\_mutex\_try\_lock](syn__mutex_8c.md#function-syn_mutex_try_lock)((mutex), (task)) == SYN\_OK)` Block the protothread until the mutex is acquired.
define	PT_MUTEX_TRYLOCK (mutex, task) `([syn\_mutex\_try\_lock](syn__mutex_8c.md#function-syn_mutex_try_lock)((mutex), (task)) == SYN\_OK)` Non-blocking try-lock macro for protothreads.
define	PT_MUTEX_UNLOCK (mutex, task) `[syn\_mutex\_unlock](syn__mutex_8c.md#function-syn_mutex_unlock)((mutex), (task))` Unlock a mutex held by the task.

Detailed Description¶

Provides recursive mutual exclusion with priority inheritance to prevent unbounded priority inversion. If a higher-priority task attempts to acquire a mutex held by a lower-priority task, the owner's priority is temporarily boosted to match the waiting task until the mutex is released.

Public Functions Documentation¶

function syn_mutex_get_owner¶

Get the current owner of the mutex.

SYN_Task * syn_mutex_get_owner (
    const SYN_Mutex * mutex
)

Parameters:

mutex Pointer to mutex structure.

Returns:

Pointer to owner task, or NULL if unlocked.

function syn_mutex_init¶

Initialize a mutex in unlocked state.

SYN_Status syn_mutex_init (
    SYN_Mutex * mutex
)

Parameters:

mutex Pointer to mutex structure.

Returns:

SYN_OK on success, or SYN_INVALID_PARAM if mutex is NULL.

function syn_mutex_is_locked¶

Check if the mutex is currently locked.

bool syn_mutex_is_locked (
    const SYN_Mutex * mutex
)

Parameters:

mutex Pointer to mutex structure.

Returns:

true if locked, false otherwise.

function syn_mutex_try_lock¶

Attempt to acquire the mutex without blocking.

SYN_Status syn_mutex_try_lock (
    SYN_Mutex * mutex,
    SYN_Task * task
)

If the mutex is already locked by another task and task has higher priority (numerically lower value) than the owner, the owner's priority is automatically boosted.

Parameters:

mutex Pointer to mutex structure.
task Pointer to acquiring task (optional, NULL for standalone lock).

Returns:

SYN_OK if acquired, SYN_BUSY if held by another task, or SYN_INVALID_PARAM.

function syn_mutex_unlock¶

Release a previously acquired mutex.

SYN_Status syn_mutex_unlock (
    SYN_Mutex * mutex,
    SYN_Task * task
)

Decrements the recursion count. When the count reaches zero, the owner's priority is restored to its base priority and ownership is cleared.

Parameters:

mutex Pointer to mutex structure.
task Pointer to owner task releasing the lock.

Returns:

SYN_OK on success, SYN_ERROR if not locked or wrong owner, or SYN_INVALID_PARAM.

Macro Definition Documentation¶

define PT_MUTEX_INIT¶

Initialize a mutex.

#define PT_MUTEX_INIT (
    mutex
) `syn_mutex_init (mutex)`

define PT_MUTEX_LOCK¶

Block the protothread until the mutex is acquired.

#define PT_MUTEX_LOCK (
    pt,
    task,
    mutex
) `PT_WAIT_UNTIL (pt, syn_mutex_try_lock ((mutex), (task)) == SYN_OK )`

Cooperatively waits via PT_WAIT_UNTIL. On contention, automatically boosts the holding task's priority to prevent unbounded priority inversion.

Parameters:

pt Protothread control block.
task Pointer to calling SYN_Task.
mutex Pointer to SYN_Mutex.

define PT_MUTEX_TRYLOCK¶

Non-blocking try-lock macro for protothreads.

#define PT_MUTEX_TRYLOCK (
    mutex,
    task
) `( syn_mutex_try_lock ((mutex), (task)) == SYN_OK )`

Parameters:

mutex Pointer to SYN_Mutex.
task Pointer to calling SYN_Task.

Returns:

true if acquired, false if busy.

define PT_MUTEX_UNLOCK¶

Unlock a mutex held by the task.

#define PT_MUTEX_UNLOCK (
    mutex,
    task
) `syn_mutex_unlock ((mutex), (task))`

Parameters:

mutex Pointer to SYN_Mutex.
task Pointer to calling SYN_Task.

The documentation for this class was generated from the following file src/syntropic/sched/syn_mutex.h