Appendix: Mutexes in Rust + Embassy

A mutex is a synchronization structure that allows sharing data across concurrency boundaries, while preventing race conditions. As mutexes are different in Rust compared to other languages like Java or C++, this appendix was added to help fill in the gaps and show some common pitfalls. This appendix will start from the very basics, so feel free to skip some parts if you already know these things.

Why and what is a mutex?

When you want to have concurrency in a program, you will come to a point where it becomes necessary to share some data. An example of such a situation could be:

use std::time::Duration;
use std::thread;


// Global shared memory
static mut COUNTER: u32 = 0;


pub fn main() {
    thread::scope(|s| {
        // We start a first thread
        s.spawn(|| unsafe {
            // We read, increment, write back the counter
            for _ in 0..100 {
                let mut count = COUNTER;
                count += 1;
                thread::sleep(Duration::from_millis(1));
                COUNTER = count;
            }
        });
        // We start another thread
        s.spawn(|| unsafe {
            // We read, increment, write back the counter
            for _ in 0..100 {
                let mut count = COUNTER;
                count += 1;
                thread::sleep(Duration::from_millis(1));
                COUNTER = count;
            }
        });
    }); // We join the two threads


    // And print the result which is most probably not equal to 200
    println!("Result of the count: {} == 200?", unsafe { COUNTER });
}

The above example has the issue that the resulting count is not always 200. Such a bug is called a race condition and stems from the issue that both write to, and read from the same variable concurrently without acknowledging each other. This is where mutexes come in, as they provide a way to ensure exclusive access to a piece of memory.

Mutexes in Rust

The Rust standard library provides a Mutex (https://doc.rust-lang.org/std/sync/struct.Mutex.html) type. Traditionally, in languages like Java or C++, one would add an extra variable containing a mutex. This mutex would then be used in conjunction with the piece of memory we want to protect. Often, this can lead to error prone code, as it is not very difficult to not lock the mutex and just use the memory that should have been protected.

This is where Rust's borrow checker and Mutex come in. Instead of having a second variable containing a mutex, the protected data is stored inside the mutex, making the mutex a container type. When you would want to use the protected data, the only way would be to lock the mutex and retrieve a guard. This guard works like a smart pointer that releases the lock when dropped.

An example use of Rust's Mutex:

use std::sync::Mutex;
let counter = Mutex::new(0usize);
*counter.lock().unwrap() += 1;

As can be seen from the example, we first get a Result back when locking a mutex. This is a safety feature from Rust, which denotes that another thread may have panic'ed while holding the lock. This may result in unexpected behavior, as the data protected by the mutex may be in an inconsistent state. Correctly handling this Result helps to detect and mitigate this.

A common pattern in concurrent Java code, is to repeatably lock a mutex. This is possible due to the reentrant nature of mutexes in Java. Mutexes in Rust are however not reentrant, so locking a mutex a second time, while the first one is still active, will block the current thread. This is independent on where you lock your mutex for the second time. The idea is here that you would lock a mutex, and keep the guard until you no longer need it.

Some possible unexpected behavior of mutex guards in Rust is how long they live. A possible situation could be the following: there is a mutex guarding a Vec and you want to pop the last element after which you want to immediately release the lock. One naive way to write this, would be:

let v = Mutex::new(vec![1, 2, 3]);
if let Some(element) = v.lock().unwrap().pop() {
    // Do something useful with `element`.
    // The lock is still active here due to the `if let`
} // <- the guard is dropped here

This is due to the fact that Rust captures all lifetimes in the if let. This is normally to prevent some unsound behavior, but here it works against us. To solve this, you need to release the lock before the if let.

let v = Mutex::new(vec![1, 2, 3]);
let option_element = v.lock().unwrap().pop();
// ^^^ the guard is dropped here
if let Some(element) = option_element {
    // Do something useful with `element`.
    // The lock is no longer active here
}

Mutexes in Embassy

Now that we have discussed mutexes in Rust, it is time to look at the mutexes in Embassy. The standard library is however not available in an embedded environment, so Embassy needs to provide its own mutexes. Embassy has defined its own set of mutexes in order to accommodate different needs and constraints in an embedded setting.

Embassy defines an async Mutex that instead of blocking, can be awaited. This has the advantage that other tasks may make progress while we wait for the mutex to become available. To make a mutex work, there needs to be some mechanism to communicate between different threads of execution. These communication mechanisms are mostly internal to the implementation of a mutex, but Embassy provides a way to specify what guarantees need to be made. Upon specifying the type of a mutex in Embassy, you need to select a RawMutex, that needs to be passed as a generic parameter. Here follows a list of the most important RawMutexes:

  • NoopRawMutex: No special underlying synchronization. Most basic, but only valid when sharing data between tasks in the same executor, and there is only one core of the device you are programming.
  • CriticalSectionMutex: Turns off certain processor features like interrupts while acquiring the lock. Useful when sharing data across different executors.
  • ThreadModeMutex: Sharing singleton values between tasks on the same executor.

Further reading