FreeRTOS::MutexBase Class Reference

Base class that provides the standard mutex interface to FreeRTOS::Mutex, FreeRTOS::StaticMutex, FreeRTOS::RecursiveMutex, and FreeRTOS::StaticRecursiveMutex. More...

#include <FreeRTOS/Mutex.hpp>

Inheritance diagram for FreeRTOS::MutexBase:

Public Member Functions
	MutexBase (const MutexBase &)=delete
MutexBase &	operator= (const MutexBase &)=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.
bool	lock (const TickType_t ticksToWait=portMAX_DELAY) const
	Function that calls xSemaphoreTake( SemaphoreHandle_t xSemaphore, TickType_t xTicksToWait )
bool	lockFromISR (bool &higherPriorityTaskWoken) const
	Function that calls xSemaphoreTakeFromISR ( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken )
bool	lockFromISR () const
	Function that calls xSemaphoreTakeFromISR ( SemaphoreHandle_t xSemaphore, signed BaseType_t *pxHigherPriorityTaskWoken )
bool	unlock () const
	Function that calls xSemaphoreGive( SemaphoreHandle_t xSemaphore )

Static Public Member Functions
static void *	operator new (size_t)=delete
static void *	operator new[] (size_t)=delete
static void *	operator new (size_t, void *ptr)
static void *	operator new[] (size_t, void *ptr)

Private Member Functions
	~MutexBase ()
	Destroy the MutexBase object by calling void vSemaphoreDelete( SemaphoreHandle_t xSemaphore )
	MutexBase (MutexBase &&) noexcept=default
MutexBase &	operator= (MutexBase &&) noexcept=default

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

Friends
class	Mutex
class	StaticMutex
class	RecursiveMutexBase
class	RecursiveMutex
class	StaticRecursiveMutex

Detailed Description

Base class that provides the standard mutex interface to FreeRTOS::Mutex, FreeRTOS::StaticMutex, FreeRTOS::RecursiveMutex, and FreeRTOS::StaticRecursiveMutex.

Note

This class is not intended to be instantiated by the user. Use FreeRTOS::Mutex, FreeRTOS::StaticMutex, FreeRTOS::RecursiveMutex, and FreeRTOS::StaticRecursiveMutex.

Constructor & Destructor Documentation

~MutexBase()

FreeRTOS::MutexBase::~MutexBase ( )

inlineprivate

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

Mutex.hpp

See also

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

Note

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

Member Function Documentation

isValid()

bool FreeRTOS::MutexBase::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.

Mutex.hpp

Return values

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

lock()

bool FreeRTOS::MutexBase::lock ( const TickType_t  ticksToWait = portMAX_DELAY ) const

inline

Function that calls xSemaphoreTake( SemaphoreHandle_t xSemaphore, TickType_t xTicksToWait )

Mutex.hpp

See also

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

Parameters

ticksToWait

The time in ticks to wait for the mutex 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 mutex.

Return values

true	If the mutex was locked.
false	If ticksToWait expired without the mutex becoming available.

Example Usage

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

lockFromISR() [1/2]

bool FreeRTOS::MutexBase::lockFromISR ( ) const

inline

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

Mutex.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.

lockFromISR() [2/2]

bool FreeRTOS::MutexBase::lockFromISR ( bool &  higherPriorityTaskWoken ) const

inline

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

Mutex.hpp

See also

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

Parameters

higherPriorityTaskWoken

It is possible (although unlikely, and dependent on the semaphore type) that a mutex will have one or more tasks blocked on it waiting to give the mutex. Calling lockFromISR() will make a task that was blocked waiting to give the mutex 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.

Returns

true If the mutex was successfully locked.

false If the mutex was not successfully locked because it was not available.

unlock()

bool FreeRTOS::MutexBase::unlock ( ) const

inline

Function that calls xSemaphoreGive( SemaphoreHandle_t xSemaphore )

Mutex.hpp

See also

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

Warning

This must not be used from an ISR.

Returns

true If the mutex was unlocked.

false If an error occurred. Mutexes (semaphores) are implemented using queues. An error can occur if there is no space on the queue to post a message indicating that the mutex was not first locked correctly.

Example Usage

#include <FreeRTOS/Mutex.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
void MyTask::taskFunction() {
  FreeRTOS::Mutex mutex;
 
  if (mutex.isValid()) {
    if (mutex.unlock()) {
      // We would expect this call to fail because we cannot unlock a mutex
      // without first locking it!
    }
 
    // Lock the mutex - don't block if the mutex is not immediately available.
    if (mutex.lock(0)) {
      // We now have the mutex and can access the shared resource.
      // ...
      // We have finished accessing the shared resource so can unlock the mutex.
      if (!mutex.unlock()) {
        // We would not expect this call to fail because we must have obtained
        // the mutex to get here.
      }
    }
  }
}

---

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

• /home/runner/work/FreeRTOS-Cpp/FreeRTOS-Cpp/FreeRTOS-Cpp/include/FreeRTOS/Mutex.hpp