Chapter 2. API Reference
Return If the mutex was successfully created then a handle to the created mutex is returned. If pxMutexBuffer
was NULL then NULL is returned.
Parameters
• pxMutexBuffer: Must point to a variable of type StaticSemaphore_t, which will be used to hold
the mutex’s data structure, removing the need for the memory to be allocated dynamically.
xSemaphoreCreateRecursiveMutex()
Creates a new recursive mutex type semaphore instance, and returns a handle by which the new recursive mutex
can be referenced.
Internally, within the FreeRTOS implementation, recursive mutexs use a block of memory, in which the mu-
tex structure is stored. If a recursive mutex is created using xSemaphoreCreateRecursiveMutex() then the
required memory is automatically dynamically allocated inside the xSemaphoreCreateRecursiveMutex() func-
tion. (see http://www.freertos.org/a00111.html). If a recursive mutex is created using xSemaphoreCreateRe-
cursiveMutexStatic() then the application writer must provide the memory that will get used by the mutex.
xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to be created without using any
dynamic memory allocation.
Mutexes created using this macro can be accessed using the xSemaphoreTakeRecursive() and xSemaphore-
GiveRecursive() macros. The xSemaphoreTake() and xSemaphoreGive() macros must not be used.
A mutex used recursively can be ‘taken’repeatedly by the owner. The mutex doesn’t become available
again until the owner has called xSemaphoreGiveRecursive() for each successful‘take’request. For example,
if a task successfully ‘takes’the same mutex 5 times then the mutex will not be available to any other task
until it has also ‘given’the mutex back exactly five times.
This type of semaphore uses a priority inheritance mechanism so a task‘taking’a semaphore MUST ALWAYS
‘give’the semaphore back once the semaphore it is no longer required.
Mutex type semaphores cannot be used from within interrupt service routines.
See vSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation
(where one task or interrupt always ‘gives’the semaphore and another always ‘takes’the semaphore) and
from within interrupt service routines.
Example usage:
SemaphoreHandle_t xSemaphore;
void vATask( void * pvParameters )
{
// Semaphore cannot be used before a call to xSemaphoreCreateMutex().
// This is a macro so pass the variable in directly.
xSemaphore = xSemaphoreCreateRecursiveMutex();
if( xSemaphore != NULL )
{
// The semaphore was created successfully.
// The semaphore can now be used.
}
}
Return xSemaphore Handle to the created mutex semaphore. Should be of type SemaphoreHandle_t.
xSemaphoreCreateRecursiveMutexStatic(pxStaticSemaphore)
Creates a new recursive mutex type semaphore instance, and returns a handle by which the new recursive mutex
can be referenced.
Internally, within the FreeRTOS implementation, recursive mutexs use a block of memory, in which the mu-
tex structure is stored. If a recursive mutex is created using xSemaphoreCreateRecursiveMutex() then the
required memory is automatically dynamically allocated inside the xSemaphoreCreateRecursiveMutex() func-
tion. (see https://www.FreeRTOS.org/a00111.html). If a recursive mutex is created using xSemaphoreCre-
ateRecursiveMutexStatic() then the application writer must provide the memory that will get used by the mutex.
Espressif Systems 910
Submit Document Feedback
Release v4.4
To Next Page
Loading...