CMSIS-RTOS RTX  Version 4.51
CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Mutex Management

Synchronize thread execution with a Mutex. More...

Macros

#define osMutexDef(name)
 Define a Mutex.
 
#define osMutex(name)   &os_mutex_def_##name
 Access a Mutex definition.
 

Functions

osMutexId osMutexCreate (const osMutexDef_t *mutex_def)
 Create and Initialize a Mutex object.
 
osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec)
 Wait until a Mutex becomes available.
 
osStatus osMutexRelease (osMutexId mutex_id)
 Release a Mutex that was obtained by osMutexWait.
 
osStatus osMutexDelete (osMutexId mutex_id)
 Delete a Mutex that was created by osMutexCreate.
 

Description

The Mutex Management function group is used to synchronize the execution of threads. This is for example used to protect access to a shared resource, for example a shared memory image.

Note
Mutex Management functions cannot be called from interrupt service routines (ISR).
Mutex.png
CMSIS-RTOS Mutex

Macro Definition Documentation

#define osMutex (   name)    &os_mutex_def_##name

Access to mutex object for the functions osMutexCreate.

Parameters
namename of the mutex object.
Note
CAN BE CHANGED: The parameter to osMutex shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.
#define osMutexDef (   name)

Define a mutex object that is referenced by osMutex.

Parameters
namename of the mutex object.
Note
CAN BE CHANGED: The parameter to osMutexDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

Function Documentation

osMutexId osMutexCreate ( const osMutexDef_t mutex_def)
Parameters
[in]mutex_defmutex definition referenced with osMutex.
Returns
mutex ID for reference by other functions or NULL in case of error.
Note
MUST REMAIN UNCHANGED: osMutexCreate shall be consistent in every CMSIS-RTOS.

Create and initialize a Mutex object.

osStatus osMutexDelete ( osMutexId  mutex_id)
Parameters
[in]mutex_idmutex ID obtained by osMutexCreate.
Returns
status code that indicates the execution status of the function.
Note
MUST REMAIN UNCHANGED: osMutexDelete shall be consistent in every CMSIS-RTOS.

Delete a Mutex object. The function releases internal memory obtained for Mutex handling. After this call the mutex_id is no longer valid and cannot be used. The Mutex may be created again using the function osMutexCreate.

Status and Error Codes

  • osOK: the mutex object has been deleted.
  • osErrorISR: osMutexDelete cannot be called from interrupt service routines.
  • osErrorResource: all tokens have already been released.
  • osErrorParameter: the parameter semaphore_id is incorrect.
osStatus osMutexRelease ( osMutexId  mutex_id)
Parameters
[in]mutex_idmutex ID obtained by osMutexCreate.
Returns
status code that indicates the execution status of the function.
Note
MUST REMAIN UNCHANGED: osMutexRelease shall be consistent in every CMSIS-RTOS.

Release a Mutex that was obtained with osMutexWait. Other threads that currently wait for the same mutex will be now put into the state READY.

Status and Error Codes

  • osOK: the mutex has been correctly released.
  • osErrorResource: the mutex was not obtained before.
  • osErrorParameter: the parameter mutex_id is incorrect.
  • osErrorISR: osMutexRelease cannot be called from interrupt service routines.

/**

osStatus osMutexWait ( osMutexId  mutex_id,
uint32_t  millisec 
)
Parameters
[in]mutex_idmutex ID obtained by osMutexCreate.
[in]millisectimeout value or 0 in case of no time-out.
Returns
status code that indicates the execution status of the function.
Note
MUST REMAIN UNCHANGED: osMutexWait shall be consistent in every CMSIS-RTOS.

Wait until a Mutex becomes available. If no other thread has obtained the Mutex, the function instantly returns and blocks the mutex object.

Status and Error Codes

  • osOK: the mutex has been obtain.
  • osErrorTimeoutResource: the mutex could not be obtained in the given time.
  • osErrorResource: the mutex could not be obtained when no timeout was specified.
  • osErrorParameter: the parameter mutex_id is incorrect.
  • osErrorISR: osMutexWait cannot be called from interrupt service routines.