task: document non-guarantees of yield_now (#4091)

tokio/src/task/yield_now.rs

@@ -2,37 +2,58 @@ use std::future::Future;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-cfg_rt! {
+/// Yields execution back to the Tokio runtime.
-    /// Yields execution back to the Tokio runtime.
+///
-    ///
+/// A task yields by awaiting on `yield_now()`, and may resume when that future
-    /// A task yields by awaiting on `yield_now()`, and may resume when that
+/// completes (with no output.) The current task will be re-added as a pending
-    /// future completes (with no output.) The current task will be re-added as
+/// task at the _back_ of the pending queue. Any other pending tasks will be
-    /// a pending task at the _back_ of the pending queue. Any other pending
+/// scheduled. No other waking is required for the task to continue.
-    /// tasks will be scheduled. No other waking is required for the task to
+///
-    /// continue.
+/// See also the usage example in the [task module](index.html#yield_now).
-    ///
+///
-    /// See also the usage example in the [task module](index.html#yield_now).
+/// ## Non-guarantees
-    #[must_use = "yield_now does nothing unless polled/`await`-ed"]
+///
-    pub async fn yield_now() {
+/// This function may not yield all the way up to the executor if there are any
-        /// Yield implementation
+/// special combinators above it in the call stack. For example, if a
-        struct YieldNow {
+/// [`tokio::select!`] has another branch complete during the same poll as the
-            yielded: bool,
+/// `yield_now()`, then the yield is not propagated all the way up to the
-        }
+/// runtime.
-
+///
-        impl Future for YieldNow {
+/// It is generally not guaranteed that the runtime behaves like you expect it
-            type Output = ();
+/// to when deciding which task to schedule next after a call to `yield_now()`.
-
+/// In particular, the runtime may choose to poll the task that just ran
-            fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
+/// `yield_now()` again immediately without polling any other tasks first. For
-                if self.yielded {
+/// example, the runtime will not drive the IO driver between every poll of a
-                    return Poll::Ready(());
+/// task, and this could result in the runtime polling the current task again
-                }
+/// immediately even if there is another task that could make progress if that
-
+/// other task is waiting for a notification from the IO driver.
-                self.yielded = true;
+///
-                cx.waker().wake_by_ref();
+/// In general, changes to the order in which the runtime polls tasks is not
-                Poll::Pending
+/// considered a breaking change, and your program should be correct no matter
-            }
+/// which order the runtime polls your tasks in.
-        }
+///
-
+/// [`tokio::select!`]: macro@crate::select
-        YieldNow { yielded: false }.await
+#[must_use = "yield_now does nothing unless polled/`await`-ed"]
+#[cfg_attr(docsrs, doc(cfg(feature = "rt")))]
+pub async fn yield_now() {
+    /// Yield implementation
+    struct YieldNow {
+        yielded: bool,
     }
+
+    impl Future for YieldNow {
+        type Output = ();
+
+        fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
+            if self.yielded {
+                return Poll::Ready(());
+            }
+
+            self.yielded = true;
+            cx.waker().wake_by_ref();
+            Poll::Pending
+        }
+    }
+
+    YieldNow { yielded: false }.await
 }