1use 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
20struct Slot<T> {
25 value: Option<T>,
26 waker: Option<Waker>,
27 closed: bool,
29}
30
31fn lock<T>(m: &Mutex<T>) -> MutexGuard<'_, T> {
32 m.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
34}
35
36#[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
49pub struct Deliver<T> {
52 slot: Arc<Mutex<Slot<T>>>,
53 sent: bool,
54}
55
56impl<T> Deliver<T> {
57 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
89pub 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 #[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#[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
138static NEXT_TOKEN: AtomicU64 = AtomicU64::new(1);
145
146pub fn next_token() -> u64 {
148 NEXT_TOKEN.fetch_add(1, Ordering::Relaxed)
149}
150
151type Callback<T> = Box<dyn FnOnce(T) + Send>;
152
153pub 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 #[must_use]
179 pub const fn new() -> Self {
180 Self {
181 slots: Mutex::new(BTreeMap::new()),
182 }
183 }
184
185 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 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 pub fn remove(&self, token: u64) -> bool {
207 lock(&self.slots).remove(&token).is_some()
208 }
209
210 pub fn contains(&self, token: u64) -> bool {
212 lock(&self.slots).contains_key(&token)
213 }
214
215 pub fn len(&self) -> usize {
217 lock(&self.slots).len()
218 }
219
220 pub fn is_empty(&self) -> bool {
222 self.len() == 0
223 }
224}
225
226pub 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
319pub 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
335pub 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#[derive(Clone, Copy, Debug, PartialEq, Eq)]
371pub enum BlockingError {
372 Panicked,
375 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#[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 #[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 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 let inner = unsafe { &mut self.get_unchecked_mut().inner };
420 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 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 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
468pub 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 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 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
527pub fn set_blocking_inline(inline: bool) {
532 BLOCKING_INLINE.store(inline, std::sync::atomic::Ordering::Release);
533}
534
535pub fn blocking_inline() -> bool {
538 cfg!(target_arch = "wasm32") || BLOCKING_INLINE.load(std::sync::atomic::Ordering::Acquire)
539}
540
541#[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#[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 const IDLE_FOR: Duration = Duration::from_secs(2);
581
582 struct State {
583 queue: VecDeque<Job>,
584 threads: usize,
586 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 pub(super) fn submit(job: Job) {
623 let p = pool();
624 let mut st = lock(&p.state);
625 st.queue.push_back(job);
626 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 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 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 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 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 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 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 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 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 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}