mutex.h

Defines

EMB_MUTEX_INHERIT
EMB_MUTEX_CEILING
EMB_MUTEX_NONE
EMB_MUTEX_RECURSIVE

Typedefs

typedef union emb_mutex_storage emb_mutex_storage_t
typedef struct emb_mutex_attr emb_mutex_attr_t

Functions

void emb_mutex_attr_default(emb_mutex_attr_t *out_attr)

emb_mutex_attr_default()

- Fill mutex attributes with defaults.

Context: thread isr prekernel Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_MUTEX Requirements: API-020 Since: 0.2 Stability: yes

When CONFIG_EMB_MUTEX_INHERIT is off, select an available protocol before initialization; the default INHERIT initialization returns EMB_ENOTSUP.

Parameters:

  • out_attr – Receives name NULL, INHERIT protocol, ceiling 0 and flags 0; NULL is a no-op.

emb_status_t emb_mutex_init(emb_mutex_storage_t *storage, const emb_mutex_attr_t *attr, emb_mutex_t *out_mutex)

emb_mutex_init()

- Construct a mutex in caller-provided storage.

Context: prekernel thread Blocking: no Timing: O(1) Ownership: borrows:storage Configuration: CONFIG_EMB_MUTEX Requirements: API-020 API-021 KRN-OBJ-003 KRN-SYNC-003 KRN-SYNC-012 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EINVAL for bad storage/output, protocol or ceiling; EMB_ENOTSUP for INHERIT when CONFIG_EMB_MUTEX_INHERIT is off.

Parameters:

  • storage – Aligned caller-owned storage; retain it until successful destruction.

  • attr – Attributes copied during initialization; NULL selects defaults. Keep name storage alive.

  • out_mutex – Required output handle; cleared before argument validation.

emb_status_t emb_mutex_destroy(emb_mutex_t mutex)

emb_mutex_destroy()

- End the mutex (KRN-OBJ-001, SPEC-005 §3.7).

Context: thread Blocking: no Timing: O(waiters + owned + PI work), plus profile-specific timeout removals Ownership: gives:storage Configuration: CONFIG_EMB_MUTEX Requirements: KRN-OBJ-001 KRN-OBJ-010 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EBUSY when owned by another thread or with waiters and no ABORT_WAITERS (misuse).

Parameters:

  • mutex – Initialized mutex; no other owner and no live waiters unless ABORT_WAITERS is set.

emb_status_t emb_mutex_lock(emb_mutex_t mutex, emb_timeout_t timeout)

emb_mutex_lock() - Acquire the mutex, waiting up to timeout

.

Context: thread Blocking: timeout Timing: O(owned) acquisition; O(waiters + PI work + timeouts) finite contended wait Ownership: none Configuration: CONFIG_EMB_MUTEX Requirements: KRN-SYNC-003 KRN-SYNC-009 KRN-SYNC-020 KRN-SYNC-023 KRN-SYNC-024 KRN-SYNC-025 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_ETIMEDOUT; EMB_ECANCELED; EMB_EDESTROYED; EMB_EOWNERDEAD (the caller owns the mutex); EMB_EDEADLK (it does not); EMB_EOVERFLOW (recursion count at 255); EMB_EPERM; EMB_EINVAL.

Parameters:

  • mutex – Initialized mutex to acquire.

  • timeout – EMB_NO_WAIT, EMB_WAIT_FOREVER or EMB_TIMEOUT(duration).

emb_status_t emb_mutex_lock_until(emb_mutex_t mutex, emb_instant_t deadline)

emb_mutex_lock_until()

- Acquire with an absolute deadline.

Context: thread Blocking: timeout Timing: O(owned) acquisition; enqueue/PI/timeout costs as

emb_mutex_lock() Ownership: none Configuration: CONFIG_EMB_MUTEX Requirements: API-024 KRN-TIM-011 KRN-SYNC-020 Since: 0.2 Stability: yes

Return: the same statuses and ownership rules as emb_mutex_lock(). EMB_TICK_MAX is the current internal forever sentinel; use a finite deadline for bounded waits. In 32-bit configurations, keep deadlines within the signed half-range window (SPEC-003 §5.2).

Parameters:

  • mutex – Initialized mutex to acquire.

  • deadline – Kernel-clock deadline; a past deadline attempts acquisition without waiting.

emb_status_t emb_mutex_unlock(emb_mutex_t mutex)

emb_mutex_unlock()

- Release the mutex; hand it to the first waiter if any.

Context: thread Blocking: no Timing: O(owned + PI work), plus waiter hand-off and profile-specific timeout removal Ownership: none Configuration: CONFIG_EMB_MUTEX Requirements: KRN-SYNC-008 KRN-SYNC-010 KRN-SYNC-021 KRN-WAIT-012 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EPERM when the caller is not the owner (misuse).

Parameters:

  • mutex – Initialized mutex owned by the calling thread.

bool emb_mutex_is_owner(emb_mutex_t mutex)

emb_mutex_is_owner() - Does the calling thread own mutex

?

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_MUTEX Requirements: KRN-SYNC-002 Since: 0.2 Stability: yes

Parameters:

  • mutex – Initialized mutex to query; false for an invalid handle or ISR caller.

emb_status_t emb_mutex_mark_consistent(emb_mutex_t mutex)

emb_mutex_mark_consistent()

- Clear the inconsistent mark after EMB_EOWNERDEAD (SPEC-005 §3.6).

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_MUTEX Requirements: KRN-SYNC-025 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EPERM when the caller is not the owner.

Parameters:

  • mutex – Mutex owned by the caller after repairing state following EMB_EOWNERDEAD.

struct emb_mutex_t
#include <mutex.h>

Public Members

uintptr_t raw
struct emb_mutex_attr
#include <mutex.h>

Public Members

const char *name
uint8_t protocol
uint8_t ceiling
uint8_t flags
uint8_t reserved_