1use crate::runtime::context;
2
3use std::future::Future;
4use std::pin::Pin;
5use std::task::{Context, Poll};
6
7/// Yields execution back to the Tokio runtime.
8///
9/// A task yields by awaiting on `yield_now()`, and may resume when that future
10/// completes (with no output.) The current task will be re-added as a pending
11/// task at the _back_ of the pending queue. Any other pending tasks will be
12/// scheduled. No other waking is required for the task to continue.
13///
14/// See also the usage example in the [task module](index.html#yield_now).
15///
16/// ## Non-guarantees
17///
18/// This function may not yield all the way up to the executor if there are any
19/// special combinators above it in the call stack. For example, if a
20/// [`tokio::select!`] has another branch complete during the same poll as the
21/// `yield_now()`, then the yield is not propagated all the way up to the
22/// runtime.
23///
24/// It is generally not guaranteed that the runtime behaves like you expect it
25/// to when deciding which task to schedule next after a call to `yield_now()`.
26/// In particular, the runtime may choose to poll the task that just ran
27/// `yield_now()` again immediately without polling any other tasks first. For
28/// example, the runtime will not drive the IO driver between every poll of a
29/// task, and this could result in the runtime polling the current task again
30/// immediately even if there is another task that could make progress if that
31/// other task is waiting for a notification from the IO driver.
32///
33/// In general, changes to the order in which the runtime polls tasks is not
34/// considered a breaking change, and your program should be correct no matter
35/// which order the runtime polls your tasks in.
36///
37/// [`tokio::select!`]: macro@crate::select
38#[cfg_attr(docsrs, doc(cfg(feature = "rt")))]
39pub async fn yield_now() {
40 /// Yield implementation
41 struct YieldNow {
42 yielded: bool,
43 }
44
45 impl Future for YieldNow {
46 type Output = ();
47
48 fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
49 ready!(crate::trace::trace_leaf(cx));
50
51 if self.yielded {
52 return Poll::Ready(());
53 }
54
55 self.yielded = true;
56
57 context::defer(cx.waker());
58
59 Poll::Pending
60 }
61 }
62
63 YieldNow { yielded: false }.await
64}
65