Struct Mutex 

pub struct Mutex<T: ?Sized> { /* private fields */ }

Mutex types and guards for mutual exclusion. A mutual exclusion primitive useful for protecting shared data.

This mutex will block threads waiting for the lock to become available. The mutex is implemented using FreeRTOS recursive mutexes, supporting priority inheritance to prevent priority inversion.

Type Parameters

• T - The type of data protected by the mutex

Examples

Basic usage

use osal_rs::os::Mutex;
 
let mutex = Mutex::new(0);
 
// Acquire the lock and modify the data
{
    let mut guard = mutex.lock().unwrap();
    *guard += 1;
}  // Lock is automatically released here

Sharing between threads

use osal_rs::os::{Mutex, Thread};
use alloc::sync::Arc;
 
let counter = Arc::new(Mutex::new(0));
let counter_clone = counter.clone();
 
let thread = Thread::new("worker", 2048, 5, move || {
    let mut guard = counter_clone.lock().unwrap();
    *guard += 1;
}).unwrap();
 
thread.start().unwrap();

Using from ISR context

use osal_rs::os::Mutex;
 
let mutex = Mutex::new(0);
 
// In an interrupt handler:
if let Ok(mut guard) = mutex.lock_from_isr() {
    *guard = 42;
}

Implementations

impl<T: ?Sized> Mutex<T>

pub fn new(data: T) -> Self

where T: Sized,

Creates a new mutex wrapping the supplied data.

The mutex is created using FreeRTOS recursive mutexes, which support priority inheritance and can be locked multiple times by the same thread.

Arguments

• data - The data to protect with the mutex

Examples

use osal_rs::os::{Mutex, MutexFn};
 
let mutex = Mutex::new(0);
let mut guard = mutex.lock().unwrap();
*guard = 42;

impl<T: ?Sized> Mutex<T>

pub fn lock_from_isr_explicit(&self) -> Result<MutexGuardFromIsr<'_, T>>

Acquires the mutex from ISR context, returning a specific ISR guard.

This is an explicit version of lock_from_isr that returns the ISR-specific guard type.

Returns

• Ok(MutexGuardFromIsr) - Lock acquired
• Err(Error::MutexLockFailed) - Failed to acquire lock

Examples

// In ISR context:
if let Ok(guard) = mutex.lock_from_isr_explicit() {
    *guard = new_value;
}

impl<T> Mutex<T>

pub fn new_arc(data: T) -> Arc<Self>

Creates a new mutex wrapped in an Arc for easy sharing between threads.

This is a convenience method equivalent to Arc::new(Mutex::new(data)).

Examples

use osal_rs::os::Mutex;
use alloc::sync::Arc;
 
let shared_data = Mutex::new_arc(0u32);
let data_clone = Arc::clone(&shared_data);
 
// Use in thread...
let thread = Thread::new("worker", 2048, 5, move || {
    let mut guard = data_clone.lock().unwrap();
    *guard += 1;
});

Trait Implementations

impl<T> Debug for Mutex<T>

where T: ?Sized,

Formats the mutex for debugging purposes.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Display for Mutex<T>

where T: ?Sized,

Formats the mutex for display purposes.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: ?Sized> Mutex<T> for Mutex<T>

fn lock(&self) -> Result<Self::Guard<'_>>

Acquires the mutex, blocking until it becomes available.

Returns a RAII guard that will automatically unlock the mutex when dropped. The guard provides access to the protected data through Deref and DerefMut.

Returns

• Ok(MutexGuard) - Successfully acquired, guard provides data access
• Err(Error::MutexLockFailed) - Failed to acquire the mutex

Examples

use osal_rs::os::{Mutex, MutexFn};
 
let mutex = Mutex::new(0);
let mut guard = mutex.lock().unwrap();
*guard += 1;
// Mutex automatically unlocked when guard goes out of scope

fn lock_from_isr(&self) -> Result<Self::GuardFromIsr<'_>>

Acquires the mutex from an ISR context.

This is the ISR-safe version of lock(). It attempts to acquire the mutex without blocking and returns an ISR-specific guard.

Returns

• Ok(MutexGuardFromIsr) - Successfully acquired, guard provides data access
• Err(Error::MutexLockFailed) - Mutex is already locked

Safety

Must only be called from ISR context.

Examples

// In interrupt handler
use osal_rs::os::{Mutex, MutexFn};
 
fn irq_handler(mutex: &Mutex<u32>) {
    if let Ok(mut guard) = mutex.lock_from_isr() {
        *guard = 42;
    }
}

fn into_inner(self) -> Result<T>

where Self: Sized, T: Sized,

Consumes the mutex and returns the inner data.

This is safe because we have unique ownership of the mutex.

Examples

use osal_rs::os::{Mutex, MutexFn};
 
let mutex = Mutex::new(5);
let value = mutex.into_inner().unwrap();
assert_eq!(value, 5);

fn get_mut(&mut self) -> &mut T

Returns a mutable reference to the inner data.

Since this takes &mut self, we know there are no other references to the data, so we can safely return a mutable reference.

Examples

use osal_rs::os::{Mutex, MutexFn};
 
let mut mutex = Mutex::new(0);
*mutex.get_mut() = 10;
assert_eq!(*mutex.get_mut(), 10);

type Guard<'a> = MutexGuard<'a, T> where Self: 'a, T: 'a

The guard type for normal mutex locks

type GuardFromIsr<'a> = MutexGuardFromIsr<'a, T> where Self: 'a, T: 'a

The guard type for ISR-context mutex locks

impl<T: ?Sized + Send> Send for Mutex<T>

impl<T: ?Sized + Send> Sync for Mutex<T>