1use crate::runtime::time::TimerEntry;
2use crate::time::{error::Error, Duration, Instant};
3use crate::util::trace;
4
5use pin_project_lite::pin_project;
6use std::future::Future;
7use std::panic::Location;
8use std::pin::Pin;
9use std::task::{self, Poll};
10
11/// Waits until `deadline` is reached.
12///
13/// No work is performed while awaiting on the sleep future to complete. `Sleep`
14/// operates at millisecond granularity and should not be used for tasks that
15/// require high-resolution timers.
16///
17/// To run something regularly on a schedule, see [`interval`].
18///
19/// # Cancellation
20///
21/// Canceling a sleep instance is done by dropping the returned future. No additional
22/// cleanup work is required.
23///
24/// # Examples
25///
26/// Wait 100ms and print "100 ms have elapsed".
27///
28/// ```
29/// use tokio::time::{sleep_until, Instant, Duration};
30///
31/// #[tokio::main]
32/// async fn main() {
33/// sleep_until(Instant::now() + Duration::from_millis(100)).await;
34/// println!("100 ms have elapsed");
35/// }
36/// ```
37///
38/// See the documentation for the [`Sleep`] type for more examples.
39///
40/// # Panics
41///
42/// This function panics if there is no current timer set.
43///
44/// It can be triggered when [`Builder::enable_time`] or
45/// [`Builder::enable_all`] are not included in the builder.
46///
47/// It can also panic whenever a timer is created outside of a
48/// Tokio runtime. That is why `rt.block_on(sleep(...))` will panic,
49/// since the function is executed outside of the runtime.
50/// Whereas `rt.block_on(async {sleep(...).await})` doesn't panic.
51/// And this is because wrapping the function on an async makes it lazy,
52/// and so gets executed inside the runtime successfully without
53/// panicking.
54///
55/// [`Sleep`]: struct@crate::time::Sleep
56/// [`interval`]: crate::time::interval()
57/// [`Builder::enable_time`]: crate::runtime::Builder::enable_time
58/// [`Builder::enable_all`]: crate::runtime::Builder::enable_all
59// Alias for old name in 0.x
60#[cfg_attr(docsrs, doc(alias = "delay_until"))]
61#[track_caller]
62pub fn sleep_until(deadline: Instant) -> Sleep {
63 return Sleep::new_timeout(deadline, location:trace::caller_location());
64}
65
66/// Waits until `duration` has elapsed.
67///
68/// Equivalent to `sleep_until(Instant::now() + duration)`. An asynchronous
69/// analog to `std::thread::sleep`.
70///
71/// No work is performed while awaiting on the sleep future to complete. `Sleep`
72/// operates at millisecond granularity and should not be used for tasks that
73/// require high-resolution timers. The implementation is platform specific,
74/// and some platforms (specifically Windows) will provide timers with a
75/// larger resolution than 1 ms.
76///
77/// To run something regularly on a schedule, see [`interval`].
78///
79/// The maximum duration for a sleep is 68719476734 milliseconds (approximately 2.2 years).
80///
81/// # Cancellation
82///
83/// Canceling a sleep instance is done by dropping the returned future. No additional
84/// cleanup work is required.
85///
86/// # Examples
87///
88/// Wait 100ms and print "100 ms have elapsed".
89///
90/// ```
91/// use tokio::time::{sleep, Duration};
92///
93/// #[tokio::main]
94/// async fn main() {
95/// sleep(Duration::from_millis(100)).await;
96/// println!("100 ms have elapsed");
97/// }
98/// ```
99///
100/// See the documentation for the [`Sleep`] type for more examples.
101///
102/// # Panics
103///
104/// This function panics if there is no current timer set.
105///
106/// It can be triggered when [`Builder::enable_time`] or
107/// [`Builder::enable_all`] are not included in the builder.
108///
109/// It can also panic whenever a timer is created outside of a
110/// Tokio runtime. That is why `rt.block_on(sleep(...))` will panic,
111/// since the function is executed outside of the runtime.
112/// Whereas `rt.block_on(async {sleep(...).await})` doesn't panic.
113/// And this is because wrapping the function on an async makes it lazy,
114/// and so gets executed inside the runtime successfully without
115/// panicking.
116///
117/// [`Sleep`]: struct@crate::time::Sleep
118/// [`interval`]: crate::time::interval()
119/// [`Builder::enable_time`]: crate::runtime::Builder::enable_time
120/// [`Builder::enable_all`]: crate::runtime::Builder::enable_all
121// Alias for old name in 0.x
122#[cfg_attr(docsrs, doc(alias = "delay_for"))]
123#[cfg_attr(docsrs, doc(alias = "wait"))]
124#[track_caller]
125pub fn sleep(duration: Duration) -> Sleep {
126 let location: Option<&Location<'_>> = trace::caller_location();
127
128 match Instant::now().checked_add(duration) {
129 Some(deadline: Instant) => Sleep::new_timeout(deadline, location),
130 None => Sleep::new_timeout(deadline:Instant::far_future(), location),
131 }
132}
133
134pin_project! {
135 /// Future returned by [`sleep`](sleep) and [`sleep_until`](sleep_until).
136 ///
137 /// This type does not implement the `Unpin` trait, which means that if you
138 /// use it with [`select!`] or by calling `poll`, you have to pin it first.
139 /// If you use it with `.await`, this does not apply.
140 ///
141 /// # Examples
142 ///
143 /// Wait 100ms and print "100 ms have elapsed".
144 ///
145 /// ```
146 /// use tokio::time::{sleep, Duration};
147 ///
148 /// #[tokio::main]
149 /// async fn main() {
150 /// sleep(Duration::from_millis(100)).await;
151 /// println!("100 ms have elapsed");
152 /// }
153 /// ```
154 ///
155 /// Use with [`select!`]. Pinning the `Sleep` with [`tokio::pin!`] is
156 /// necessary when the same `Sleep` is selected on multiple times.
157 /// ```no_run
158 /// use tokio::time::{self, Duration, Instant};
159 ///
160 /// #[tokio::main]
161 /// async fn main() {
162 /// let sleep = time::sleep(Duration::from_millis(10));
163 /// tokio::pin!(sleep);
164 ///
165 /// loop {
166 /// tokio::select! {
167 /// () = &mut sleep => {
168 /// println!("timer elapsed");
169 /// sleep.as_mut().reset(Instant::now() + Duration::from_millis(50));
170 /// },
171 /// }
172 /// }
173 /// }
174 /// ```
175 /// Use in a struct with boxing. By pinning the `Sleep` with a `Box`, the
176 /// `HasSleep` struct implements `Unpin`, even though `Sleep` does not.
177 /// ```
178 /// use std::future::Future;
179 /// use std::pin::Pin;
180 /// use std::task::{Context, Poll};
181 /// use tokio::time::Sleep;
182 ///
183 /// struct HasSleep {
184 /// sleep: Pin<Box<Sleep>>,
185 /// }
186 ///
187 /// impl Future for HasSleep {
188 /// type Output = ();
189 ///
190 /// fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
191 /// self.sleep.as_mut().poll(cx)
192 /// }
193 /// }
194 /// ```
195 /// Use in a struct with pin projection. This method avoids the `Box`, but
196 /// the `HasSleep` struct will not be `Unpin` as a consequence.
197 /// ```
198 /// use std::future::Future;
199 /// use std::pin::Pin;
200 /// use std::task::{Context, Poll};
201 /// use tokio::time::Sleep;
202 /// use pin_project_lite::pin_project;
203 ///
204 /// pin_project! {
205 /// struct HasSleep {
206 /// #[pin]
207 /// sleep: Sleep,
208 /// }
209 /// }
210 ///
211 /// impl Future for HasSleep {
212 /// type Output = ();
213 ///
214 /// fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
215 /// self.project().sleep.poll(cx)
216 /// }
217 /// }
218 /// ```
219 ///
220 /// [`select!`]: ../macro.select.html
221 /// [`tokio::pin!`]: ../macro.pin.html
222 // Alias for old name in 0.2
223 #[cfg_attr(docsrs, doc(alias = "Delay"))]
224 #[derive(Debug)]
225 #[must_use = "futures do nothing unless you `.await` or poll them"]
226 pub struct Sleep {
227 inner: Inner,
228
229 // The link between the `Sleep` instance and the timer that drives it.
230 #[pin]
231 entry: TimerEntry,
232 }
233}
234
235cfg_trace! {
236 #[derive(Debug)]
237 struct Inner {
238 ctx: trace::AsyncOpTracingCtx,
239 }
240}
241
242cfg_not_trace! {
243 #[derive(Debug)]
244 struct Inner {
245 }
246}
247
248impl Sleep {
249 #[cfg_attr(not(all(tokio_unstable, feature = "tracing")), allow(unused_variables))]
250 #[track_caller]
251 pub(crate) fn new_timeout(
252 deadline: Instant,
253 location: Option<&'static Location<'static>>,
254 ) -> Sleep {
255 use crate::runtime::scheduler;
256
257 let handle = scheduler::Handle::current();
258 let entry = TimerEntry::new(&handle, deadline);
259
260 #[cfg(all(tokio_unstable, feature = "tracing"))]
261 let inner = {
262 let clock = handle.driver().clock();
263 let handle = &handle.driver().time();
264 let time_source = handle.time_source();
265 let deadline_tick = time_source.deadline_to_tick(deadline);
266 let duration = deadline_tick.saturating_sub(time_source.now(clock));
267
268 let location = location.expect("should have location if tracing");
269 let resource_span = tracing::trace_span!(
270 "runtime.resource",
271 concrete_type = "Sleep",
272 kind = "timer",
273 loc.file = location.file(),
274 loc.line = location.line(),
275 loc.col = location.column(),
276 );
277
278 let async_op_span = resource_span.in_scope(|| {
279 tracing::trace!(
280 target: "runtime::resource::state_update",
281 duration = duration,
282 duration.unit = "ms",
283 duration.op = "override",
284 );
285
286 tracing::trace_span!("runtime.resource.async_op", source = "Sleep::new_timeout")
287 });
288
289 let async_op_poll_span =
290 async_op_span.in_scope(|| tracing::trace_span!("runtime.resource.async_op.poll"));
291
292 let ctx = trace::AsyncOpTracingCtx {
293 async_op_span,
294 async_op_poll_span,
295 resource_span,
296 };
297
298 Inner { ctx }
299 };
300
301 #[cfg(not(all(tokio_unstable, feature = "tracing")))]
302 let inner = Inner {};
303
304 Sleep { inner, entry }
305 }
306
307 pub(crate) fn far_future(location: Option<&'static Location<'static>>) -> Sleep {
308 Self::new_timeout(Instant::far_future(), location)
309 }
310
311 /// Returns the instant at which the future will complete.
312 pub fn deadline(&self) -> Instant {
313 self.entry.deadline()
314 }
315
316 /// Returns `true` if `Sleep` has elapsed.
317 ///
318 /// A `Sleep` instance is elapsed when the requested duration has elapsed.
319 pub fn is_elapsed(&self) -> bool {
320 self.entry.is_elapsed()
321 }
322
323 /// Resets the `Sleep` instance to a new deadline.
324 ///
325 /// Calling this function allows changing the instant at which the `Sleep`
326 /// future completes without having to create new associated state.
327 ///
328 /// This function can be called both before and after the future has
329 /// completed.
330 ///
331 /// To call this method, you will usually combine the call with
332 /// [`Pin::as_mut`], which lets you call the method without consuming the
333 /// `Sleep` itself.
334 ///
335 /// # Example
336 ///
337 /// ```
338 /// use tokio::time::{Duration, Instant};
339 ///
340 /// # #[tokio::main(flavor = "current_thread")]
341 /// # async fn main() {
342 /// let sleep = tokio::time::sleep(Duration::from_millis(10));
343 /// tokio::pin!(sleep);
344 ///
345 /// sleep.as_mut().reset(Instant::now() + Duration::from_millis(20));
346 /// # }
347 /// ```
348 ///
349 /// See also the top-level examples.
350 ///
351 /// [`Pin::as_mut`]: fn@std::pin::Pin::as_mut
352 pub fn reset(self: Pin<&mut Self>, deadline: Instant) {
353 self.reset_inner(deadline)
354 }
355
356 /// Resets the `Sleep` instance to a new deadline without reregistering it
357 /// to be woken up.
358 ///
359 /// Calling this function allows changing the instant at which the `Sleep`
360 /// future completes without having to create new associated state and
361 /// without having it registered. This is required in e.g. the
362 /// [crate::time::Interval] where we want to reset the internal [Sleep]
363 /// without having it wake up the last task that polled it.
364 pub(crate) fn reset_without_reregister(self: Pin<&mut Self>, deadline: Instant) {
365 let mut me = self.project();
366 me.entry.as_mut().reset(deadline, false);
367 }
368
369 fn reset_inner(self: Pin<&mut Self>, deadline: Instant) {
370 let mut me = self.project();
371 me.entry.as_mut().reset(deadline, true);
372
373 #[cfg(all(tokio_unstable, feature = "tracing"))]
374 {
375 let _resource_enter = me.inner.ctx.resource_span.enter();
376 me.inner.ctx.async_op_span =
377 tracing::trace_span!("runtime.resource.async_op", source = "Sleep::reset");
378 let _async_op_enter = me.inner.ctx.async_op_span.enter();
379
380 me.inner.ctx.async_op_poll_span =
381 tracing::trace_span!("runtime.resource.async_op.poll");
382
383 let duration = {
384 let clock = me.entry.clock();
385 let time_source = me.entry.driver().time_source();
386 let now = time_source.now(clock);
387 let deadline_tick = time_source.deadline_to_tick(deadline);
388 deadline_tick.saturating_sub(now)
389 };
390
391 tracing::trace!(
392 target: "runtime::resource::state_update",
393 duration = duration,
394 duration.unit = "ms",
395 duration.op = "override",
396 );
397 }
398 }
399
400 fn poll_elapsed(self: Pin<&mut Self>, cx: &mut task::Context<'_>) -> Poll<Result<(), Error>> {
401 let me = self.project();
402
403 ready!(crate::trace::trace_leaf(cx));
404
405 // Keep track of task budget
406 #[cfg(all(tokio_unstable, feature = "tracing"))]
407 let coop = ready!(trace_poll_op!(
408 "poll_elapsed",
409 crate::runtime::coop::poll_proceed(cx),
410 ));
411
412 #[cfg(any(not(tokio_unstable), not(feature = "tracing")))]
413 let coop = ready!(crate::runtime::coop::poll_proceed(cx));
414
415 let result = me.entry.poll_elapsed(cx).map(move |r| {
416 coop.made_progress();
417 r
418 });
419
420 #[cfg(all(tokio_unstable, feature = "tracing"))]
421 return trace_poll_op!("poll_elapsed", result);
422
423 #[cfg(any(not(tokio_unstable), not(feature = "tracing")))]
424 return result;
425 }
426}
427
428impl Future for Sleep {
429 type Output = ();
430
431 // `poll_elapsed` can return an error in two cases:
432 //
433 // - AtCapacity: this is a pathological case where far too many
434 // sleep instances have been scheduled.
435 // - Shutdown: No timer has been setup, which is a mis-use error.
436 //
437 // Both cases are extremely rare, and pretty accurately fit into
438 // "logic errors", so we just panic in this case. A user couldn't
439 // really do much better if we passed the error onwards.
440 fn poll(mut self: Pin<&mut Self>, cx: &mut task::Context<'_>) -> Poll<Self::Output> {
441 #[cfg(all(tokio_unstable, feature = "tracing"))]
442 let _res_span = self.inner.ctx.resource_span.clone().entered();
443 #[cfg(all(tokio_unstable, feature = "tracing"))]
444 let _ao_span = self.inner.ctx.async_op_span.clone().entered();
445 #[cfg(all(tokio_unstable, feature = "tracing"))]
446 let _ao_poll_span = self.inner.ctx.async_op_poll_span.clone().entered();
447 match ready!(self.as_mut().poll_elapsed(cx)) {
448 Ok(()) => Poll::Ready(()),
449 Err(e) => panic!("timer error: {}", e),
450 }
451 }
452}
453