Return values updated.

[cmsis] / CMSIS / DoxyGen / RTOS2 / src / cmsis_os2_Mutex.txt

// 
// close group struct osMutexAttr_t
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
//  ==== Mutex Management ====
/** 
\addtogroup CMSIS_RTOS_MutexMgmt Mutex Management
\ingroup CMSIS_RTOS
\brief Synchronize resource access using Mutual Exclusion (Mutex).
\details 
<b>Mutual exclusion</b> (widely known as \b Mutex) is used in various operating systems for resource management. Many
resources in a microcontroller device can be used repeatedly, but only by one thread at a time (for example communication
channels, memory, and files). Mutexes are used to protect access to a shared resource. A mutex is created and then passed
between the threads (they can acquire and release the mutex).

\image html "Mutex.png" "CMSIS-RTOS Mutex"

A mutex is a special version of a \ref CMSIS_RTOS_SemaphoreMgmt "semaphore". Like the semaphore, it is a container for
tokens. But instead of being able to have multiple tokens, a mutex can only carry one (representing the resource). Thus, a
mutex token is binary and bounded, i.e. it is either \em available, or \em blocked by a owning thread. The advantage of a
mutex is that it introduces thread ownership. When a thread acquires a mutex and becomes its owner, subsequent mutex acquires
from that thread will succeed immediately without any latency (if \ref osMutexRecursive is specified). Thus, mutex acquires/releases
can be nested.

\image html "mutex_states.png" "CMSIS-RTOS Mutex States"

\note Mutex management functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" (ISR), unlike a
binary semaphore that can be released from an ISR.
\note Refer to \ref mutexConfig for RTX5 configuration options.  
  
@{
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\def osMutexRecursive
\details
Recursive flag in osMutexAttr_t.

The same thread can consume a mutex multiple times without locking itself.
Each time the owning thread acquires the mutex the lock count is incremented. The mutex must
be released multiple times as well until the lock count reaches zero. At reaching zero the
mutex is actually released and can be acquired by other threads.

\note The maximum amount of recursive locks possible is implementation specific, i.e. the type size used for the lock count.
If the maximum amount of recursive locks is depleted mutex acquire might fail.

<b>Code Example</b>
\code
#include "cmsis_os2.h"
  
osMutexId_t mutex_id;  
  
const osMutexAttr_t Thread_Mutex_attr = {
  "myThreadMutex",     // human readable mutex name
  osMutexRecursive,    // attr_bits
  NULL,                // memory for control block   
  0U                   // size for control block
};
  
// must be called from a thread context
void UseMutexRecursively(int count)  {
  osStatus_t result = osMutexAcquire(mutex_id, osWaitForever);  // lock count is incremented, might fail when lock count is depleted
  if (result == osOK) {
    if (count < 10) {
      UseMutexRecursively(count + 1);
    }
    osMutexRelease(mutex_id); // lock count is decremented, actually releases the mutex on lock count zero
  }
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\def osMutexPrioInherit
\details
Priority inheritance flag in osMutexAttr_t.

A mutex using priority inheritance protocol transfers a waiting threads priority to the
current mutex owner if the owners thread priority is lower. This assures that a low priority
thread does not block a high priority thread.

Otherwise a low priority thread might hold a mutex but is not granted execution time due to
another mid priority thread. Without priority inheritance the high priority thread waiting
for the mutex would be blocked by the mid priority thread, called priority inversion.

<b>Code Example</b>

This example reveals a blocked high priority thread if osMutexPrioInherit is removed.

\code
#include "cmsis_os2.h"
  
osMutexId_t mutex_id;  
  
const osMutexAttr_t Thread_Mutex_attr = {
  "myThreadMutex",     // human readable mutex name
  osMutexPrioInherit,  // attr_bits
  NULL,                // memory for control block   
  0U                   // size for control block
};
  
void HighPrioThread(void *argument) {
  osDelay(1000); // wait 1s until start actual work
  while(1) {
    osMutexAcquire(mutex_id, osWaitForever); // try to acquire mutex
    // do stuff
    osMutexRelease(mutex_id);
  }
}
  
void MidPrioThread(void *argument) {
  osDelay(1000); // wait 1s until start actual work
  while(1) {
    // do non blocking stuff
  }
}
  
void LowPrioThread(void *argument) {
  while(1) {
    osMutexAcquire(mutex_id, osWaitForever);
    osDelay(5000); // block mutex for 5s
    osMutexRelease(mutex_id);
    osDelay(5000); // sleep for 5s
  }
}
\endcode

During the first second the high and mid priority threads are delayed. Thus the low priority
thread can start its work, acquires the mutex and delays while holding it.

After the first second the high and mid priority threads become ready. Thus the high priority
thread gets precedence and tries to acquire the mutex. Because the mutex is already owned by
the low priority thread the high priority thread gets blocked.

Finally the mid priority thread gets executed and start doing a lot of non-blocking stuff,
i.e. it does not call any blocking RTOS functionality.

Without osMutexPrioInherit we would stuck here forever. Even if the low priority thread
gets ready after 5s. Due to its low priority the mid priority thread always gets precedence.
The effect called priority inversion leads to the mid priority thread blocking the high
priority thread indirectly.

Using osMutexPrioInherit as shown in the example code we get rid of this situation. Due
to the priority inheritance protocol the low priority thread inherites the high priority
while holding the mutex. Thus the low priority thread gets precedence over the mid priority
thread until it release the mutex. On osMutexRelease the high priority thread get ready and
is scheduled immediately.

*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\def osMutexRobust
\details
Robust flag in osMutexAttr_t.

Robust mutexes are automatically released if the owning thread is terminated (either by
osThreadExit or osThreadTerminate). Non-robust mutexes are not released and the user must
assure mutex release manually.

<b>Code Example</b>

This example reveals a blocked mutex if osMutexRobust is removed.

\code
#include "cmsis_os2.h"
  
osMutexId_t mutex_id;  
  
const osMutexAttr_t Thread_Mutex_attr = {
  "myThreadMutex",     // human readable mutex name
  osMutexRobust,       // attr_bits
  NULL,                // memory for control block   
  0U                   // size for control block
};
  
void Thread(void *argument) {
  osMutexAcquire(mutex_id, osWaitForever);
  osThreadExit();
}
\endcode

Due to osMutexRobust the mutex gets released automatically. A non-robust mutex would stay locked and cannot be released anymore.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\typedef osMutexId_t
\details
Returned by:
- \ref osMutexNew
*/ 

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\struct osMutexAttr_t
\details
Attributes to configure a mutex.

Refer to \ref CMSIS_RTOS_MemoryMgmt for details about usage of
 - osMutexAttr_t::cb_mem
 - osMutexAttr_t::cb_size
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osMutexId_t osMutexNew (const osMutexAttr_t *attr)
\details
The function \b osMutexNew creates and initializes a new mutex object and returns the pointer to the mutex object identifier
or \token{NULL} in case of an error. It can be safely called before the RTOS is
started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).

The parameter \a attr sets the mutex object attributes (refer to \ref osMutexAttr_t). Default attributes will be used if set
to \token{NULL}.
/*
New definition
*/
Possible return values:
- pointer to the mutex object identifier, in case of success
- \em 'NULL', if the control block memory (\em attr->cb_mem) is not \em NULL and the memory is not 4 byte aligned 
- \em 'NULL', if the control block memory (\em attr->cb_mem) is not \em NULL but the size (\em attr->cb_size) is not big enough to store a \em mutex object control block
- \em 'NULL', if the control block memory (\em attr->cb_mem) is \em NULL but the size (\em attr->cb_size) is not 0
- \em NULL, if in IRQ mode
- \em NULL, if IRQ is masked.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
#include "cmsis_os2.h"
  
osMutexId_t mutex_id;  
  
const osMutexAttr_t Thread_Mutex_attr = {
  "myThreadMutex",                          // human readable mutex name
  osMutexRecursive | osMutexPrioInherit,    // attr_bits
  NULL,                                     // memory for control block   
  0U                                        // size for control block
  };
  
void CreateMutex (void)  {
  mutex_id = osMutexNew(&Thread_Mutex_attr);
  if (mutex_id != NULL)  {
    // Mutex object created
  }   
}
\endcode
*/

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn const char *osMutexGetName (osMutexId_t mutex_id)
\details
The function \b osMutexGetName returns the pointer to the name string of the mutex identified by parameter \a mutex_id or
\token{NULL} in case of an error.

Possible return values:
- pointer to the name string of the mutex, in case of success
- \em NULL, if a mutex specified by \a mutex_id does not exist 
- \em NULL, if the mutex specified by \a mutex_id is \em NULL
- \em NULL, if the state of the mutex is \em 'osRtxObjectInactive'
- \em NULL, if IRQ is masked
- \em NULL, if in IRQ mode.



\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout)
\details
The blocking function \b osMutexAcquire waits until a mutex object specified by parameter \a mutex_id becomes available. If
no other thread has obtained the mutex, the function instantly returns and blocks the mutex object. 

The parameter \a timeout specifies how long the system waits to acquire the mutex. While the system waits, the thread that is
calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter \ref CMSIS_RTOS_TimeOutValue "timeout"
can have the following values:
 - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the mutex becomes available (i.e. wait semantics).
 - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).

Possible \ref osStatus_t return values:
 - \em 'osOK', if the mutex specified by \a mutex_id has been obtained
 - \em 'osErrorTimeOut', if the mutex is locked by another thread and \em timeout > 0
 - \em 'osErrorResource', if the mutex is locked by another thread and \em timeout == 0
 - \em 'osErrorParameter', if the mutex is equal to \em NULL
 - \em 'osErrorResource' if the maximum number of mutex locks has been reached (\em mutex->lock is greater than \em 'osRtxMutexLockLimit') 
 - \em 'osErrorParameter', if the mutex specified by \a mutex_id does not exist
 - \em 'osErrorResource', if the mutex is in state \em 'osRtxObjectInactive'
 - \em 'osErrorISR', if IRQ is masked
 - \em 'osErrorISR', in IRQ mode.


\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
#include "cmsis_os2.h"
  
void WaitMutex (void)  {
osMutexId_t mutex_id;   
osStatus_t  status;
 
  mutex_id = osMutexNew(NULL);
  if (mutex_id != NULL)  {
    status  = osMutexAcquire(mutex_id, 0);
    if (status != osOK)  {
      // handle failure code
    }
  }
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osMutexRelease (osMutexId_t mutex_id)
\details
The function \b osMutexRelease releases a mutex specified by parameter \a mutex_id. Other threads that currently wait for
this mutex will be put into the \ref ThreadStates "READY" state.

Possible \ref osStatus_t return values:
 - \em 'osOK', if the mutex specified by \em mutex_id has been correctly released
 - \em 'osErrorResource' if the mutex specified by \em mutex_id is in state \em 'osRtxObjectInactive'
 - \em 'osErrorResource' if the running thread does not own the mutex specified by \em mutex_id
 - \em 'osErrorParameter' if a mutex specified by \a mutex_id does not exist
 - \em 'osErrorParameter' if the mutex specified by \em mutex_id is \em NULL
 - \em 'osErrorResource', if the mutex specified by \em mutex_id is not locked
 - \em 'osErrorISR', if IRQ is masked
 - \em 'osErrorISR', if in IRQ mode. 


\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
#include "cmsis_os2.h"
  
osMutexId_t mutex_id;                                        // Mutex id populated by the function osMutexNew()
 
void ReleaseMutex (osMutexId_t mutex_id)  {
  osStatus_t status;
  
  if (mutex_id != NULL)  {
    status = osMutexRelease(mutex_id);
    if (status != osOK)  {
      // handle failure code
    }
  }
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osThreadId_t osMutexGetOwner (osMutexId_t mutex_id)
\details
The function \b osMutexGetOwner returns the thread ID of the thread that acquired a mutex specified by parameter \a
mutex_id. In case of an error or if the mutex is not blocked by any thread, it returns \token{NULL}.

Possible \ref osThreadId_t return values:
- the thread ID of the thread that acquired the mutex specified by \a mutex_id
- \em NULL, if the mutex specified by \em mutex_id is not blocked
- \em NULL, if a mutex specified by \a mutex_id does not exist
- \em NULL, if the mutex is \em NULL
- \em NULL, if the state of of the mutex specified by \em mutex_id is \em 'osRtxObjectInactive'
- \em NULL, if IRQ is masked
- \em NULL, if in IRQ mode.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osMutexDelete (osMutexId_t mutex_id)
\details
The function \b osMutexDelete deletes a mutex object specified by parameter \a mutex_id. It releases internal memory obtained
for mutex handling. After this call, the \a mutex_id is no longer valid and cannot be used. The mutex may be created again
using the function \ref osMutexNew.

Possible \ref osStatus_t return values:
- \em 'osOK', if the mutex specified by \a mutex_id mutex_id has been deleted
- \em 'osErrorParameter', if a mutex specified by \a mutex_id mutex_id does not exist
- \em 'osErrrorResource', if the state of the mutex specified by \a mutex_id mutex_id is \em 'osRtxObjectInactive'
- \em 'osErrorISR', if IRQ is masked
- \em 'osErrorISR', in IRQ mode.


\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
#include "cmsis_os2.h"
  
osMutexId_t mutex_id;                            // Mutex id populated by the function osMutexNew()
 
void DeleteMutex (osMutexId_t mutex_id)  {
  osStatus_t status;
  
  if (mutex_id != NULL)  {
    status = osMutexDelete(mutex_id);
    if (status != osOK)  {
      // handle failure code
    }
  }
}
\endcode
*/
/// @}

// these struct members must stay outside the group to avoid double entries in documentation
/**
\var osMutexAttr_t::attr_bits
\details
The following predefined bit masks can be assigned to set options for a mutex object.  

| Bit Mask                    |  Description        |
| :-------------------------- | :------------------ |
| \ref osMutexRecursive       | Mutex is recursive. |
| \ref osMutexPrioInherit     | Priority inheritance protocol. |
| \ref osMutexRobust          | Robust mutex.       |

*/
/**
\var osMutexAttr_t::cb_mem
\details
Pointer to a memory location for the mutex control block object. This can optionally be used for custom memory management systems.\n
Default: \token{NULL} (uses kernel memory management).
*/
/**
\var osMutexAttr_t::cb_size
\details
The size of the memory block passed with \ref cb_mem. Must be the size of a mutex control block object or larger.
*/
/**
\var osMutexAttr_t::name
\details
Pointer to a string with a human readable name of the event object.\n
Default: \token{NULL}.
*/