Skip to main content

gpu_async_reactor/host/
std_host.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! std hosts:
4//! - [`StdClock`]: `Instant` from an origin, as the core's [`Clock`]; its [`Timer`] sleeps the
5//!   calling thread (an inline host: the future is ready on its first poll).
6//! - [`StdIdle`]: the executor's idle: `thread::sleep` to a deadline; a park on a line through
7//!   the `wordwait` backend when one was probed, else a yield loop to the bound.
8//! - [`Watcher`]: a background thread that waits on completion lines and wakes the [`Waker`]s
9//!   of futures awaiting them, for consumers on any runtime that are not latency-critical.
10
11use std::sync::{Arc, Mutex, PoisonError};
12use std::task::{Context, Poll, Waker};
13use std::thread::{self, JoinHandle};
14use std::time::{Duration, Instant};
15use std::vec::Vec;
16
17use crate::core::line::{CompletionLine, Slot, reached};
18use crate::core::reactor::Idle;
19use crate::core::time::{Clock, DurNs, MonoNs, Timer};
20
21/// The monotonic clock of the process, from an origin.
22#[derive(Clone, Copy, Debug)]
23pub struct StdClock {
24    origin: Instant,
25}
26
27impl StdClock {
28    /// A clock whose 0 is now.
29    #[must_use]
30    pub fn new() -> Self {
31        Self {
32            origin: Instant::now(),
33        }
34    }
35
36    /// A clock whose 0 is `origin`.
37    #[must_use]
38    pub fn from_origin(origin: Instant) -> Self {
39        Self { origin }
40    }
41}
42
43impl Default for StdClock {
44    fn default() -> Self {
45        Self::new()
46    }
47}
48
49impl Clock for StdClock {
50    fn monotonic_ns(&self) -> MonoNs {
51        MonoNs(u64::try_from(self.origin.elapsed().as_nanos()).unwrap_or(u64::MAX))
52    }
53}
54
55impl Timer for StdClock {
56    async fn sleep_until(&self, at: MonoNs) {
57        let left = at.since(self.monotonic_ns());
58        if left.0 > 0 {
59            thread::sleep(Duration::from_nanos(left.0));
60        }
61    }
62}
63
64/// How a [`StdIdle`] parks on a line.
65#[derive(Clone, Copy, Debug)]
66enum LinePark {
67    #[cfg(feature = "wordwait")]
68    Word(crate::backend::wordwait::WordWait),
69    Yield,
70}
71
72/// The executor's idle on a std thread.
73#[derive(Clone, Copy, Debug)]
74pub struct StdIdle {
75    clock: StdClock,
76    park: LinePark,
77}
78
79impl StdIdle {
80    /// An idle that parks through the CPU's word wait when the `wordwait` feature is on and the
81    /// CPU has one; otherwise it yields to the bound (the declared fallback, see
82    /// [`StdIdle::parks_in_hardware`]).
83    #[must_use]
84    pub fn new(clock: StdClock) -> Self {
85        #[cfg(feature = "wordwait")]
86        if let Ok(w) = crate::backend::wordwait::WordWait::probe() {
87            return Self {
88                clock,
89                park: LinePark::Word(w),
90            };
91        }
92        Self {
93            clock,
94            park: LinePark::Yield,
95        }
96    }
97
98    /// An idle that parks through `wait` (a word wait probed by the caller).
99    #[cfg(feature = "wordwait")]
100    #[must_use]
101    pub fn with_word_wait(clock: StdClock, wait: crate::backend::wordwait::WordWait) -> Self {
102        Self {
103            clock,
104            park: LinePark::Word(wait),
105        }
106    }
107
108    /// Whether a park sleeps the core in hardware (`false`: it yields the thread in a loop).
109    #[must_use]
110    pub fn parks_in_hardware(&self) -> bool {
111        !matches!(self.park, LinePark::Yield)
112    }
113}
114
115impl Idle for StdIdle {
116    fn sleep_until(&mut self, at: MonoNs) {
117        let left = at.since(self.clock.monotonic_ns());
118        if left.0 > 0 {
119            thread::sleep(Duration::from_nanos(left.0));
120        }
121    }
122
123    fn park_line<R: Fn(&CompletionLine) -> bool>(
124        &mut self,
125        line: &CompletionLine,
126        ready: R,
127        bound: DurNs,
128    ) -> bool {
129        match self.park {
130            #[cfg(feature = "wordwait")]
131            LinePark::Word(w) => w.park(line, ready, Duration::from_nanos(bound.0)),
132            LinePark::Yield => {
133                let until = Instant::now() + Duration::from_nanos(bound.0);
134                while !ready(line) {
135                    if Instant::now() >= until {
136                        return false;
137                    }
138                    thread::yield_now();
139                }
140                true
141            }
142        }
143    }
144}
145
146fn line_of<L: AsRef<CompletionLine>>(l: &Arc<L>) -> &CompletionLine {
147    (**l).as_ref()
148}
149
150struct Entry<L> {
151    line: Arc<L>,
152    slot: Slot,
153    target: u64,
154    waker: Waker,
155}
156
157struct Shared<L> {
158    entries: Mutex<Vec<Entry<L>>>,
159    stop: std::sync::atomic::AtomicBool,
160}
161
162/// A thread that watches completion lines and wakes the futures awaiting them. `L` is anything
163/// that holds a line (a backend's mapped line, an `Arc`'d plain line).
164pub struct Watcher<L: AsRef<CompletionLine> + Send + Sync + 'static> {
165    shared: Arc<Shared<L>>,
166    thread: Option<JoinHandle<()>>,
167}
168
169impl<L: AsRef<CompletionLine> + Send + Sync + 'static> Watcher<L> {
170    /// Start the watcher thread; it parks on a watched line for at most `park_bound` at a time
171    /// and sleeps (thread park) while nothing is watched.
172    #[must_use]
173    pub fn spawn(mut idle: StdIdle, park_bound: Duration) -> Self {
174        let shared = Arc::new(Shared {
175            entries: Mutex::new(Vec::new()),
176            stop: std::sync::atomic::AtomicBool::new(false),
177        });
178        let s = Arc::clone(&shared);
179        let bound = DurNs(u64::try_from(park_bound.as_nanos()).unwrap_or(u64::MAX));
180        let thread = thread::spawn(move || {
181            while !s.stop.load(std::sync::atomic::Ordering::Acquire) {
182                let first = {
183                    let mut e = s.entries.lock().unwrap_or_else(PoisonError::into_inner);
184                    e.retain(|x| {
185                        let done = reached(line_of(&x.line), x.slot, x.target);
186                        if done {
187                            x.waker.wake_by_ref();
188                        }
189                        !done
190                    });
191                    e.first().map(|x| (Arc::clone(&x.line), x.slot, x.target))
192                };
193                match first {
194                    None => thread::park(),
195                    Some((line, slot, target)) => {
196                        let _ = idle.park_line(
197                            line_of(&line),
198                            |l| reached(l, slot, target),
199                            bound,
200                        );
201                    }
202                }
203            }
204        });
205        Self {
206            shared,
207            thread: Some(thread),
208        }
209    }
210
211    /// A future that resolves once word `slot` of `line` reaches `target`.
212    #[must_use]
213    pub fn wait(&self, line: Arc<L>, slot: Slot, target: u64) -> Watch<L> {
214        Watch {
215            shared: Arc::clone(&self.shared),
216            thread: self.thread.as_ref().map(|t| t.thread().clone()),
217            line,
218            slot,
219            target,
220        }
221    }
222}
223
224impl<L: AsRef<CompletionLine> + Send + Sync + 'static> Drop for Watcher<L> {
225    fn drop(&mut self) {
226        self.shared
227            .stop
228            .store(true, std::sync::atomic::Ordering::Release);
229        if let Some(t) = self.thread.take() {
230            t.thread().unpark();
231            let _ = t.join();
232        }
233    }
234}
235
236/// The future of [`Watcher::wait`]: `Send`, usable on any runtime.
237pub struct Watch<L: AsRef<CompletionLine> + Send + Sync + 'static> {
238    shared: Arc<Shared<L>>,
239    thread: Option<thread::Thread>,
240    line: Arc<L>,
241    slot: Slot,
242    target: u64,
243}
244
245impl<L: AsRef<CompletionLine> + Send + Sync + 'static> Future for Watch<L> {
246    type Output = ();
247
248    fn poll(self: std::pin::Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
249        if reached(line_of(&self.line), self.slot, self.target) {
250            return Poll::Ready(());
251        }
252        {
253            let mut e = self
254                .shared
255                .entries
256                .lock()
257                .unwrap_or_else(PoisonError::into_inner);
258            match e
259                .iter_mut()
260                .find(|x| Arc::ptr_eq(&x.line, &self.line) && x.slot == self.slot && x.target == self.target)
261            {
262                Some(x) => x.waker.clone_from(cx.waker()),
263                None => e.push(Entry {
264                    line: Arc::clone(&self.line),
265                    slot: self.slot,
266                    target: self.target,
267                    waker: cx.waker().clone(),
268                }),
269            }
270        }
271        if let Some(t) = &self.thread {
272            t.unpark();
273        }
274        // A store between the first check and the registration is seen by the watcher's next
275        // pass; checking again here makes it immediate.
276        if reached(line_of(&self.line), self.slot, self.target) {
277            return Poll::Ready(());
278        }
279        Poll::Pending
280    }
281}