Skip to main content

libc_rs/
sync.rs

1//! Pure-Rust futex synchronization primitives (`FutexMutex`) with zero `pthreads` dependencies.
2
3use core::cell::UnsafeCell;
4use core::ops::{Deref, DerefMut};
5use core::sync::atomic::{AtomicU32, Ordering};
6
7#[cfg(all(target_arch = "aarch64", target_os = "none"))]
8use crate::raw::{nr, syscall4, syscall6};
9use crate::time::Timespec;
10
11/// Private futex wait operation (`FUTEX_WAIT | FUTEX_PRIVATE_FLAG`).
12pub const FUTEX_WAIT_PRIVATE: i32 = 128;
13/// Private futex wake operation (`FUTEX_WAKE | FUTEX_PRIVATE_FLAG`).
14pub const FUTEX_WAKE_PRIVATE: i32 = 129;
15
16/// Waits on futex `word` while its value equals `expected`, with an optional relative `timeout`.
17pub fn futex_wait(word: &AtomicU32, expected: u32, timeout: Option<&Timespec>) {
18    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
19    {
20        let ts_ptr = timeout.map_or(0, |t| core::ptr::from_ref(t) as usize);
21        // SAFETY: `word` is a valid 4-byte aligned `AtomicU32` and `ts_ptr` is null or valid.
22        let _ = unsafe {
23            syscall6(
24                nr::FUTEX,
25                core::ptr::from_ref(word) as usize,
26                FUTEX_WAIT_PRIVATE as usize,
27                expected as usize,
28                ts_ptr,
29                0,
30                0,
31            )
32        };
33    }
34    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
35    {
36        let _ = (word, expected, timeout);
37        core::hint::spin_loop();
38    }
39}
40
41/// Wakes at most one waiter blocked on futex `word`.
42pub fn futex_wake_one(word: &AtomicU32) -> usize {
43    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
44    {
45        // SAFETY: `word` is a valid 4-byte aligned `AtomicU32`.
46        unsafe {
47            syscall4(
48                nr::FUTEX,
49                core::ptr::from_ref(word) as usize,
50                FUTEX_WAKE_PRIVATE as usize,
51                1,
52                0,
53            )
54            .unwrap_or(0)
55        }
56    }
57    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
58    {
59        let _ = word;
60        0
61    }
62}
63
64/// Wakes all waiters blocked on futex `word`.
65pub fn futex_wake_all(word: &AtomicU32) -> usize {
66    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
67    {
68        // SAFETY: `word` is a valid 4-byte aligned `AtomicU32`.
69        unsafe {
70            syscall4(
71                nr::FUTEX,
72                core::ptr::from_ref(word) as usize,
73                FUTEX_WAKE_PRIVATE as usize,
74                i32::MAX as usize,
75                0,
76            )
77            .unwrap_or(0)
78        }
79    }
80    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
81    {
82        let _ = word;
83        0
84    }
85}
86
87const UNLOCKED: u32 = 0;
88const LOCKED_UNCONTENDED: u32 = 1;
89const LOCKED_CONTENDED: u32 = 2;
90
91/// Move-safe, zero-allocation 3-state futex mutex (`0` = unlocked, `1` = locked, `2` = contended).
92pub struct FutexMutex<T: ?Sized> {
93    state: AtomicU32,
94    value: UnsafeCell<T>,
95}
96
97// SAFETY: `FutexMutex` serializes access to `T` across threads via acquire/release operations.
98unsafe impl<T: ?Sized + Send> Sync for FutexMutex<T> {}
99// SAFETY: `FutexMutex` can be sent across threads when its payload `T` is `Send`.
100unsafe impl<T: ?Sized + Send> Send for FutexMutex<T> {}
101
102impl<T> FutexMutex<T> {
103    /// Creates a new unlocked [`FutexMutex`] wrapping `value`.
104    #[must_use]
105    pub const fn new(value: T) -> Self {
106        Self {
107            state: AtomicU32::new(UNLOCKED),
108            value: UnsafeCell::new(value),
109        }
110    }
111
112    /// Consumes the mutex and returns its inner value.
113    #[must_use]
114    pub fn into_inner(self) -> T {
115        self.value.into_inner()
116    }
117}
118
119impl<T: ?Sized> FutexMutex<T> {
120    /// Attempts to acquire the mutex without blocking.
121    #[must_use]
122    pub fn try_lock(&self) -> Option<FutexMutexGuard<'_, T>> {
123        if self
124            .state
125            .compare_exchange(
126                UNLOCKED,
127                LOCKED_UNCONTENDED,
128                Ordering::Acquire,
129                Ordering::Relaxed,
130            )
131            .is_ok()
132        {
133            Some(FutexMutexGuard { mutex: self })
134        } else {
135            None
136        }
137    }
138
139    /// Acquires the mutex, spinning briefly before blocking via futex wait under contention.
140    #[must_use]
141    pub fn lock(&self) -> FutexMutexGuard<'_, T> {
142        if self
143            .state
144            .compare_exchange(
145                UNLOCKED,
146                LOCKED_UNCONTENDED,
147                Ordering::Acquire,
148                Ordering::Relaxed,
149            )
150            .is_err()
151        {
152            self.lock_contended();
153        }
154        FutexMutexGuard { mutex: self }
155    }
156
157    #[cold]
158    fn lock_contended(&self) {
159        let mut c = self.state.load(Ordering::Relaxed);
160        for _ in 0..32 {
161            if c == UNLOCKED {
162                match self.state.compare_exchange(
163                    UNLOCKED,
164                    LOCKED_UNCONTENDED,
165                    Ordering::Acquire,
166                    Ordering::Relaxed,
167                ) {
168                    Ok(_) => return,
169                    Err(prev) => c = prev,
170                }
171            }
172            if c != LOCKED_UNCONTENDED {
173                break;
174            }
175            core::hint::spin_loop();
176            c = self.state.load(Ordering::Relaxed);
177        }
178        loop {
179            if c == LOCKED_CONTENDED
180                || self
181                    .state
182                    .compare_exchange(
183                        LOCKED_UNCONTENDED,
184                        LOCKED_CONTENDED,
185                        Ordering::Relaxed,
186                        Ordering::Relaxed,
187                    )
188                    .is_err()
189            {
190                futex_wait(&self.state, LOCKED_CONTENDED, None);
191            }
192            if self.state.swap(LOCKED_CONTENDED, Ordering::Acquire) == UNLOCKED {
193                return;
194            }
195            c = LOCKED_CONTENDED;
196        }
197    }
198
199    /// Releases the mutex without a guard (used by [`FutexMutexGuard`] drop).
200    ///
201    /// # Safety
202    ///
203    /// The caller must currently hold the lock on `self` and must not access the protected
204    /// value after calling `raw_unlock` without re-acquiring the lock.
205    pub unsafe fn raw_unlock(&self) {
206        if self.state.swap(UNLOCKED, Ordering::Release) == LOCKED_CONTENDED {
207            let _ = futex_wake_one(&self.state);
208        }
209    }
210
211    /// Returns a mutable reference to the underlying data when holding exclusive `&mut self`.
212    #[must_use]
213    pub fn get_mut(&mut self) -> &mut T {
214        self.value.get_mut()
215    }
216}
217
218/// RAII guard for [`FutexMutex`].
219pub struct FutexMutexGuard<'a, T: ?Sized> {
220    mutex: &'a FutexMutex<T>,
221}
222
223impl<T: ?Sized> Deref for FutexMutexGuard<'_, T> {
224    type Target = T;
225
226    fn deref(&self) -> &Self::Target {
227        // SAFETY: The guard holds exclusive access to the mutex value.
228        unsafe { &*self.mutex.value.get() }
229    }
230}
231
232impl<T: ?Sized> DerefMut for FutexMutexGuard<'_, T> {
233    fn deref_mut(&mut self) -> &mut Self::Target {
234        // SAFETY: The guard holds exclusive mutable access to the mutex value.
235        unsafe { &mut *self.mutex.value.get() }
236    }
237}
238
239impl<T: ?Sized> Drop for FutexMutexGuard<'_, T> {
240    fn drop(&mut self) {
241        // SAFETY: `self` owns the lock and is being dropped.
242        unsafe {
243            self.mutex.raw_unlock();
244        }
245    }
246}
247
248#[cfg(test)]
249mod tests {
250    use super::*;
251
252    #[test]
253    fn futex_mutex_lock_try_lock_and_move_by_value() {
254        let m = FutexMutex::new(10u64);
255        {
256            let mut g = m.lock();
257            assert!(m.try_lock().is_none());
258            *g += 5;
259        }
260        let mut moved = m;
261        assert_eq!(*moved.get_mut(), 15);
262        *moved.try_lock().unwrap() += 27;
263        assert_eq!(moved.into_inner(), 42);
264    }
265}