embassy_sync/blocking_mutex/
raw.rs

1//! Mutex primitives.
2//!
3//! This module provides a trait for mutexes that can be used in different contexts.
4use core::marker::PhantomData;
5
6/// Raw mutex trait.
7///
8/// This mutex is "raw", which means it does not actually contain the protected data, it
9/// just implements the mutex mechanism. For most uses you should use [`super::Mutex`] instead,
10/// which is generic over a RawMutex and contains the protected data.
11///
12/// Note that, unlike other mutexes, implementations only guarantee no
13/// concurrent access from other threads: concurrent access from the current
14/// thread is allowed. For example, it's possible to lock the same mutex multiple times reentrantly.
15///
16/// Therefore, locking a `RawMutex` is only enough to guarantee safe shared (`&`) access
17/// to the data, it is not enough to guarantee exclusive (`&mut`) access.
18///
19/// # Safety
20///
21/// RawMutex implementations must ensure that, while locked, no other thread can lock
22/// the RawMutex concurrently.
23///
24/// Unsafe code is allowed to rely on this fact, so incorrect implementations will cause undefined behavior.
25pub unsafe trait RawMutex {
26    /// Create a new `RawMutex` instance.
27    ///
28    /// This is a const instead of a method to allow creating instances in const context.
29    const INIT: Self;
30
31    /// Lock this `RawMutex`.
32    fn lock<R>(&self, f: impl FnOnce() -> R) -> R;
33}
34
35/// A mutex that allows borrowing data across executors and interrupts.
36///
37/// # Safety
38///
39/// This mutex is safe to share between different executors and interrupts.
40pub struct CriticalSectionRawMutex {
41    _phantom: PhantomData<()>,
42}
43unsafe impl Send for CriticalSectionRawMutex {}
44unsafe impl Sync for CriticalSectionRawMutex {}
45
46impl CriticalSectionRawMutex {
47    /// Create a new `CriticalSectionRawMutex`.
48    pub const fn new() -> Self {
49        Self { _phantom: PhantomData }
50    }
51}
52
53unsafe impl RawMutex for CriticalSectionRawMutex {
54    const INIT: Self = Self::new();
55
56    fn lock<R>(&self, f: impl FnOnce() -> R) -> R {
57        critical_section::with(|_| f())
58    }
59}
60
61// ================
62
63/// A mutex that allows borrowing data in the context of a single executor.
64///
65/// # Safety
66///
67/// **This Mutex is only safe within a single executor.**
68pub struct NoopRawMutex {
69    _phantom: PhantomData<*mut ()>,
70}
71
72unsafe impl Send for NoopRawMutex {}
73
74impl NoopRawMutex {
75    /// Create a new `NoopRawMutex`.
76    pub const fn new() -> Self {
77        Self { _phantom: PhantomData }
78    }
79}
80
81unsafe impl RawMutex for NoopRawMutex {
82    const INIT: Self = Self::new();
83    fn lock<R>(&self, f: impl FnOnce() -> R) -> R {
84        f()
85    }
86}
87
88// ================
89
90#[cfg(any(cortex_m, feature = "std"))]
91mod thread_mode {
92    use super::*;
93
94    /// A "mutex" that only allows borrowing from thread mode.
95    ///
96    /// # Safety
97    ///
98    /// **This Mutex is only safe on single-core systems.**
99    ///
100    /// On multi-core systems, a `ThreadModeRawMutex` **is not sufficient** to ensure exclusive access.
101    pub struct ThreadModeRawMutex {
102        _phantom: PhantomData<()>,
103    }
104
105    unsafe impl Send for ThreadModeRawMutex {}
106    unsafe impl Sync for ThreadModeRawMutex {}
107
108    impl ThreadModeRawMutex {
109        /// Create a new `ThreadModeRawMutex`.
110        pub const fn new() -> Self {
111            Self { _phantom: PhantomData }
112        }
113    }
114
115    unsafe impl RawMutex for ThreadModeRawMutex {
116        const INIT: Self = Self::new();
117        fn lock<R>(&self, f: impl FnOnce() -> R) -> R {
118            assert!(in_thread_mode(), "ThreadModeMutex can only be locked from thread mode.");
119
120            f()
121        }
122    }
123
124    impl Drop for ThreadModeRawMutex {
125        fn drop(&mut self) {
126            // Only allow dropping from thread mode. Dropping calls drop on the inner `T`, so
127            // `drop` needs the same guarantees as `lock`. `ThreadModeMutex<T>` is Send even if
128            // T isn't, so without this check a user could create a ThreadModeMutex in thread mode,
129            // send it to interrupt context and drop it there, which would "send" a T even if T is not Send.
130            assert!(
131                in_thread_mode(),
132                "ThreadModeMutex can only be dropped from thread mode."
133            );
134
135            // Drop of the inner `T` happens after this.
136        }
137    }
138
139    pub(crate) fn in_thread_mode() -> bool {
140        #[cfg(feature = "std")]
141        return Some("main") == std::thread::current().name();
142
143        #[cfg(not(feature = "std"))]
144        // ICSR.VECTACTIVE == 0
145        return unsafe { (0xE000ED04 as *const u32).read_volatile() } & 0x1FF == 0;
146    }
147}
148#[cfg(any(cortex_m, feature = "std"))]
149pub use thread_mode::*;
embassy_sync/blocking_mutex/raw.rs

embassy_sync/blocking_mutex/
raw.rs
