Atmel Software Framework

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

semphr.

h

xSemaphoreTake(
                     xSemaphoreHandle xSemaphore,
                     portTickType xBlockTime
                 )

Macro to obtain a semaphore. The semaphore must have previously been created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or xSemaphoreCreateCounting().

Parameters
xSemaphoreA handle to the semaphore being taken - obtained when the semaphore was created.
xBlockTimeThe time in ticks to wait for the semaphore to become available. The macro portTICK_RATE_MS can be used to convert this to a real time. A block time of zero can be used to poll the semaphore. A block time of portMAX_DELAY can be used to block indefinitely (provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h).
Returns
pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime expired without the semaphore becoming available.

Example usage:

 xSemaphoreHandle xSemaphore = NULL;
A task that creates a semaphore.
 void vATask( void * pvParameters )
 {
Create the semaphore to guard a shared resource.
    vSemaphoreCreateBinary( xSemaphore );
 }
A task that uses the semaphore.
 void vAnotherTask( void * pvParameters )
 {
... Do other things.

if( xSemaphore != NULL )
{

See if we can obtain the semaphore. If the semaphore is not available wait 10 ticks to see if it becomes free. if( xSemaphoreTake( xSemaphore, ( portTickType ) 10 ) == pdTRUE ) { We were able to obtain the semaphore and can now access the shared resource.

...
We have finished accessing the shared resource.  Release the
semaphore.
            xSemaphoreGive( xSemaphore );
        }
        else
        {
We could not obtain the semaphore and can therefore not access
the shared resource safely.
        }
    }
 }