1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
use super::CriticalSection;
use core::cell::{Ref, RefCell, RefMut, UnsafeCell};

/// A mutex based on critical sections.
///
/// # Example
///
/// ```no_run
/// # use critical_section::Mutex;
/// # use std::cell::Cell;
///
/// static FOO: Mutex<Cell<i32>> = Mutex::new(Cell::new(42));
///
/// fn main() {
///     critical_section::with(|cs| {
///         FOO.borrow(cs).set(43);
///     });
/// }
///
/// fn interrupt_handler() {
///     let _x = critical_section::with(|cs| FOO.borrow(cs).get());
/// }
/// ```
///
///
/// # Design
///
/// [`std::sync::Mutex`] has two purposes. It converts types that are [`Send`]
/// but not [`Sync`] into types that are both; and it provides
/// [interior mutability]. `critical_section::Mutex`, on the other hand, only adds
/// `Sync`. It does *not* provide interior mutability.
///
/// This was a conscious design choice. It is possible to create multiple
/// [`CriticalSection`] tokens, either by nesting critical sections or `Copy`ing
/// an existing token. As a result, it would not be sound for [`Mutex::borrow`]
/// to return `&mut T`, because there would be nothing to prevent calling
/// `borrow` multiple times to create aliased `&mut T` references.
///
/// The solution is to include a runtime check to ensure that each resource is
/// borrowed only once. This is what `std::sync::Mutex` does. However, this is
/// a runtime cost that may not be required in all circumstances. For instance,
/// `Mutex<Cell<T>>` never needs to create `&mut T` or equivalent.
///
/// If `&mut T` is needed, the simplest solution is to use `Mutex<RefCell<T>>`,
/// which is the closest analogy to `std::sync::Mutex`. [`RefCell`] inserts the
/// exact runtime check necessary to guarantee that the `&mut T` reference is
/// unique.
///
/// To reduce verbosity when using `Mutex<RefCell<T>>`, we reimplement some of
/// `RefCell`'s methods on it directly.
///
/// ```no_run
/// # use critical_section::Mutex;
/// # use std::cell::RefCell;
///
/// static FOO: Mutex<RefCell<i32>> = Mutex::new(RefCell::new(42));
///
/// fn main() {
///     critical_section::with(|cs| {
///         // Instead of calling this
///         let _ = FOO.borrow(cs).take();
///         // Call this
///         let _ = FOO.take(cs);
///         // `RefCell::borrow` and `RefCell::borrow_mut` are renamed to
///         // `borrow_ref` and `borrow_ref_mut` to avoid name collisions
///         let _: &mut i32 = &mut *FOO.borrow_ref_mut(cs);
///     })
/// }
/// ```
///
/// [`std::sync::Mutex`]: https://doc.rust-lang.org/std/sync/struct.Mutex.html
/// [interior mutability]: https://doc.rust-lang.org/reference/interior-mutability.html
#[derive(Debug)]
pub struct Mutex<T> {
    inner: UnsafeCell<T>,
}

impl<T> Mutex<T> {
    /// Creates a new mutex.
    #[inline]
    pub const fn new(value: T) -> Self {
        Mutex {
            inner: UnsafeCell::new(value),
        }
    }

    /// Gets a mutable reference to the contained value when the mutex is already uniquely borrowed.
    ///
    /// This does not require locking or a critical section since it takes `&mut self`, which
    /// guarantees unique ownership already. Care must be taken when using this method to
    /// **unsafely** access `static mut` variables, appropriate fences must be used to prevent
    /// unwanted optimizations.
    #[inline]
    pub fn get_mut(&mut self) -> &mut T {
        unsafe { &mut *self.inner.get() }
    }

    /// Unwraps the contained value, consuming the mutex.
    #[inline]
    pub fn into_inner(self) -> T {
        self.inner.into_inner()
    }

    /// Borrows the data for the duration of the critical section.
    #[inline]
    pub fn borrow<'cs>(&'cs self, _cs: CriticalSection<'cs>) -> &'cs T {
        unsafe { &*self.inner.get() }
    }
}

impl<T> Mutex<RefCell<T>> {
    /// Borrow the data and call [`RefCell::replace`]
    ///
    /// This is equivalent to `self.borrow(cs).replace(t)`
    ///
    /// # Panics
    ///
    /// This call could panic. See the documentation for [`RefCell::replace`]
    /// for more details.
    #[inline]
    #[track_caller]
    pub fn replace<'cs>(&'cs self, cs: CriticalSection<'cs>, t: T) -> T {
        self.borrow(cs).replace(t)
    }

    /// Borrow the data and call [`RefCell::replace_with`]
    ///
    /// This is equivalent to `self.borrow(cs).replace_with(f)`
    ///
    /// # Panics
    ///
    /// This call could panic. See the documentation for
    /// [`RefCell::replace_with`] for more details.
    #[inline]
    #[track_caller]
    pub fn replace_with<'cs, F>(&'cs self, cs: CriticalSection<'cs>, f: F) -> T
    where
        F: FnOnce(&mut T) -> T,
    {
        self.borrow(cs).replace_with(f)
    }

    /// Borrow the data and call [`RefCell::borrow`]
    ///
    /// This is equivalent to `self.borrow(cs).borrow()`
    ///
    /// # Panics
    ///
    /// This call could panic. See the documentation for [`RefCell::borrow`]
    /// for more details.
    #[inline]
    #[track_caller]
    pub fn borrow_ref<'cs>(&'cs self, cs: CriticalSection<'cs>) -> Ref<'cs, T> {
        self.borrow(cs).borrow()
    }

    /// Borrow the data and call [`RefCell::borrow_mut`]
    ///
    /// This is equivalent to `self.borrow(cs).borrow_mut()`
    ///
    /// # Panics
    ///
    /// This call could panic. See the documentation for [`RefCell::borrow_mut`]
    /// for more details.
    #[inline]
    #[track_caller]
    pub fn borrow_ref_mut<'cs>(&'cs self, cs: CriticalSection<'cs>) -> RefMut<'cs, T> {
        self.borrow(cs).borrow_mut()
    }
}

impl<T: Default> Mutex<RefCell<T>> {
    /// Borrow the data and call [`RefCell::take`]
    ///
    /// This is equivalent to `self.borrow(cs).take()`
    ///
    /// # Panics
    ///
    /// This call could panic. See the documentation for [`RefCell::take`]
    /// for more details.
    #[inline]
    #[track_caller]
    pub fn take<'cs>(&'cs self, cs: CriticalSection<'cs>) -> T {
        self.borrow(cs).take()
    }
}

// NOTE A `Mutex` can be used as a channel so the protected data must be `Send`
// to prevent sending non-Sendable stuff (e.g. access tokens) across different
// threads.
unsafe impl<T> Sync for Mutex<T> where T: Send {}

/// ``` compile_fail
/// fn bad(cs: critical_section::CriticalSection) -> &u32 {
///     let x = critical_section::Mutex::new(42u32);
///     x.borrow(cs)
/// }
/// ```
#[cfg(doctest)]
const BorrowMustNotOutliveMutexTest: () = ();