Atmel Software Framework

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
xSemaphoreCreateCounting

semphr.

h

xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )

Macro that creates a counting semaphore by using the existing queue mechanism.

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 (decrementing the semaphore count value). The count value is therefore the difference between the number of events that have occurred and the number that have been processed. In this case it is desirable for the initial count value to be zero.

2) Resource management.

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.

Parameters
uxMaxCountThe maximum count value that can be reached. When the semaphore reaches this value it can no longer be 'given'.
uxInitialCountThe count value assigned to the semaphore when it is created.
Returns
Handle to the created semaphore. Null if the semaphore could not be created.

Example usage:

 xSemaphoreHandle xSemaphore;
 void vATask( void * pvParameters )
 {
 xSemaphoreHandle xSemaphore = NULL;
Semaphore cannot be used before a call to xSemaphoreCreateCounting().
The max value to which the semaphore can count should be 10, and the
initial value assigned to the count should be 0.
    xSemaphore = xSemaphoreCreateCounting( 10, 0 );
    if( xSemaphore != NULL )
    {
The semaphore was created successfully.
The semaphore can now be used.
    }
 }