semphr. h

sem_t mutex_create( void )

Creates a new mutex type semaphore instance, and returns a handle by which the new mutex can be referenced.

Internally, within the FreeRTOS implementation, mutex semaphores use a block of memory, in which the mutex structure is stored. If a mutex is created using mutex_create() then the required memory is automatically dynamically allocated inside the mutex_create() function. (see http://www.freertos.org/a00111.html). If a mutex is created using mutex_create_static() then the application writer must provided the memory. mutex_create_static() therefore allows a mutex to be created without using any dynamic memory allocation.

Mutexes created using this function can be accessed using the sem_wait() and sem_post() macros. The mutex_recursive_take() and mutex_recursive_give() macros must not be used.

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 sem_binary_create() 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.

Returns

If the mutex was successfully created then a handle to the created semaphore is returned. If there was not enough heap to allocate the mutex data structures then NULL is returned.

Example usage:

sem_t xSemaphore;

void vATask( void * pvParameters )
{
   // Semaphore cannot be used before a call to mutex_create().
   // This is a macro so pass the variable in directly.
   xSemaphore = mutex_create();

   if( xSemaphore != NULL )
   {
       // The semaphore was created successfully.
       // The semaphore can now be used.
   }
}