backon/
sleep.rs

1use core::future::Future;
2use core::future::Ready;
3use core::time::Duration;
4
5/// A sleeper is used to generate a future that completes after a specified duration.
6pub trait Sleeper: 'static {
7    /// The future returned by the `sleep` method.
8    type Sleep: Future;
9
10    /// Create a future that completes after a set period.
11    fn sleep(&self, dur: Duration) -> Self::Sleep;
12}
13
14/// A stub trait allowing non-[`Sleeper`] types to be used as a generic parameter in [`Retry`][crate::Retry].
15/// It does not provide actual functionality.
16#[doc(hidden)]
17pub trait MaybeSleeper: 'static {
18    type Sleep: Future;
19}
20
21/// All `Sleeper` will implement  `MaybeSleeper`, but not vice versa.
22impl<T: Sleeper + ?Sized> MaybeSleeper for T {
23    type Sleep = <T as Sleeper>::Sleep;
24}
25
26/// All `Fn(Duration) -> impl Future` implements `Sleeper`.
27impl<F: Fn(Duration) -> Fut + 'static, Fut: Future> Sleeper for F {
28    type Sleep = Fut;
29
30    fn sleep(&self, dur: Duration) -> Self::Sleep {
31        self(dur)
32    }
33}
34
35/// The default implementation of `Sleeper` when no features are enabled.
36///
37/// It will fail to compile if a containing [`Retry`][crate::Retry] is `.await`ed without calling [`Retry::sleep`][crate::Retry::sleep] to provide a valid sleeper.
38#[cfg(all(not(feature = "tokio-sleep"), not(feature = "gloo-timers-sleep"),))]
39pub type DefaultSleeper = PleaseEnableAFeatureOrProvideACustomSleeper;
40/// The default implementation of `Sleeper` while feature `tokio-sleep` enabled.
41///
42/// it uses `tokio::time::sleep`.
43#[cfg(all(not(target_arch = "wasm32"), feature = "tokio-sleep"))]
44pub type DefaultSleeper = TokioSleeper;
45/// The default implementation of `Sleeper` while feature `gloo-timers-sleep` enabled.
46///
47/// It uses `gloo_timers::sleep::sleep`.
48#[cfg(all(target_arch = "wasm32", feature = "gloo-timers-sleep"))]
49pub type DefaultSleeper = GlooTimersSleep;
50
51/// A placeholder type that does not implement [`Sleeper`] and will therefore fail to compile if used as one.
52///
53/// Users should enable a feature of this crate that provides a valid [`Sleeper`] implementation when this type appears in compilation errors. Alternatively, a custom [`Sleeper`] implementation should be provided where necessary, such as in [`crate::Retry::sleeper`].
54#[doc(hidden)]
55#[allow(dead_code)]
56#[derive(Clone, Copy, Debug, Default)]
57pub struct PleaseEnableAFeatureOrProvideACustomSleeper;
58
59/// Implement `MaybeSleeper` but not `Sleeper`.
60impl MaybeSleeper for PleaseEnableAFeatureOrProvideACustomSleeper {
61    type Sleep = Ready<()>;
62}
63
64/// The default implementation of `Sleeper` uses `tokio::time::sleep`.
65///
66/// It will adhere to [pausing/auto-advancing](https://docs.rs/tokio/latest/tokio/time/fn.pause.html)
67/// in Tokio's Runtime semantics, if enabled.
68#[cfg(all(not(target_arch = "wasm32"), feature = "tokio-sleep"))]
69#[derive(Clone, Copy, Debug, Default)]
70pub struct TokioSleeper;
71
72#[cfg(all(not(target_arch = "wasm32"), feature = "tokio-sleep"))]
73impl Sleeper for TokioSleeper {
74    type Sleep = tokio::time::Sleep;
75
76    fn sleep(&self, dur: Duration) -> Self::Sleep {
77        tokio::time::sleep(dur)
78    }
79}
80
81/// The implementation of `Sleeper` that uses `futures_timer::Delay`.
82///
83/// This implementation is based on
84/// the [`futures-timer`](https://docs.rs/futures-timer/latest/futures_timer/) crate.
85/// It is async runtime agnostic and will also work in WASM environments.
86#[cfg(feature = "futures-timer-sleep")]
87#[derive(Clone, Copy, Debug, Default)]
88pub struct FuturesTimerSleeper;
89
90#[cfg(feature = "futures-timer-sleep")]
91impl Sleeper for FuturesTimerSleeper {
92    type Sleep = futures_timer::Delay;
93
94    fn sleep(&self, dur: Duration) -> Self::Sleep {
95        futures_timer::Delay::new(dur)
96    }
97}
98
99/// The default implementation of `Sleeper` utilizes `gloo_timers::future::sleep`.
100#[cfg(all(target_arch = "wasm32", feature = "gloo-timers-sleep"))]
101#[derive(Clone, Copy, Debug, Default)]
102pub struct GlooTimersSleep;
103
104#[cfg(all(target_arch = "wasm32", feature = "gloo-timers-sleep"))]
105impl Sleeper for GlooTimersSleep {
106    type Sleep = gloo_timers::future::TimeoutFuture;
107
108    fn sleep(&self, dur: Duration) -> Self::Sleep {
109        gloo_timers::future::sleep(dur)
110    }
111}
backon/sleep.rs

backon/
sleep.rs
