Skip to main content

zigbee_types/
sync.rs

1//! Async signaling primitives.
2//!
3//! Runtime-agnostic: built on [`AtomicWaker`], usable from any executor.
4
5use core::future::Future;
6use core::future::poll_fn;
7use core::pin::pin;
8use core::sync::atomic::AtomicBool;
9use core::sync::atomic::Ordering;
10use core::task::Poll;
11
12use atomic_waker::AtomicWaker;
13use spin::Mutex;
14
15/// Run `fut` until it completes or `timeout` elapses first.
16///
17/// Returns `None` when `timeout` won the race.
18pub async fn with_timeout<F: Future>(
19    fut: F,
20    timeout: impl Future<Output = ()>,
21) -> Option<F::Output> {
22    let mut fut = pin!(fut);
23    let mut timeout = pin!(timeout);
24    poll_fn(move |cx| {
25        if let Poll::Ready(value) = fut.as_mut().poll(cx) {
26            return Poll::Ready(Some(value));
27        }
28        match timeout.as_mut().poll(cx) {
29            Poll::Ready(()) => Poll::Ready(None),
30            Poll::Pending => Poll::Pending,
31        }
32    })
33    .await
34}
35
36/// Hand control back to the executor once, so another task can make progress.
37///
38/// Used by yielding `try_lock` loops: a waiter releases the CPU instead of
39/// spinning while the holder finishes.
40pub async fn yield_now() {
41    let mut yielded = false;
42    poll_fn(|cx| {
43        if yielded {
44            return Poll::Ready(());
45        }
46        yielded = true;
47        cx.waker().wake_by_ref();
48        Poll::Pending
49    })
50    .await;
51}
52
53/// One-shot signal carrying a value to a single waiter.
54///
55/// The value is produced by the receive path and consumed by the procedure
56/// waiting for it; it stays available until taken, so a signal that arrives
57/// before anyone waits is not lost.
58pub struct Signal<T> {
59    value: Mutex<Option<T>>,
60    waker: AtomicWaker,
61}
62
63impl<T> Default for Signal<T> {
64    fn default() -> Self {
65        Self::new()
66    }
67}
68
69impl<T> Signal<T> {
70    /// Creates a signal holding no value.
71    pub const fn new() -> Self {
72        Self {
73            value: Mutex::new(None),
74            waker: AtomicWaker::new(),
75        }
76    }
77
78    /// Store the value and wake the waiter, replacing an unconsumed one.
79    pub fn signal(&self, value: T) {
80        *self.value.lock() = Some(value);
81        self.waker.wake();
82    }
83
84    /// Discard a pending, unconsumed value.
85    pub fn reset(&self) {
86        *self.value.lock() = None;
87    }
88
89    /// Take the value without waiting, if one is pending.
90    pub fn try_take(&self) -> Option<T> {
91        self.value.lock().take()
92    }
93
94    /// Whether a value is pending.
95    pub fn is_signaled(&self) -> bool {
96        self.value.lock().is_some()
97    }
98
99    /// Wait until signaled, consuming the value.
100    pub async fn wait(&self) -> T {
101        poll_fn(|cx| {
102            if let Some(value) = self.try_take() {
103                return Poll::Ready(value);
104            }
105            self.waker.register(cx.waker());
106            // re-check to close the race with a signal between check and
107            // register
108            match self.try_take() {
109                Some(value) => Poll::Ready(value),
110                None => Poll::Pending,
111            }
112        })
113        .await
114    }
115}
116
117/// One-shot event flag supporting a single waiter.
118#[derive(Default)]
119pub struct Event {
120    set: AtomicBool,
121    waker: AtomicWaker,
122}
123
124impl Event {
125    /// Creates an unset event.
126    pub const fn new() -> Self {
127        Self {
128            set: AtomicBool::new(false),
129            waker: AtomicWaker::new(),
130        }
131    }
132
133    /// Set the flag and wake the waiter.
134    pub fn signal(&self) {
135        self.set.store(true, Ordering::Release);
136        self.waker.wake();
137    }
138
139    /// Clear a pending, unconsumed signal.
140    pub fn reset(&self) {
141        self.set.store(false, Ordering::Release);
142    }
143
144    /// Whether the flag is currently set.
145    pub fn is_set(&self) -> bool {
146        self.set.load(Ordering::Acquire)
147    }
148
149    /// Wait until signaled, consuming the flag (edge semantics).
150    pub async fn wait(&self) {
151        poll_fn(|cx| {
152            if self.set.swap(false, Ordering::AcqRel) {
153                return Poll::Ready(());
154            }
155            self.waker.register(cx.waker());
156            // re-check to close the race with a signal between check and
157            // register
158            if self.set.swap(false, Ordering::AcqRel) {
159                return Poll::Ready(());
160            }
161            Poll::Pending
162        })
163        .await;
164    }
165
166    /// Wait until signaled, leaving the flag set (level semantics).
167    pub async fn wait_set(&self) {
168        poll_fn(|cx| {
169            if self.set.load(Ordering::Acquire) {
170                return Poll::Ready(());
171            }
172            self.waker.register(cx.waker());
173            if self.set.load(Ordering::Acquire) {
174                return Poll::Ready(());
175            }
176            Poll::Pending
177        })
178        .await;
179    }
180}
181
182#[cfg(test)]
183mod tests {
184    use core::future::Future;
185    use core::pin::pin;
186    use core::task::Context;
187    use core::task::Waker;
188
189    use super::*;
190
191    #[test]
192    fn wait_consumes_signal() {
193        let event = Event::new();
194        let mut cx = Context::from_waker(Waker::noop());
195
196        let mut wait = pin!(event.wait());
197        assert!(wait.as_mut().poll(&mut cx).is_pending());
198
199        event.signal();
200        assert!(wait.as_mut().poll(&mut cx).is_ready());
201
202        // flag consumed: next wait is pending again
203        let mut wait = pin!(event.wait());
204        assert!(wait.as_mut().poll(&mut cx).is_pending());
205    }
206
207    #[test]
208    fn signal_delivers_value_once() {
209        let signal = Signal::<u8>::new();
210        let mut cx = Context::from_waker(Waker::noop());
211
212        let mut wait = pin!(signal.wait());
213        assert!(wait.as_mut().poll(&mut cx).is_pending());
214
215        signal.signal(0x42);
216        assert_eq!(wait.as_mut().poll(&mut cx), Poll::Ready(0x42));
217
218        // value consumed: next wait is pending again
219        assert!(!signal.is_signaled());
220        assert!(pin!(signal.wait()).poll(&mut cx).is_pending());
221    }
222
223    #[test]
224    fn wait_set_leaves_flag() {
225        let event = Event::new();
226        let mut cx = Context::from_waker(Waker::noop());
227
228        event.signal();
229        assert!(pin!(event.wait_set()).poll(&mut cx).is_ready());
230        // level semantics: still set
231        assert!(pin!(event.wait_set()).poll(&mut cx).is_ready());
232    }
233}