FreeRTOS::Mutex Class Reference

Class that encapsulates the functionality of a FreeRTOS mutex. More...

#include <FreeRTOS/Mutex.hpp>

Inheritance diagram for FreeRTOS::Mutex:

Collaboration diagram for FreeRTOS::Mutex:

Public Member Functions
	Mutex ()
	Construct a new Mutex object by calling SemaphoreHandle_t xSemaphoreCreateMutex( void )
	Mutex (const Mutex &)=delete
Mutex &	operator= (const Mutex &)=delete
	Mutex (Mutex &&) noexcept=default
Mutex &	operator= (Mutex &&) noexcept=default
Public Member Functions inherited from FreeRTOS::MutexBase
	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 )

Additional Inherited Members
Static Public Member Functions inherited from FreeRTOS::MutexBase
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)

Detailed Description

Class that encapsulates the functionality of a FreeRTOS mutex.

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

Mutexes and binary semaphores 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.

The priority of a task that locks a mutex will be temporarily 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 lock the same mutex. This means the mutex must always be unlocked back otherwise the higher priority task will never be able to lock the mutex, and the lower priority task will never 'disinherit' the priority.

Constructor & Destructor Documentation

Mutex()

FreeRTOS::Mutex::Mutex ( )

inline

Construct a new Mutex object by calling SemaphoreHandle_t xSemaphoreCreateMutex( void )

Mutex.hpp

See also

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

Warning

The user should call isValid() on this object to verify that the mutex was created successfully in case the memory required to create the queue could not be allocated.

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()) {
    // The recursive mutex was created successfully and can now be used.
  }
}

---

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

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