Skip to main content

day_async/
lib.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! day-async: the std-only async support parts (docs/async.md).
5//!
6//! Day runs futures on its own main-loop executor (`day::task`) and never brings in an async
7//! runtime. What a part needs beside that executor is small and was, until this crate, written
8//! once per part: a **oneshot** future that a completion arriving on any thread resolves, and a
9//! **token registry** that hands a platform a plain number and looks the waiting closure up when
10//! the number comes back. Both live here, with the locking rules the copies converged on:
11//! deliver outside the lock, and treat an unknown token as a no-op.
12
13use std::collections::BTreeMap;
14use std::future::Future;
15use std::pin::Pin;
16use std::sync::atomic::{AtomicU64, Ordering};
17use std::sync::{Arc, Mutex, MutexGuard};
18use std::task::{Context, Poll, Waker};
19
20// ---------------------------------------------------------------------------
21// Oneshot
22// ---------------------------------------------------------------------------
23
24struct Slot<T> {
25    value: Option<T>,
26    waker: Option<Waker>,
27    /// The sender is gone (delivered or dropped); with `value` empty that is [`Dropped`].
28    closed: bool,
29}
30
31fn lock<T>(m: &Mutex<T>) -> MutexGuard<'_, T> {
32    // A poisoned slot holds nothing a later poll could misread: the flags below are set last.
33    m.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
34}
35
36/// The sending half went away without delivering. A [`Oneshot`] resolves to this rather than
37/// pending forever, so a completion that never comes is an error the caller sees.
38#[derive(Clone, Copy, Debug, PartialEq, Eq)]
39pub struct Dropped;
40
41impl std::fmt::Display for Dropped {
42    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
43        f.write_str("the completion was dropped before it delivered")
44    }
45}
46
47impl std::error::Error for Dropped {}
48
49/// The sending half of a [`oneshot`]. `Send` whenever `T` is, so a platform's completion thread
50/// can hold it; delivering wakes the receiver outside the lock.
51pub struct Deliver<T> {
52    slot: Arc<Mutex<Slot<T>>>,
53    sent: bool,
54}
55
56impl<T> Deliver<T> {
57    /// Resolve the receiver with `value`. A second delivery is impossible by construction: this
58    /// consumes the sender.
59    pub fn send(mut self, value: T) {
60        self.sent = true;
61        let waker = {
62            let mut s = lock(&self.slot);
63            s.value = Some(value);
64            s.closed = true;
65            s.waker.take()
66        };
67        if let Some(w) = waker {
68            w.wake();
69        }
70    }
71}
72
73impl<T> Drop for Deliver<T> {
74    fn drop(&mut self) {
75        if self.sent {
76            return;
77        }
78        let waker = {
79            let mut s = lock(&self.slot);
80            s.closed = true;
81            s.waker.take()
82        };
83        if let Some(w) = waker {
84            w.wake();
85        }
86    }
87}
88
89/// The receiving half of a [`oneshot`]: a future resolving to the delivered value, or to
90/// [`Dropped`] when the sender went away first. Awaitable from any executor: `day::task`, or a
91/// test's park/unpark `block_on`.
92pub struct Oneshot<T> {
93    slot: Arc<Mutex<Slot<T>>>,
94}
95
96impl<T> Future for Oneshot<T> {
97    type Output = Result<T, Dropped>;
98
99    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
100        let mut s = lock(&self.slot);
101        if let Some(v) = s.value.take() {
102            return Poll::Ready(Ok(v));
103        }
104        if s.closed {
105            return Poll::Ready(Err(Dropped));
106        }
107        s.waker = Some(cx.waker().clone());
108        Poll::Pending
109    }
110}
111
112impl<T> Oneshot<T> {
113    /// Whether a value has arrived (or the sender is gone), without consuming it.
114    #[must_use]
115    pub fn is_ready(&self) -> bool {
116        let s = lock(&self.slot);
117        s.value.is_some() || s.closed
118    }
119}
120
121/// A single-value channel between one completion and one future.
122#[must_use]
123pub fn oneshot<T>() -> (Deliver<T>, Oneshot<T>) {
124    let slot = Arc::new(Mutex::new(Slot {
125        value: None,
126        waker: None,
127        closed: false,
128    }));
129    (
130        Deliver {
131            slot: slot.clone(),
132            sent: false,
133        },
134        Oneshot { slot },
135    )
136}
137
138// ---------------------------------------------------------------------------
139// Token registry
140// ---------------------------------------------------------------------------
141
142/// The process-wide token counter, shared by every registry so a token identifies one waiting
143/// closure anywhere in the process. Starts at 1: zero is "no token" in every foreign spelling.
144static NEXT_TOKEN: AtomicU64 = AtomicU64::new(1);
145
146/// A fresh token, never reused for the life of the process.
147pub fn next_token() -> u64 {
148    NEXT_TOKEN.fetch_add(1, Ordering::Relaxed)
149}
150
151type Callback<T> = Box<dyn FnOnce(T) + Send>;
152
153/// Waiting closures keyed by token: the shape behind every platform completion that crosses
154/// an FFI boundary as a number (docs/bridge.md "Callbacks").
155///
156/// Rules that make it safe to hand a token to code in another language:
157///
158/// - **Register before the call goes out.** A platform may complete synchronously, or fail
159///   before returning; a slot that exists first is found either way.
160/// - **An unknown token is a no-op.** A late, duplicate, or cancelled completion finds nothing
161///   and does nothing.
162/// - **Deliver outside the lock.** The closure may register a new token or drop a handle; the
163///   registry is never held while it runs.
164///
165/// `const`-constructible, so a generated `static` can own one per declaration.
166pub struct TokenRegistry<T> {
167    slots: Mutex<BTreeMap<u64, Callback<T>>>,
168}
169
170impl<T> Default for TokenRegistry<T> {
171    fn default() -> Self {
172        Self::new()
173    }
174}
175
176impl<T> TokenRegistry<T> {
177    /// An empty registry.
178    #[must_use]
179    pub const fn new() -> Self {
180        Self {
181            slots: Mutex::new(BTreeMap::new()),
182        }
183    }
184
185    /// Store `cb` under a fresh token.
186    pub fn insert(&self, cb: impl FnOnce(T) + Send + 'static) -> u64 {
187        let token = next_token();
188        lock(&self.slots).insert(token, Box::new(cb));
189        token
190    }
191
192    /// Remove the closure for `token` and run it with `value`. `false` when no closure waits
193    /// under that token (completed, cancelled, or never registered).
194    pub fn complete(&self, token: u64, value: T) -> bool {
195        let cb = lock(&self.slots).remove(&token);
196        match cb {
197            Some(cb) => {
198                cb(value);
199                true
200            }
201            None => false,
202        }
203    }
204
205    /// Forget `token` without running its closure: the waiting side gave up.
206    pub fn remove(&self, token: u64) -> bool {
207        lock(&self.slots).remove(&token).is_some()
208    }
209
210    /// Whether a closure still waits under `token`.
211    pub fn contains(&self, token: u64) -> bool {
212        lock(&self.slots).contains_key(&token)
213    }
214
215    /// How many closures wait, for tests and diagnostics.
216    pub fn len(&self) -> usize {
217        lock(&self.slots).len()
218    }
219
220    /// Whether nothing waits.
221    pub fn is_empty(&self) -> bool {
222        self.len() == 0
223    }
224}
225
226// ---------------------------------------------------------------------------
227// Timers
228// ---------------------------------------------------------------------------
229
230/// A scheduled timer, for [`unschedule`].
231pub type TimerId = u64;
232
233#[cfg(not(target_arch = "wasm32"))]
234mod timer_thread {
235    use std::cmp::Reverse;
236    use std::collections::{BinaryHeap, HashMap};
237    use std::sync::{Condvar, Mutex, OnceLock};
238    use std::time::{Duration, Instant};
239
240    use super::{TimerId, lock};
241
242    type Job = Box<dyn FnOnce() + Send>;
243
244    struct State {
245        heap: BinaryHeap<Reverse<(Instant, TimerId)>>,
246        jobs: HashMap<TimerId, Job>,
247        next: TimerId,
248        started: bool,
249    }
250
251    struct Timers {
252        state: Mutex<State>,
253        wake: Condvar,
254    }
255
256    fn timers() -> &'static Timers {
257        static TIMERS: OnceLock<Timers> = OnceLock::new();
258        TIMERS.get_or_init(|| Timers {
259            state: Mutex::new(State {
260                heap: BinaryHeap::new(),
261                jobs: HashMap::new(),
262                next: 0,
263                started: false,
264            }),
265            wake: Condvar::new(),
266        })
267    }
268
269    pub(super) fn schedule(delay: Duration, job: impl FnOnce() + Send + 'static) -> TimerId {
270        let t = timers();
271        let mut st = lock(&t.state);
272        st.next += 1;
273        let id = st.next;
274        st.heap.push(Reverse((Instant::now() + delay, id)));
275        st.jobs.insert(id, Box::new(job));
276        if !st.started {
277            st.started = std::thread::Builder::new()
278                .name("day-timers".into())
279                .spawn(run)
280                .is_ok();
281        }
282        t.wake.notify_one();
283        id
284    }
285
286    pub(super) fn unschedule(id: TimerId) {
287        lock(&timers().state).jobs.remove(&id);
288    }
289
290    fn run() {
291        let t = timers();
292        let mut st = lock(&t.state);
293        loop {
294            let Some(Reverse((at, id))) = st.heap.peek().copied() else {
295                st = t
296                    .wake
297                    .wait(st)
298                    .unwrap_or_else(std::sync::PoisonError::into_inner);
299                continue;
300            };
301            let now = Instant::now();
302            if at > now {
303                st = t
304                    .wake
305                    .wait_timeout(st, at - now)
306                    .map_or_else(|p| p.into_inner().0, |(g, _)| g);
307                continue;
308            }
309            st.heap.pop();
310            if let Some(job) = st.jobs.remove(&id) {
311                drop(st);
312                job();
313                st = lock(&t.state);
314            }
315        }
316    }
317}
318
319/// Run `job` after `delay` on the process's one timer thread, which starts with the first
320/// timer. Parts use it for limits and backoff instead of parking a thread per wait. Jobs run one
321/// at a time, so a job should hand longer work elsewhere. The browser has no threads: there a
322/// timer never fires, and web code keeps its own clock.
323pub fn schedule(delay: std::time::Duration, job: impl FnOnce() + Send + 'static) -> TimerId {
324    #[cfg(not(target_arch = "wasm32"))]
325    {
326        timer_thread::schedule(delay, job)
327    }
328    #[cfg(target_arch = "wasm32")]
329    {
330        let _ = (delay, job);
331        0
332    }
333}
334
335/// Forget a timer that has not fired. A timer that already fired, or an unknown id, is a no-op.
336pub fn unschedule(id: TimerId) {
337    #[cfg(not(target_arch = "wasm32"))]
338    timer_thread::unschedule(id);
339    #[cfg(target_arch = "wasm32")]
340    let _ = id;
341}
342
343#[cfg(all(test, not(target_arch = "wasm32")))]
344mod timer_tests {
345    use std::sync::mpsc;
346    use std::time::{Duration, Instant};
347
348    #[test]
349    fn timers_fire_in_order_and_unscheduled_ones_never_do() {
350        let (tx, rx) = mpsc::channel();
351        let start = Instant::now();
352        let second = tx.clone();
353        let never = tx.clone();
354        super::schedule(Duration::from_millis(60), move || second.send(2).unwrap());
355        super::schedule(Duration::from_millis(20), move || tx.send(1).unwrap());
356        let dropped = super::schedule(Duration::from_millis(40), move || never.send(9).unwrap());
357        super::unschedule(dropped);
358        assert_eq!(rx.recv_timeout(Duration::from_secs(2)), Ok(1));
359        assert_eq!(rx.recv_timeout(Duration::from_secs(2)), Ok(2));
360        assert!(rx.recv_timeout(Duration::from_millis(100)).is_err());
361        assert!(start.elapsed() >= Duration::from_millis(60));
362    }
363}
364
365// ---------------------------------------------------------------------------
366// Blocking pool
367// ---------------------------------------------------------------------------
368
369/// Why a [`Blocking`] future resolved without its job's value.
370#[derive(Clone, Copy, Debug, PartialEq, Eq)]
371pub enum BlockingError {
372    /// The job panicked. The panic went to the panic hook like any other; the pool thread that
373    /// ran it carries on with the next job.
374    Panicked,
375    /// The job never ran: the pool could not start its first thread.
376    Closed,
377}
378
379impl std::fmt::Display for BlockingError {
380    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
381        f.write_str(match self {
382            BlockingError::Panicked => "the blocking job panicked",
383            BlockingError::Closed => "the blocking job never ran: no pool thread could start",
384        })
385    }
386}
387
388impl std::error::Error for BlockingError {}
389
390/// The future [`spawn_blocking`] returns: the job's value once a pool thread has run it.
391///
392/// Dropping it before the job starts cancels the job, which then never runs. Dropping it while
393/// the job runs lets the job finish on its thread and discards the value: a blocking call has no
394/// way to be interrupted. [`Blocking::detach`] keeps the job without the value. Awaitable from
395/// any executor, `day::task` included.
396#[must_use = "await the future to receive the job's value, or `detach` it"]
397pub struct Blocking<T> {
398    inner: BlockingInner<T>,
399}
400
401enum BlockingInner<T> {
402    /// Queued for the pool; the value arrives through the oneshot.
403    #[cfg(not(target_arch = "wasm32"))]
404    Pooled {
405        receiver: Oneshot<Result<T, BlockingError>>,
406        cancelled: Arc<std::sync::atomic::AtomicBool>,
407        detached: bool,
408    },
409    /// No thread will run it (the web, or a synchronous test harness): it runs at the first
410    /// poll, on the polling thread. `Send` so the future is, like the pooled one.
411    Inline(Option<Box<dyn FnOnce() -> T + Send>>),
412}
413
414impl<T> Future for Blocking<T> {
415    type Output = Result<T, BlockingError>;
416
417    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
418        // SAFETY: `inner` is never moved out of the pinned future; the oneshot is `Unpin`.
419        let inner = unsafe { &mut self.get_unchecked_mut().inner };
420        // An inline job needs no waker: it is ready at this poll.
421        let _ = &cx;
422        match inner {
423            #[cfg(not(target_arch = "wasm32"))]
424            BlockingInner::Pooled { receiver, .. } => Pin::new(receiver)
425                .poll(cx)
426                .map(|r| r.unwrap_or(Err(BlockingError::Closed))),
427            // `catch_unwind` is a plain call under the web's abort-on-panic; it does its job on
428            // the targets that unwind.
429            BlockingInner::Inline(job) => Poll::Ready(match job.take() {
430                Some(job) => std::panic::catch_unwind(std::panic::AssertUnwindSafe(job))
431                    .map_err(|_| BlockingError::Panicked),
432                None => Err(BlockingError::Closed),
433            }),
434        }
435    }
436}
437
438impl<T> Blocking<T> {
439    /// Let the job run to completion without waiting for its value: for work whose effect is
440    /// its own completion callback. A pooled job keeps its queue slot; an inline one runs now.
441    pub fn detach(mut self) {
442        match &mut self.inner {
443            #[cfg(not(target_arch = "wasm32"))]
444            BlockingInner::Pooled { detached, .. } => *detached = true,
445            BlockingInner::Inline(job) => {
446                if let Some(job) = job.take() {
447                    let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(job));
448                }
449            }
450        }
451    }
452}
453
454#[cfg(not(target_arch = "wasm32"))]
455impl<T> Drop for Blocking<T> {
456    fn drop(&mut self) {
457        if let BlockingInner::Pooled {
458            cancelled,
459            detached: false,
460            ..
461        } = &self.inner
462        {
463            cancelled.store(true, std::sync::atomic::Ordering::Release);
464        }
465    }
466}
467
468/// Run `job` on a pool thread and resolve to its value on the awaiting side.
469///
470/// The one bridge from an `async` flow to a call that blocks or computes for a while: a file
471/// read, a parse, a hash, a database open, a `block_on` into some other runtime. The pool is
472/// process-wide, starts with the first job, holds at most [`blocking_limit`] threads, and lets a
473/// thread go after a few idle seconds; jobs beyond the limit queue in order. Nothing here knows
474/// about Day's executor, so a part can await it under `day::task` or a test's `block_on` alike.
475///
476/// On the web, where no thread exists, the job runs inline at the future's first poll. Keep
477/// web jobs short, or branch on `cfg!(target_arch = "wasm32")` and use the platform's async API.
478/// A synchronous test harness (the mock toolkit) asks for the same with
479/// [`set_blocking_inline`].
480///
481/// ```ignore
482/// let bytes = day::spawn_blocking(move || std::fs::read(&path)).await;
483/// match bytes {
484///     Ok(Ok(bytes)) => contents.set(bytes),
485///     Ok(Err(io)) => status.set(io.to_string()),
486///     Err(e) => status.set(e.to_string()),
487/// }
488/// ```
489pub fn spawn_blocking<T: Send + 'static>(job: impl FnOnce() -> T + Send + 'static) -> Blocking<T> {
490    if blocking_inline() {
491        return Blocking {
492            inner: BlockingInner::Inline(Some(Box::new(job))),
493        };
494    }
495    #[cfg(not(target_arch = "wasm32"))]
496    {
497        use std::sync::atomic::{AtomicBool, Ordering};
498        let (tx, rx) = oneshot();
499        let cancelled = Arc::new(AtomicBool::new(false));
500        let flag = cancelled.clone();
501        let run = move || {
502            // The awaiting side is gone: skip the work. (Dropping `tx` here is unobserved.)
503            if flag.load(Ordering::Acquire) {
504                return;
505            }
506            let out = std::panic::catch_unwind(std::panic::AssertUnwindSafe(job));
507            tx.send(out.map_err(|_| BlockingError::Panicked));
508        };
509        // A refused job drops its `tx` with the box, so the receiver resolves to `Closed`.
510        blocking_pool::submit(Box::new(run));
511        Blocking {
512            inner: BlockingInner::Pooled {
513                receiver: rx,
514                cancelled,
515                detached: false,
516            },
517        }
518    }
519    #[cfg(target_arch = "wasm32")]
520    {
521        unreachable!("the web always runs blocking jobs inline")
522    }
523}
524
525static BLOCKING_INLINE: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
526
527/// Make every later [`spawn_blocking`] run its job inline at the first poll, as the web does,
528/// instead of on a pool thread. For a synchronous test harness whose main-loop posts run on
529/// the calling thread (the mock toolkit), where a wake from a pool thread would have no loop
530/// to land on. Process-wide; the web ignores it (always inline).
531pub fn set_blocking_inline(inline: bool) {
532    BLOCKING_INLINE.store(inline, std::sync::atomic::Ordering::Release);
533}
534
535/// Whether [`spawn_blocking`] runs jobs inline: always on the web, else per
536/// [`set_blocking_inline`].
537pub fn blocking_inline() -> bool {
538    cfg!(target_arch = "wasm32") || BLOCKING_INLINE.load(std::sync::atomic::Ordering::Acquire)
539}
540
541/// How many threads the blocking pool may hold at once: the machine's parallelism, at least
542/// four (a job waiting behind three slow ones still gets a thread), at most thirty-two. Zero on
543/// the web, where jobs run inline.
544#[must_use]
545pub fn blocking_limit() -> usize {
546    #[cfg(not(target_arch = "wasm32"))]
547    {
548        blocking_pool::limit()
549    }
550    #[cfg(target_arch = "wasm32")]
551    {
552        0
553    }
554}
555
556/// How many pool threads exist right now, idle ones included: for diagnostics and tests.
557#[must_use]
558pub fn blocking_threads() -> usize {
559    #[cfg(not(target_arch = "wasm32"))]
560    {
561        blocking_pool::threads()
562    }
563    #[cfg(target_arch = "wasm32")]
564    {
565        0
566    }
567}
568
569#[cfg(not(target_arch = "wasm32"))]
570mod blocking_pool {
571    use std::collections::VecDeque;
572    use std::sync::{Condvar, Mutex, OnceLock};
573    use std::time::Duration;
574
575    use super::lock;
576
577    type Job = Box<dyn FnOnce() + Send>;
578
579    /// How long a thread with nothing to do waits for a job before it exits.
580    const IDLE_FOR: Duration = Duration::from_secs(2);
581
582    struct State {
583        queue: VecDeque<Job>,
584        /// Threads alive, working or waiting.
585        threads: usize,
586        /// Threads waiting on `wake`.
587        idle: usize,
588    }
589
590    struct Pool {
591        state: Mutex<State>,
592        wake: Condvar,
593        limit: usize,
594    }
595
596    fn pool() -> &'static Pool {
597        static POOL: OnceLock<Pool> = OnceLock::new();
598        POOL.get_or_init(|| Pool {
599            state: Mutex::new(State {
600                queue: VecDeque::new(),
601                threads: 0,
602                idle: 0,
603            }),
604            wake: Condvar::new(),
605            limit: std::thread::available_parallelism()
606                .map_or(4, std::num::NonZero::get)
607                .clamp(4, 32),
608        })
609    }
610
611    pub(super) fn limit() -> usize {
612        pool().limit
613    }
614
615    pub(super) fn threads() -> usize {
616        lock(&pool().state).threads
617    }
618
619    /// Queue `job`; start a thread when no idle one will take it and the limit allows. A job
620    /// that no thread can ever run (the first thread failed to start) is dropped, which drops
621    /// its delivery.
622    pub(super) fn submit(job: Job) {
623        let p = pool();
624        let mut st = lock(&p.state);
625        st.queue.push_back(job);
626        // A wake lost to a race costs latency, not the job: a woken thread drains the queue
627        // before it waits again, and the spawn below covers the queue outgrowing the waiters.
628        if st.queue.len() > st.idle && st.threads < p.limit {
629            match std::thread::Builder::new()
630                .name("day-blocking".into())
631                .spawn(worker)
632            {
633                Ok(_) => st.threads += 1,
634                Err(_) if st.threads == 0 => {
635                    st.queue.pop_back();
636                    return;
637                }
638                // Other threads exist; they will get to it.
639                Err(_) => {}
640            }
641        }
642        p.wake.notify_one();
643    }
644
645    fn worker() {
646        let p = pool();
647        let mut st = lock(&p.state);
648        loop {
649            while let Some(job) = st.queue.pop_front() {
650                drop(st);
651                job();
652                st = lock(&p.state);
653            }
654            st.idle += 1;
655            let (guard, waited) = p
656                .wake
657                .wait_timeout(st, IDLE_FOR)
658                .unwrap_or_else(std::sync::PoisonError::into_inner);
659            st = guard;
660            st.idle -= 1;
661            if waited.timed_out() && st.queue.is_empty() {
662                st.threads -= 1;
663                return;
664            }
665        }
666    }
667}
668
669#[cfg(all(test, not(target_arch = "wasm32")))]
670mod blocking_tests {
671    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
672    use std::sync::{Arc, mpsc};
673    use std::time::Duration;
674
675    use super::tests::block_on;
676    use super::{BlockingError, blocking_limit, blocking_threads, spawn_blocking};
677
678    /// Inline mode is process-wide and the pool is shared, so these tests take turns: one
679    /// toggling inline mode under another's thread assertion would fail it.
680    fn turn() -> std::sync::MutexGuard<'static, ()> {
681        static TURN: std::sync::Mutex<()> = std::sync::Mutex::new(());
682        TURN.lock()
683            .unwrap_or_else(std::sync::PoisonError::into_inner)
684    }
685
686    #[test]
687    fn a_job_runs_on_another_thread_and_delivers_its_value() {
688        let _turn = turn();
689        let here = std::thread::current().id();
690        let out = block_on(spawn_blocking(move || {
691            (std::thread::current().id() != here, 6 * 7)
692        }));
693        assert_eq!(out, Ok((true, 42)));
694    }
695
696    #[test]
697    fn a_panicking_job_is_an_error_and_the_pool_carries_on() {
698        let _turn = turn();
699        let out: Result<(), _> = block_on(spawn_blocking(|| panic!("job failed")));
700        assert_eq!(out, Err(BlockingError::Panicked));
701        assert_eq!(block_on(spawn_blocking(|| 1)), Ok(1));
702    }
703
704    #[test]
705    fn a_future_dropped_before_its_job_starts_cancels_the_job() {
706        let _turn = turn();
707        // Hold every pool thread so the marker job has to queue.
708        let limit = blocking_limit();
709        let (release, held) = mpsc::channel::<()>();
710        let held = Arc::new(std::sync::Mutex::new(held));
711        let started = Arc::new(AtomicUsize::new(0));
712        let holders: Vec<_> = (0..limit)
713            .map(|_| {
714                let held = held.clone();
715                let started = started.clone();
716                spawn_blocking(move || {
717                    started.fetch_add(1, Ordering::SeqCst);
718                    // One receiver, shared: each holder takes one release.
719                    let _ = held.lock().unwrap().recv();
720                })
721            })
722            .collect();
723        while started.load(Ordering::SeqCst) < limit {
724            std::thread::sleep(Duration::from_millis(1));
725        }
726        let ran = Arc::new(AtomicBool::new(false));
727        let marker = {
728            let ran = ran.clone();
729            spawn_blocking(move || ran.store(true, Ordering::SeqCst))
730        };
731        drop(marker);
732        for _ in 0..limit {
733            release.send(()).unwrap();
734        }
735        for h in holders {
736            assert_eq!(block_on(h), Ok(()));
737        }
738        // Every holder finished, so the queue behind them has drained too.
739        assert_eq!(block_on(spawn_blocking(|| ())), Ok(()));
740        assert!(!ran.load(Ordering::SeqCst), "a cancelled job ran");
741    }
742
743    #[test]
744    fn many_jobs_complete_within_the_thread_limit() {
745        let _turn = turn();
746        let limit = blocking_limit();
747        let live = Arc::new(AtomicUsize::new(0));
748        let peak = Arc::new(AtomicUsize::new(0));
749        let jobs: Vec<_> = (0..limit * 8)
750            .map(|i| {
751                let (live, peak) = (live.clone(), peak.clone());
752                spawn_blocking(move || {
753                    let now = live.fetch_add(1, Ordering::SeqCst) + 1;
754                    peak.fetch_max(now, Ordering::SeqCst);
755                    std::thread::sleep(Duration::from_millis(2));
756                    live.fetch_sub(1, Ordering::SeqCst);
757                    i
758                })
759            })
760            .collect();
761        let mut sum = 0;
762        for j in jobs {
763            sum += block_on(j).unwrap();
764        }
765        assert_eq!(sum, (0..limit * 8).sum::<usize>());
766        assert!(peak.load(Ordering::SeqCst) <= limit, "{peak:?} > {limit}");
767        assert!(blocking_threads() <= limit);
768    }
769
770    #[test]
771    fn the_future_is_send_for_a_send_value() {
772        fn assert_send<T: Send>(_: &T) {}
773        let _turn = turn();
774        let fut = spawn_blocking(|| String::from("sent"));
775        assert_send(&fut);
776        assert_eq!(block_on(fut), Ok(String::from("sent")));
777    }
778
779    #[test]
780    fn a_detached_job_still_runs() {
781        let _turn = turn();
782        let (tx, rx) = mpsc::channel();
783        spawn_blocking(move || tx.send(5).unwrap()).detach();
784        assert_eq!(rx.recv_timeout(Duration::from_secs(5)), Ok(5));
785    }
786
787    #[test]
788    fn an_inline_job_runs_at_the_first_poll_on_the_polling_thread() {
789        let _turn = turn();
790        let here = std::thread::current().id();
791        super::set_blocking_inline(true);
792        let fut = spawn_blocking(move || std::thread::current().id() == here);
793        let detached = spawn_blocking(|| ());
794        super::set_blocking_inline(false);
795        assert_eq!(block_on(fut), Ok(true));
796        detached.detach();
797    }
798
799    #[test]
800    fn idle_threads_leave_after_a_while() {
801        let _turn = turn();
802        assert_eq!(block_on(spawn_blocking(|| ())), Ok(()));
803        assert!(blocking_threads() >= 1);
804        // Other tests in this binary may keep the pool busy; wait for a quiet span.
805        let deadline = std::time::Instant::now() + Duration::from_secs(12);
806        while blocking_threads() > 0 && std::time::Instant::now() < deadline {
807            std::thread::sleep(Duration::from_millis(100));
808        }
809        assert_eq!(blocking_threads(), 0, "idle pool threads did not exit");
810    }
811}
812
813#[cfg(test)]
814mod tests {
815    use super::*;
816    use std::sync::Arc as StdArc;
817    use std::task::Wake;
818
819    /// The ~20-line park/unpark executor every part's future tests use.
820    pub(super) fn block_on<F: Future>(mut fut: F) -> F::Output {
821        struct Unpark(std::thread::Thread);
822        impl Wake for Unpark {
823            fn wake(self: StdArc<Self>) {
824                self.0.unpark();
825            }
826        }
827        let waker = Waker::from(StdArc::new(Unpark(std::thread::current())));
828        let mut cx = Context::from_waker(&waker);
829        // SAFETY: `fut` lives on this stack frame and is never moved after being pinned.
830        let mut fut = unsafe { Pin::new_unchecked(&mut fut) };
831        loop {
832            if let Poll::Ready(v) = fut.as_mut().poll(&mut cx) {
833                return v;
834            }
835            std::thread::park();
836        }
837    }
838
839    #[test]
840    fn delivers_across_a_thread() {
841        let (tx, rx) = oneshot::<u32>();
842        std::thread::spawn(move || tx.send(7));
843        assert_eq!(block_on(rx), Ok(7));
844    }
845
846    #[test]
847    fn a_dropped_sender_resolves_rather_than_hangs() {
848        let (tx, rx) = oneshot::<u32>();
849        drop(tx);
850        assert_eq!(block_on(rx), Err(Dropped));
851    }
852
853    #[test]
854    fn a_value_sent_before_the_first_poll_is_ready_at_once() {
855        let (tx, rx) = oneshot::<&str>();
856        tx.send("now");
857        assert!(rx.is_ready());
858        assert_eq!(block_on(rx), Ok("now"));
859    }
860
861    static REG: TokenRegistry<i32> = TokenRegistry::new();
862
863    #[test]
864    fn a_token_completes_exactly_once() {
865        let hits = StdArc::new(Mutex::new(Vec::new()));
866        let h = hits.clone();
867        let token = REG.insert(move |v| h.lock().unwrap().push(v));
868        assert!(REG.contains(token));
869        assert!(REG.complete(token, 1));
870        assert!(!REG.complete(token, 2), "a second completion finds nothing");
871        assert_eq!(*hits.lock().unwrap(), vec![1]);
872    }
873
874    #[test]
875    fn a_removed_token_never_runs() {
876        let token = REG.insert(|_| panic!("cancelled closures never run"));
877        assert!(REG.remove(token));
878        assert!(!REG.complete(token, 0));
879    }
880
881    #[test]
882    fn a_completion_may_register_again_from_inside_the_closure() {
883        // Would deadlock if the registry were held while the closure runs.
884        let token = REG.insert(|_| {
885            let _ = REG.insert(|_| {});
886        });
887        assert!(REG.complete(token, 0));
888    }
889
890    #[test]
891    fn tokens_are_process_unique() {
892        let a = next_token();
893        let b = next_token();
894        assert!(b > a);
895        assert_ne!(a, 0);
896    }
897}