Chapter 2. API Reference
In this usage scenario the count value indicates the number of resources available. To obtain control of a
resource a task must first obtain a semaphore - decrementing the semaphore count value. When the count value
reaches zero there are no free resources. When a task finishes with the resource it‘gives’the semaphore back
- incrementing the semaphore count value. In this case it is desirable for the initial count value to be equal to
the maximum count value, indicating that all resources are free.
Example usage:
SemaphoreHandle_t xSemaphore;
StaticSemaphore_t xSemaphoreBuffer;
void vATask( void * pvParameters )
{
SemaphoreHandle_t xSemaphore = NULL;
// Counting semaphore cannot be used before they have been created. Create
// a counting semaphore using xSemaphoreCreateCountingStatic(). The max
// value to which the semaphore can count is 10, and the initial value
// assigned to the count will be 0. The address of xSemaphoreBuffer is
// passed in and will be used to hold the semaphore structure, so no dynamic
// memory allocation will be used.
xSemaphore = xSemaphoreCreateCounting( 10, 0, &xSemaphoreBuffer );
// No memory allocation was attempted so xSemaphore cannot be NULL, so there
// is no need to check its value.
}
Return If the counting semaphore was successfully created then a handle to the created counting semaphore
is returned. If pxSemaphoreBuffer was NULL then NULL is returned.
Parameters
• uxMaxCount: The maximum count value that can be reached. When the semaphore reaches this
value it can no longer be ‘given’.
• uxInitialCount: The count value assigned to the semaphore when it is created.
• pxSemaphoreBuffer: Must point to a variable of type StaticSemaphore_t, which will then be
used to hold the semaphore’s data structure, removing the need for the memory to be allocated
dynamically.
vSemaphoreDelete(xSemaphore)
Delete a semaphore. This function must be used with care. For example, do not delete a mutex type semaphore
if the mutex is held by a task.
Parameters
• xSemaphore: A handle to the semaphore to be deleted.
xSemaphoreGetMutexHolder(xSemaphore)
If xMutex is indeed a mutex type semaphore, return the current mutex holder. If xMutex is not a mutex type
semaphore, or the mutex is available (not held by a task), return NULL.
Note: This is a good way of determining if the calling task is the mutex holder, but not a good way of deter-
mining the identity of the mutex holder as the holder may change between the function exiting and the returned
value being tested.
xSemaphoreGetMutexHolderFromISR(xSemaphore)
If xMutex is indeed a mutex type semaphore, return the current mutex holder. If xMutex is not a mutex type
semaphore, or the mutex is available (not held by a task), return NULL.
uxSemaphoreGetCount(xSemaphore)
If the semaphore is a counting semaphore then uxSemaphoreGetCount() returns its current count value. If the
semaphore is a binary semaphore then uxSemaphoreGetCount() returns 1 if the semaphore is available, and 0
if the semaphore is not available.
Type Definitions
typedef QueueHandle_t SemaphoreHandle_t
Espressif Systems 913
Submit Document Feedback
Release v4.4
To Next Page
Loading...