Coldwave Documentation

Appearance

Mutex ​

Mutex functions.

A Mutex is a program object that allows multiple program threads to share the same resource, but not simultaneously. When a program is using a particular resource, that program locks the mutex from other programs' access, doing this signifies that the mutex is currently being used. When it's done, it will unlock the mutex and other programs that were barred can now access the resource.

Coldwave eOS provides several functions for Mutex management, such as osMutexNew (to create and initialize a Mutex object), osMutexAcquire (to acquire a Mutex and lock it), osMutexRelease (to release and unlock a Mutex), and osMutexDelete (to delete a Mutex object).

Example usage ​

cpp
osMutexId_t mid_Mutex;
void sampleMutexUsage (void) {
mid_Mutex = osMutexNew(NULL);  // create and initialize Mutex object
if (osMutexAcquire(mid_Mutex, osWaitForever) == osOK) {  // acquire a mutex, wait forever
 // critical section
 osMutexRelease(mid_Mutex);  // release the mutex
  }

  osMutexDelete(mid_Mutex);  // delete the mutex object
}

Types ​

Name
structosMutexAttr_t
Attributes structure for mutex.

Functions Overview ​

Name
osMutexId_tosMutexNew(const osMutexAttr_t * attr)
Create and Initialize a Mutex object.
const char *osMutexGetName(osMutexId_t mutex_id)
Get name of a Mutex object.
osStatus_tosMutexAcquire(osMutexId_t mutex_id, uint32_t timeout)
Acquire a Mutex or timeout if it is locked.
osStatus_tosMutexRelease(osMutexId_t mutex_id)
Release a Mutex that was acquired by osMutexAcquire.
osThreadId_tosMutexGetOwner(osMutexId_t mutex_id)
Get Thread which owns a Mutex object.
osStatus_tosMutexDelete(osMutexId_t mutex_id)
Delete a Mutex object.

Defines ​

Name
osMutexRecursiveRecursive mutex.
osMutexPrioInheritPriority inherit protocol.
osMutexRobustRobust mutex.

Function Details ​

function osMutexNew ​

cpp
osMutexId_t osMutexNew(
    const osMutexAttr_t * attr
)

Create and Initialize a Mutex object.

Parameters:

  • attr mutex attributes; NULL: default values.

Return: mutex ID for reference by other functions or NULL in case of error.

function osMutexGetName ​

cpp
const char * osMutexGetName(
    osMutexId_t mutex_id
)

Get name of a Mutex object.

Parameters:

Return: name as null-terminated string.

function osMutexAcquire ​

cpp
osStatus_t osMutexAcquire(
    osMutexId_t mutex_id,
    uint32_t timeout
)

Acquire a Mutex or timeout if it is locked.

Parameters:

  • mutex_id mutex ID obtained by osMutexNew.
  • timeout CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.

Return: status code that indicates the execution status of the function.

function osMutexRelease ​

cpp
osStatus_t osMutexRelease(
    osMutexId_t mutex_id
)

Release a Mutex that was acquired by osMutexAcquire.

Parameters:

Return: status code that indicates the execution status of the function.

function osMutexGetOwner ​

cpp
osThreadId_t osMutexGetOwner(
    osMutexId_t mutex_id
)

Get Thread which owns a Mutex object.

Parameters:

Return: thread ID of owner thread or NULL when mutex was not acquired.

function osMutexDelete ​

cpp
osStatus_t osMutexDelete(
    osMutexId_t mutex_id
)

Delete a Mutex object.

Parameters:

Return: status code that indicates the execution status of the function.

Macros Documentation ​

define osMutexRecursive ​

cpp
#define osMutexRecursive 0x00000001U

Recursive mutex.

define osMutexPrioInherit ​

cpp
#define osMutexPrioInherit 0x00000002U

Priority inherit protocol.

define osMutexRobust ​

cpp
#define osMutexRobust 0x00000008U

Robust mutex.