File mutex.h

Mutex for resource ownership on a single coroutine.

This does not have an ISR API, as mutexes are not to be used within an ISR context (they are purely a coroutine primitive).

Typedefs

typedef struct mutex Mutex

Enums

enum res_codes_mutex

Values:

enumerator RES_MUTEX_NOT_OWNER

enumerator RES_MUTEX_OCCUPIED

Functions

Mutex *mutex_create_static(Mutex *mutex)

Initialise a statically allocated mutex.

Parameters:

mutex – Mutex to initialise.

Returns:

Pointer to the mutex.

Mutex *mutex_create(void)

Dynamically create and initialise a mutex.

Returns:

Pointer to a mutex, or NULL if it cannot be created.

void mutex_free(Mutex *mutex)

Free a previously created dynamic mutex.

Warning

Freeing a mutex not created by mutex_create is causes undefined behaviour.

Parameters:

mutex – Mutex to free.

Result mutex_acquire(Mutex *mutex, PlatformTick timeout)

Acquires a resource exclusively for this coroutine.

Note

Repeated calls from the same coroutine are allowed.

Parameters:

• mutex – Mutex to acquire.

• timeout – Maximum time to wait before giving up.

Return values:

• RES_OK – Mutex was acquired.

• RES_TIMEOUT – Timeout occurred.

Result mutex_acquire_no_wait(Mutex *mutex)

Acquires a resource exclusively for this coroutine without waiting.

Note

Repeated calls from the same coroutine are allowed.

Parameters:

mutex – Mutex to acquire.

Return values:

• RES_OK – Mutex was acquired.

• RES_MUTEX_OCCUPIED – Mutex is currently occupied by another coroutine.

Result mutex_release(Mutex *mutex)

Releases the mutex.

Note

This call is idempotent.

Parameters:

mutex – Mutex to release.

Return values:

• RES_OK – Mutex was released.

• RES_MUTEX_NOT_OWNER –

struct mutex

Public Members

Coro *owner