Base class that provides the standard semaphore interface to FreeRTOS::BinarySemaphore, FreeRTOS::StaticBinarySemaphore, FreeRTOS::CountingSemaphore, and FreeRTOS::StaticCountingSemaphore. More...

#include <FreeRTOS/Semaphore.hpp>

Inheritance diagram for FreeRTOS::SemaphoreBase:

[legend]

Public Member Functions
	SemaphoreBase (const SemaphoreBase &)=delete

SemaphoreBase &	operator= (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...

Static Public Member Functions
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

Private Member Functions
	~SemaphoreBase ()
	Destroy the SemaphoreBase object by calling `void vSemaphoreDelete( SemaphoreHandle_t xSemaphore )` More...

	SemaphoreBase (SemaphoreBase &&) noexcept=default

SemaphoreBase &	operator= (SemaphoreBase &&) noexcept=default

Private Attributes
SemaphoreHandle_t	handle = NULL
	Handle used to refer to the semaphore when using the FreeRTOS interface.

Friends
class	BinarySemaphore

class	StaticBinarySemaphore

class	CountingSemaphore

class	StaticCountingSemaphore

Detailed Description

Base class that provides the standard semaphore interface to FreeRTOS::BinarySemaphore, FreeRTOS::StaticBinarySemaphore, FreeRTOS::CountingSemaphore, and FreeRTOS::StaticCountingSemaphore.

Note: This class is not intended to be instantiated by the user. Use FreeRTOS::BinarySemaphore, FreeRTOS::StaticBinarySemaphore, FreeRTOS::CountingSemaphore, or FreeRTOS::StaticCountingSemaphore.

Constructor & Destructor Documentation

◆ ~SemaphoreBase()

FreeRTOS::SemaphoreBase::~SemaphoreBase ( )

inlineprivate

Destroy the SemaphoreBase object by calling void vSemaphoreDelete( SemaphoreHandle_t xSemaphore )

Semaphore.hpp

See also: https://www.freertos.org/a00113.html#vSemaphoreDelete

Note: Do not delete a semaphore that has tasks blocked on it (tasks that are in the Blocked state waiting for the semaphore to become available).

Member Function Documentation

◆ getCount()

UBaseType_t FreeRTOS::SemaphoreBase::getCount ( ) const

inline

Function that calls UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xSemaphore )

Semaphore.hpp

See also: https://www.freertos.org/uxSemaphoreGetCount.html

Returns the count of a semaphore.

Returns: UBaseType_t If the semaphore is a counting semaphore then the semaphores current count value is returned. If the semaphore is a binary semaphore then 1 is returned if the semaphore is available, and 0 is returned if the semaphore is not available.

◆ give()

bool FreeRTOS::SemaphoreBase::give ( ) const

inline

Function that calls xSemaphoreGive( SemaphoreHandle_t xSemaphore )

Semaphore.hpp

See also: https://www.freertos.org/a00123.html

Function to release a semaphore.

This must not be used from an ISR. See giveFromISR() for an alternative which can be used from an ISR.

Return values

true	If the semaphore was released.
false	If an error occurred. Semaphores are implemented using queues. An error can occur if there is no space on the queue to post a message indicating that the semaphore was not first obtained correctly.

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()) {
    if (binarySemaphore.give()) {
      // We would expect this call to fail because we cannot give a semaphore
      // without first "taking" it!
    }
 
    // Obtain the semaphore - don't block if the semaphore is not immediately
    // available.
    if (binarySemaphore.take(0)) {
      // We now have the semaphore and can access the shared resource.
      // ...
      // We have finished accessing the shared resource so can free the
      // semaphore.
      if (!binarySemaphore.give()) {
        // We would not expect this call to fail because we must have obtained
        // the semaphore to get here.
      }
    }
  }
}

◆ giveFromISR() [1/2]

bool FreeRTOS::SemaphoreBase::giveFromISR ( ) const

inline

Function that calls xSemaphoreGiveFromISR( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken )

Semaphore.hpp

See also: https://www.freertos.org/a00124.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ giveFromISR() [2/2]

bool FreeRTOS::SemaphoreBase::giveFromISR ( bool & higherPriorityTaskWoken ) const

inline

Function that calls xSemaphoreGiveFromISR( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken )

Semaphore.hpp

See also: https://www.freertos.org/a00124.html

Function to release a semaphore.

This macro can be used from an ISR.

Parameters

higherPriorityTaskWoken giveFromISR() will set higherPriorityTaskWoken to true if giving the semaphore caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If giveFromISR() sets this value to true then a context switch should be requested before the interrupt is exited.

Return values

true	If the semaphore was successfully given.
false	Otherwise.

Example Usage

#include <FreeRTOS/Semaphore.hpp>
#include <FreeRTOS/Task.hpp>
 
#define LONG_TIME 0xffff
#define TICKS_TO_WAIT 10
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
static FreeRTOS::StaticBinarySemaphore binarySemaphore;
 
void MyTask::taskFunction() {
  // We are using the semaphore for synchronisation so we create a binary
  // semaphore rather than a mutex.  We must make sure that the interrupt does
  // not attempt to use the semaphore before it is created!
 
  for (;;) {
    // We want this task to run every 10 ticks of a timer.  The semaphore was
    // created before this task was started.
 
    // Block waiting for the semaphore to become available.
    if (binarySemaphore.take()) {
      // It is time to execute.
 
      // ...
 
      // We have finished our task.  Return to the top of the loop where we will
      // block on the semaphore until it is time to execute again.  Note when
      // using the semaphore for synchronisation with an ISR in this manner
      // there is no need to 'give' the semaphore back.
    }
  }
}
 
// Timer ISR
void vTimerISR(void* pvParameters) {
  static TickType_t ucLocalTickCount = 0;
  bool higherPriorityTaskWoken = false;
 
  // A timer tick has occurred.
 
  // ... Do other time functions.
 
  // Is it time for MyTask() to run?
  ucLocalTickCount++;
  if (ucLocalTickCount >= TICKS_TO_WAIT) {
    // Unblock the task by releasing the semaphore.
    binarySemaphore.giveFromISR(higherPriorityTaskWoken);
 
    // Reset the count so we release the semaphore again in 10 ticks time.
    ucLocalTickCount = 0;
  }
 
  // If higherPriorityTaskWoken was set to true you we should yield.  The actual
  // macro used here is port specific.
  FreeRTOS::Kernel::yield();
}

◆ isValid()

bool FreeRTOS::SemaphoreBase::isValid ( ) const

inline

Function that checks if the underlying semaphore handle is not NULL. This should be used to ensure a semaphore has been created correctly.

Semaphore.hpp

Return values

true	the handle is not NULL.
false	the handle is NULL.

◆ take()

bool FreeRTOS::SemaphoreBase::take ( const TickType_t ticksToWait = portMAX_DELAY ) const

inline

Function that calls xSemaphoreTake( SemaphoreHandle_t xSemaphore, TickType_t xTicksToWait )

Semaphore.hpp

See also: https://www.freertos.org/a00122.html

Function to obtain a semaphore.

This macro must not be called from an ISR. takeFromISR() can be used to take a semaphore from within an interrupt if required, although this would not be a normal operation. Semaphores use queues as their underlying mechanism, so functions are to some extent interoperable.

Parameters

ticksToWait The time in ticks to wait for the semaphore to become available. The macro portTICK_PERIOD_MS can be used to convert this to a real time. A block time of zero can be used to poll the semaphore.

Return values

true	If the semaphore was obtained.
false	If xTicksToWait expired without the semaphore becoming available.

Example Usage

#include <FreeRTOS/Semaphore.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
class MyOtherTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
FreeRTOS::StaticBinarySemaphore binarySemaphore;
 
// A task that uses the semaphore.
void MyTask::taskFunction() {
  // Do something
}
 
// Another task that uses the semaphore.
void MyOtherTask::taskFunction() {
 
  if (binarySemaphore.isValid()) {
    // See if we can obtain the semaphore.  If the semaphore is not available
    // wait 10 ticks to see if it becomes free.
    if (binarySemaphore.take()) {
      // We were able to obtain the semaphore and can now access the shared
      // resource.
 
      // ...
 
      // We have finished accessing the shared resource.  Release the semaphore.
      binarySemaphore.give();
    } else {
      // We could not obtain the semaphore and can therefore not access the
      // shared resource safely.
    }
  }
}

◆ takeFromISR() [1/2]

bool FreeRTOS::SemaphoreBase::takeFromISR ( ) const

inline

Function that calls xSemaphoreTakeFromISR( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken)

Semaphore.hpp

See also: https://www.freertos.org/xSemaphoreTakeFromISR.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ takeFromISR() [2/2]

bool FreeRTOS::SemaphoreBase::takeFromISR ( bool & higherPriorityTaskWoken ) const

inline

Function that calls xSemaphoreTakeFromISR( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken)

Semaphore.hpp

See also: https://www.freertos.org/xSemaphoreTakeFromISR.html

A version of take() that can be called from an ISR. Unlike take(), takeFromISR() does not permit a block time to be specified.

Parameters

higherPriorityTaskWoken It is possible (although unlikely, and dependent on the semaphore type) that a semaphore will have one or more tasks blocked on it waiting to give the semaphore. Calling takeFromISR() will make a task that was blocked waiting to give the semaphore leave the Blocked state. If calling the API function causes a task to leave the Blocked state, and the unblocked task has a priority equal to or higher than the currently executing task (the task that was interrupted), then, internally, the API function will set higherPriorityTaskWoken to true. If takeFromISR() sets higherPriorityTaskWoken to true, then a context switch should be performed before the interrupt is exited. This will ensure that the interrupt returns directly to the highest priority Ready state task. The mechanism is identical to that used in the FreeRTOS::receiveFromISR() function, and readers are referred to the FreeRTOS::receiveFromISR() documentation for further explanation.

Return values

true	If the semaphore was successfully taken.
false	If the semaphore was not successfully taken because it was not available.

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

/home/runner/work/FreeRTOS-Cpp/FreeRTOS-Cpp/FreeRTOS-Cpp/include/FreeRTOS/Semaphore.hpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~SemaphoreBase()

Member Function Documentation

◆ getCount()

◆ give()

◆ giveFromISR() [1/2]

◆ giveFromISR() [2/2]

◆ isValid()

◆ take()

◆ takeFromISR() [1/2]

◆ takeFromISR() [2/2]