Mutexes for Concurrent Access Control

1. The Danger of Concurrent Access: Race Conditions

When two or more tasks attempt to access and modify a shared resource—be it a global variable, a hardware register, or a communication bus—the final outcome can depend on the unpredictable order in which the tasks are scheduled by the operating system. This situation is called a race condition, and it's a primary source of intermittent and hard-to-debug bugs in concurrent systems.

To understand what a race condition is and why it's so problematic, let's start with a clear, visual explanation.

The key insight is that even a simple operation like variable++ is not "atomic" on most processors. It involves three distinct steps: read the value from memory, modify the value in a register, and write the new value back to memory. A task switch can occur between any of these steps, leading to corrupted data.

To see this bug in action on a real ESP32, the same video provides a practical demonstration.

The segment of code that accesses the shared resource and must be protected from concurrent access is known as a critical section. To solve the race condition, we need a mechanism to enforce mutual exclusion, ensuring that only one task can be inside its critical section at any given time.

2. The Solution: Mutexes for Mutual Exclusion

The most common tool for enforcing mutual exclusion is a mutex (short for mutual exclusion). Think of a mutex as a token or a key for a shared resource.

• Before entering a critical section, a task must "take" or "lock" the mutex.
• If the mutex is already held by another task, the requesting task is put into a blocked state (consuming no CPU) until the mutex is available.
• Once the task has the mutex, it can safely execute its critical section.
• After leaving the critical section, the task must "give" or "unlock" the mutex, allowing other waiting tasks to proceed.

This is analogous to a key for a single-occupancy restroom. Only the person with the key can enter. Others must wait for the key to be returned.

It's important to distinguish a mutex from the semaphores we've seen before. While they share some implementation details in FreeRTOS, their purpose is different. A mutex is for guarding a single resource and has a concept of "ownership" (only the task that took it can give it back). A semaphore is more of a general signaling mechanism.

3. Implementing Mutexes with the FreeRTOS API

In ESP-IDF and FreeRTOS, mutexes are created and managed using a set of functions from the semphr.h header. The official ESP-IDF documentation provides the API reference.

The basic workflow is as follows:

1. Create: Call xSemaphoreCreateMutex() once to create the mutex. Store the returned SemaphoreHandle_t.
2. Take: In each task, before the critical section, call xSemaphoreTake(mutex_handle, portMAX_DELAY).
3. Give: After the critical section, call xSemaphoreGive(mutex_handle).

Let's watch a demonstration of this pattern.

Now, let's examine a complete, working example that you can build and run.

4. A Safer C++ Approach: RAII and lock_guard

The C-style take/give pattern works, but it has a weakness. What happens if the code inside the critical section returns early or throws an exception?

void risky_function(SemaphoreHandle_t mutex) {
    xSemaphoreTake(mutex, portMAX_DELAY);
    
    // Critical section
    if (some_error_condition) {
        // Whoops, we returned without giving the mutex back!
        // This will cause a deadlock.
        return; 
    }
    
    xSemaphoreGive(mutex);
}

This is a very easy mistake to make. Your C++ background provides a more robust and elegant solution: the RAII (Resource Acquisition Is Initialization) pattern. The idea is to tie the lifetime of a resource (like a mutex lock) to the lifetime of an object on the stack.

• Acquire: The mutex is locked in the object's constructor.
• Release: The mutex is unlocked in the object's destructor.

This guarantees that the mutex is always released when the lock object goes out of scope, no matter how the block is exited—whether by normal completion, a return statement, or an exception.

While we aren't using std::thread on the ESP32, we can easily create our own simple RAII wrapper for a FreeRTOS mutex that mimics std::lock_guard.

#include "freertos/semphr.h"

// A simple RAII wrapper for a FreeRTOS mutex
class FreeRTOSMutexLock {
public:
    // Constructor: Takes the mutex
    explicit FreeRTOSMutexLock(SemaphoreHandle_t& mutex) : m_mutex(mutex) {
        xSemaphoreTake(m_mutex, portMAX_DELAY);
    }

    // Destructor: Gives the mutex back
    ~FreeRTOSMutexLock() {
        xSemaphoreGive(m_mutex);
    }

    // Disable copying and assignment
    FreeRTOSMutexLock(const FreeRTOSMutexLock&) = delete;
    FreeRTOSMutexLock& operator=(const FreeRTOSMutexLock&) = delete;

private:
    SemaphoreHandle_t& m_mutex;
};

Now, our risky_function becomes completely safe and much cleaner:

void safe_function(SemaphoreHandle_t mutex) {
    FreeRTOSMutexLock lock(mutex); // Mutex is taken here

    // Critical section
    if (some_error_condition) {
        return; // It's safe! The destructor for 'lock' will be called, releasing the mutex.
    }
    
} // Mutex is automatically released here when 'lock' goes out of scope.

This RAII pattern is a cornerstone of safe and modern C++. Applying it to embedded resources like mutexes makes your firmware significantly more robust.

5. Important Mutex Concepts: Priority Inversion & Inheritance

A classic problem in real-time systems is priority inversion. Imagine this scenario:

1. A low-priority task takes a mutex.
2. A high-priority task preempts it and tries to take the same mutex, but blocks.
3. A medium-priority task (that doesn't need the mutex) starts running, preventing the low-priority task from ever finishing and releasing the mutex.

Effectively, the high-priority task is being held up by a medium-priority task. To solve this, FreeRTOS mutexes implement priority inheritance. When the high-priority task blocks on the mutex, the RTOS temporarily boosts the priority of the low-priority task holding the mutex. This allows the low-priority task to finish its critical section quickly, release the mutex, and unblock the high-priority task. This feature is a key reason to use a mutex for mutual exclusion instead of a binary semaphore.

Conclusion

In this lesson, we tackled the critical challenge of managing shared resources in a multitasking environment. You learned how to identify potential race conditions and protect your code using mutexes.

Key Takeaways:

• Race Conditions: Occur when multiple tasks access a shared resource, leading to unpredictable and buggy behavior. The code accessing the resource is a critical section.
• Mutexes: Provide mutual exclusion to ensure only one task can enter a critical section at a time, preventing race conditions.
• FreeRTOS API: The core functions are xSemaphoreCreateMutex(), xSemaphoreTake(), and xSemaphoreGive().
• RAII is Safer: Using a C++ RAII wrapper class (lock_guard style) is far safer than manual take/give calls, as it guarantees the mutex is released even if errors occur.
• Priority Inheritance: This is a key feature of FreeRTOS mutexes that automatically resolves priority inversion, a common pitfall in real-time systems.

Our system is now more robust, with tasks communicating via queues and safely sharing resources via mutexes. However, we're still letting the FreeRTOS scheduler treat all our tasks equally. What if our motor control needs to be more responsive than our sensor logging?

In the next lesson, we will learn how to apply appropriate task priorities to ensure our most critical tasks, like motor control, get the CPU time they need to remain responsive, while less critical tasks run in the background.