[Study FreeRTOS-Semaphore API] 4.1 vSemaphoreCreateBinary()

#include "FreeRTOS.h"
#include "semphr.h"

vSemaphoreCreateBinary(SemaphoreHandle_t xSemaphore);

Summary
NOTE: The vSemaphoreCreateBinary() macro remains in the source code to ensure backward
compatibility, but it should not be used in new designs. Use the xSemaphoreCreateBinary()
function instead.
A macro that creates a binary semaphore. A semaphore must be explicitly created before it
can be used.

Parameters
xSemaphore  Variable of type SemaphoreHandle_t that will store the handle of the semaphore being created.

Return Values
None.

If,  following  a  call  to  vSemaphoreCreateBinary(),  xSemaphore  is  equal  to  NULL,  then  the
semaphore  cannot  be  created  because  there  is  insufficient  heap  memory  available  for
FreeRTOS  to  allocate  the  semaphore  data  structures.   In  all  other  cases,  xSemaphore  will
hold the handle of the created semaphore.

Notes
Binary  semaphores  and  mutexes  are  very  similar,  but  do  have  some  subtle  differences.
Mutexes  include  a  priority  inheritance  mechanism,  binary  semaphores  do  not.  This  makes
binary  semaphores  the  better  choice  for  implementing  synchronization  (between  tasks  or
between  tasks  and  an  interrupt),  and  mutexes  the  better  choice  for  implementing  simple
mutual exclusion. 


Binary  Semaphores  –  A  binary  semaphore  used  for  synchronization  does  not  need  to  be
‘given’  back  after  it  has  been  successfully  ‘taken’  (obtained).   Task  synchronization  is
implemented by  having one task  or interrupt  ‘give’  the semaphore, and  another task  ‘take’  the
semaphore (see the xSemaphoreGiveFromISR() documentation).
Mutexes  –  The priority of a task that  holds  a mutex  will  be raised if another task of higher
priority attempts to obtain the same  mutex.    The task that  already holds  the mutex  is said to
‘inherit’  the  priority  of  the  task  that  is  attempting  to  ‘take’  the  same  mutex.   The  inherited
priority will be ‘disinherited’ when the mutex is returned (the task that inherited a higher priority
while it held a mutex will return to its original priority when the mutex is returned).
A task that obtains a mutex that is used for mutual exclusion must always give the mutex back
–  otherwise no other task will ever be able to obtain the same mutex.    An example of a mutex
being used to implement mutual exclusion is provided in the xSemaphoreTake() section of this
manual.
Mutexes  and  binary  semaphores  are  both  referenced  using  variables  that  have  an
SemaphoreHandle_t  type,  and can be used in any API function  that takes a parameter of  that
type.
Mutexes and binary semaphores  that were  created using the  old  vSemaphoreCreateBinary()
macro,  as  opposed  to  the  preferred  xSemaphoreCreateBinary()  function,  are  both  created
such  that  the  first  call  to  xSemaphoreTake()  on  the  semaphore  or  mutex  will  pass.  Note
vSemaphoreCreateBinary() is deprecated and must not be used in new applications.  Binary
semaphores created using the xSemaphoreCreateBinary() function are created ‘empty’, so the
semaphore must first be given before the semaphore can be taken (obtained) using a call to
xSemaphoreTake().


Example
SemaphoreHandle_t xSemaphore;
void vATask( void * pvParameters )
{
/* Attempt to create a semaphore.
NOTE: New designs should use the xSemaphoreCreateBinary() function, not the vSemaphoreCreateBinary() macro. */
vSemaphoreCreateBinary( xSemaphore );

if( xSemaphore == NULL )
{
/* There was insufficient FreeRTOS heap available for the semaphore to
be created successfully. */
}
else
{
/* The semaphore can now be used. Its handle is stored in the xSemaphore
variable. */
}