FreeRTOS-Cpp
Public Member Functions | List of all members
FreeRTOS::BinarySemaphore Class Reference

Class that encapsulates the functionality of a FreeRTOS binary semaphore. More...

#include <FreeRTOS/Semaphore.hpp>

Inheritance diagram for FreeRTOS::BinarySemaphore:
Inheritance graph
[legend]
Collaboration diagram for FreeRTOS::BinarySemaphore:
Collaboration graph
[legend]

Public Member Functions

 BinarySemaphore ()
 Construct a new BinarySemaphore object by calling SemaphoreHandle_t xSemaphoreCreateBinary( void ) More...
 
 BinarySemaphore (const BinarySemaphore &)=delete
 
BinarySemaphoreoperator= (const BinarySemaphore &)=delete
 
 BinarySemaphore (BinarySemaphore &&) noexcept=default
 
BinarySemaphoreoperator= (BinarySemaphore &&) noexcept=default
 
- Public Member Functions inherited from FreeRTOS::SemaphoreBase
 SemaphoreBase (const SemaphoreBase &)=delete
 
SemaphoreBaseoperator= (const SemaphoreBase &)=delete
 
bool isValid () const
 Function that checks if the underlying semaphore handle is not NULL. This should be used to ensure a semaphore has been created correctly. More...
 
UBaseType_t getCount () const
 Function that calls UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xSemaphore ) More...
 
bool take (const TickType_t ticksToWait=portMAX_DELAY) const
 Function that calls xSemaphoreTake( SemaphoreHandle_t xSemaphore, TickType_t xTicksToWait ) More...
 
bool takeFromISR (bool &higherPriorityTaskWoken) const
 Function that calls xSemaphoreTakeFromISR( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken) More...
 
bool takeFromISR () const
 Function that calls xSemaphoreTakeFromISR( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken) More...
 
bool give () const
 Function that calls xSemaphoreGive( SemaphoreHandle_t xSemaphore ) More...
 
bool giveFromISR (bool &higherPriorityTaskWoken) const
 Function that calls xSemaphoreGiveFromISR( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken ) More...
 
bool giveFromISR () const
 Function that calls xSemaphoreGiveFromISR( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken ) More...
 

Additional Inherited Members

- Static Public Member Functions inherited from FreeRTOS::SemaphoreBase
static void * operator new (size_t, void *ptr)
 
static void * operator new[] (size_t, void *ptr)
 
static void * operator new (size_t)=delete
 
static void * operator new[] (size_t)=delete
 

Detailed Description

Class that encapsulates the functionality of a FreeRTOS binary semaphore.

Each binary semaphore require a small amount of RAM that is used to hold the semaphore's state. If a binary semaphore is created using FreeRTOS::BinarySemaphore then the required RAM is automatically allocated from the FreeRTOS heap. If a binary semaphore is created using FreeRTOS::StaticBinarySemaphore then the RAM is provided by the application writer as part of the class and allows the RAM to be statically allocated at compile time. See the Static Vs Dynamic allocation page for more information.

The semaphore is created in the 'empty' state, meaning the semaphore must first be given using the give() API function before it can subsequently be taken (obtained) using the take() function.

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

A binary semaphore need not be given back once obtained, so task synchronisation can be implemented by one task/interrupt continuously 'giving' the semaphore while another continuously 'takes' the semaphore. This is demonstrated by the sample code on the giveFromISR() documentation page. Note the same functionality can often be achieved in a more efficient way using a direct to task notification.

The priority of a task that 'takes' a mutex can potentially be raised if another task of higher priority attempts to obtain the same mutex. The task that owns the mutex 'inherits' the priority of the task attempting to 'take' the same mutex. This means the mutex must always be 'given' back - otherwise the higher priority task will never be able to obtain the mutex, and the lower priority task will never 'disinherit' the priority. An example of a mutex being used to implement mutual exclusion is provided on the take() documentation page.

Constructor & Destructor Documentation

◆ BinarySemaphore()

FreeRTOS::BinarySemaphore::BinarySemaphore ( )
inline

Construct a new BinarySemaphore object by calling SemaphoreHandle_t xSemaphoreCreateBinary( void )

Semaphore.hpp

See also
https://www.freertos.org/xSemaphoreCreateBinary.html
Warning
The user should call isValid() on this object to verify that the binary semaphore was created successfully in case the memory required to create the queue could not be allocated.

Example Usage

#include <FreeRTOS/Semaphore.hpp>
#include <FreeRTOS/Task.hpp>
class MyTask : public FreeRTOS::Task {
public:
void taskFunction() final;
};
void MyTask::taskFunction() {
FreeRTOS::BinarySemaphore binarySemaphore;
if (binarySemaphore.isValid()) {
// The semaphore was created successfully.
// The semaphore can now be used.
}
// Rest of task code.
}
Class that encapsulates the functionality of a FreeRTOS binary semaphore.
Definition: Semaphore.hpp:309
bool isValid() const
Function that checks if the underlying semaphore handle is not NULL. This should be used to ensure a ...
Definition: Semaphore.hpp:71
Class that encapsulates the functionality of a FreeRTOS task.
Definition: Task.hpp:1323

The documentation for this class was generated from the following file: