Chapter 2. API Reference
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 xSemaphoreCreateBinary() 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;
StaticSemaphore_t xMutexBuffer;
void vATask( void * pvParameters )
{
// A recursive semaphore cannot be used before it is created. Here a
// recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic().
// The address of xMutexBuffer is passed into the function, and will hold
// the mutexes data structures - so no dynamic memory allocation will be
// attempted.
xSemaphore = xSemaphoreCreateRecursiveMutexStatic( &xMutexBuffer );
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL,
// so there is no need to check it.
}
Return If the recursive mutex was successfully created then a handle to the created recursive mutex is returned.
If pxMutexBuffer was NULL then NULL is returned.
Parameters
• pxStaticSemaphore: Must point to a variable of type StaticSemaphore_t, which will then be
used to hold the recursive mutex’s data structure, removing the need for the memory to be allocated
dynamically.
xSemaphoreCreateCounting(uxMaxCount, uxInitialCount)
Creates a new counting semaphore instance, and returns a handle by which the new counting semaphore can
be referenced.
In many usage scenarios it is faster and more memory efficient to use a direct to task notification in place of a
counting semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html
Internally, within the FreeRTOS implementation, counting semaphores use a block of memory, in which
the counting semaphore structure is stored. If a counting semaphore is created using xSemaphoreCreate-
Counting() then the required memory is automatically dynamically allocated inside the xSemaphoreCreate-
Counting() function. (see https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created us-
ing xSemaphoreCreateCountingStatic() then the application writer can instead optionally provide the memory
that will get used by the counting semaphore. xSemaphoreCreateCountingStatic() therefore allows a counting
semaphore to be created without using any dynamic memory allocation.
Counting semaphores are typically used for two things:
1) Counting events.
In this usage scenario an event handler will ‘give’a semaphore each time an event occurs (incrementing
the semaphore count value), and a handler task will ‘take’a semaphore each time it processes an event
Espressif Systems 911
Submit Document Feedback
Release v4.4
To Next Page
Loading...