KernelSemaphore and Mutexes

Updated Mar 2025

xSemaphoreTake

[Semaphores]

TIP: In many usage scenarios it is faster and more memory efficient to use a direct to task notification instead of a semaphore

semphr. h

1 xSemaphoreTake( SemaphoreHandle_t xSemaphore,
2                 TickType_t xTicksToWait );

Copy

Macro to obtain a semaphore. The semaphore must have previously been created with a call to

xSemaphoreCreateBinary()

Copy

xSemaphoreCreateMutex()

Copy

xSemaphoreCreateCounting()

Copy

This macro must not be called from an ISR.

xQueueReceiveFromISR()

Copy

Parameters:

• xSemaphore

  A handle to the semaphore being taken - obtained when the semaphore was created.

• xTicksToWait

  The time in ticks to wait for the semaphore to become available. The macro

  portTICK_PERIOD_MS

  Copy
  can be used to convert this to a real time. A block time of zero can be used to poll the semaphore. If INCLUDE_vTaskSuspend is set to '1' then specifying the block time as

  portMAX_DELAY

  Copy
  will cause the task to block indefinitely (without a timeout).

Returns:

• pdTRUE if the semaphore was obtained.
• pdFALSE if

  xTicksToWait

  Copy
  expired without the semaphore becoming available.

Example usage:

1SemaphoreHandle_t xSemaphore = NULL;
2
3/* A task that creates a semaphore. */
4void vATask( void * pvParameters )
5{
6    /* Create the semaphore to guard a shared resource. As we are using
7       the semaphore for mutual exclusion we create a mutex semaphore
8       rather than a binary semaphore. */
9    xSemaphore = xSemaphoreCreateMutex();
10}
11
12/* A task that uses the semaphore. */
13void vAnotherTask( void * pvParameters )
14{
15    /* ... Do other things. */
16
17    if( xSemaphore != NULL )
18    {
19        /* See if we can obtain the semaphore. If the semaphore is not
20           available wait 10 ticks to see if it becomes free. */
21        if( xSemaphoreTake( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )
22        {
23            /* We were able to obtain the semaphore and can now access the
24               shared resource. */
25
26            /* ... */
27
28            /* We have finished accessing the shared resource. Release the
29               semaphore. */
30            xSemaphoreGive( xSemaphore );
31        }
32        else
33        {
34            /* We could not obtain the semaphore and can therefore not access
35               the shared resource safely. */
36        }
37    }
38}

Copy