move rotator types into /macros/join and re-export, fix formatting, remove comment inside macro invocation in example

Author: jlizen

tokio/src/macros/join.rs

@@ -88,10 +88,10 @@ macro_rules! doc {
         /// #[tokio::main]
         /// async fn main() {
         ///     let (first, second) = tokio::join!(
-        ///         // do_stuff_async() will always be polled first when woken
         ///         biased;
         ///         do_stuff_async(),
-        ///         more_async_work());
+        ///         more_async_work()
+        ///     );
         ///
         ///     // do something with the values
         /// }
@@ -224,3 +224,34 @@ doc! {macro_rules! join {
 
     () => { async {}.await }
 }}
+
+#[derive(Default, Debug)]
+/// Rotates by one every [`Self::num_skip`] call up to COUNT - 1.
+pub struct Rotator<const COUNT: u32> {
+    next: u32,
+}
+
+impl<const COUNT: u32> Rotator<COUNT> {
+    /// Rotates by one every [`Self::num_skip`] call up to COUNT - 1
+    #[inline]
+    pub fn num_skip(&mut self) -> u32 {
+        let num_skip = self.next;
+        self.next += 1;
+        if self.next == COUNT {
+            self.next = 0;
+        }
+        num_skip
+    }
+}
+
+/// [`Self::num_skip`] always returns 0.
+#[derive(Default, Debug)]
+pub struct BiasedRotator {}
+
+impl BiasedRotator {
+    /// Always returns 0
+    #[inline]
+    pub fn num_skip(&mut self) -> u32 {
+        0
+    }
+}

tokio/src/macros/support.rs

@@ -3,6 +3,11 @@ cfg_macros! {
 
     pub use std::future::poll_fn;
 
+    // Used with `join!` and `try_join!`
+    pub use crate::macros::join::Rotator;
+    // Used with `join!` and `try_join!`
+    pub use crate::macros::join::BiasedRotator;
+
     #[doc(hidden)]
     pub fn thread_rng_n(n: u32) -> u32 {
         crate::runtime::context::thread_rng_n(n)
@@ -23,39 +28,10 @@ cfg_macros! {
             Poll::Ready(())
         }
     }
+
+
 }
 
 pub use std::future::{Future, IntoFuture};
 pub use std::pin::Pin;
 pub use std::task::{Context, Poll};
-
-#[doc(hidden)]
-#[derive(Default, Debug)]
-pub struct Rotator<const COUNT: u32> {
-    next: u32,
-}
-
-impl<const COUNT: u32> Rotator<COUNT> {
-    #[doc(hidden)]
-    #[inline]
-    pub fn num_skip(&mut self) -> u32 {
-        let num_skip = self.next;
-        self.next += 1;
-        if self.next == COUNT {
-            self.next = 0;
-        }
-        num_skip
-    }
-}
-
-#[doc(hidden)]
-#[derive(Default, Debug)]
-pub struct BiasedRotator {}
-
-impl BiasedRotator {
-    #[doc(hidden)]
-    #[inline]
-    pub fn num_skip(&mut self) -> u32 {
-        0
-    }
-}

tokio/src/macros/try_join.rs

@@ -135,10 +135,10 @@ macro_rules! doc {
         /// #[tokio::main]
         /// async fn main() {
         ///     let res = tokio::try_join!(
-        ///         //do_stuff_async() will always be polled first when woken
         ///         biased;
         ///         do_stuff_async(),
-        ///         more_async_work());
+        ///         more_async_work()
+        ///     );
         ///
         ///     match res {
         ///          Ok((first, second)) => {
@@ -215,53 +215,53 @@ doc! {macro_rules! try_join {
             // This loop runs twice and the first `skip` futures
             // are not polled in the first iteration.
             loop {
-                $(
-                    if skip == 0 {
-                        if to_run == 0 {
-                            // Every future has been polled
-                            break;
-                        }
-                        to_run -= 1;
+            $(
+                if skip == 0 {
+                    if to_run == 0 {
+                        // Every future has been polled
+                        break;
+                    }
+                    to_run -= 1;
 
-                        // Extract the future for this branch from the tuple.
-                        let ( $($skip,)* fut, .. ) = &mut *futures;
+                    // Extract the future for this branch from the tuple.
+                    let ( $($skip,)* fut, .. ) = &mut *futures;
 
-                        // Safety: future is stored on the stack above
-                        // and never moved.
-                        let mut fut = unsafe { Pin::new_unchecked(fut) };
+                    // Safety: future is stored on the stack above
+                    // and never moved.
+                    let mut fut = unsafe { Pin::new_unchecked(fut) };
 
-                        // Try polling
-                        if fut.as_mut().poll(cx).is_pending() {
-                            is_pending = true;
-                        } else if fut.as_mut().output_mut().expect("expected completed future").is_err() {
-                            return Ready(Err(fut.take_output().expect("expected completed future").err().unwrap()))
-                        }
-                    } else {
-                        // Future skipped, one less future to skip in the next iteration
-                        skip -= 1;
+                    // Try polling
+                    if fut.as_mut().poll(cx).is_pending() {
+                        is_pending = true;
+                    } else if fut.as_mut().output_mut().expect("expected completed future").is_err() {
+                        return Ready(Err(fut.take_output().expect("expected completed future").err().unwrap()))
                     }
-                )*
+                } else {
+                    // Future skipped, one less future to skip in the next iteration
+                    skip -= 1;
                 }
+            )*
+            }
 
-                if is_pending {
-                    Pending
-                } else {
-                    Ready(Ok(($({
-                        // Extract the future for this branch from the tuple.
-                        let ( $($skip,)* fut, .. ) = &mut futures;
+            if is_pending {
+                Pending
+            } else {
+                Ready(Ok(($({
+                    // Extract the future for this branch from the tuple.
+                    let ( $($skip,)* fut, .. ) = &mut futures;
 
-                        // Safety: future is stored on the stack above
-                        // and never moved.
-                        let mut fut = unsafe { Pin::new_unchecked(fut) };
+                    // Safety: future is stored on the stack above
+                    // and never moved.
+                    let mut fut = unsafe { Pin::new_unchecked(fut) };
 
-                        fut
-                            .take_output()
-                            .expect("expected completed future")
-                            .ok()
-                            .expect("expected Ok(_)")
-                    },)*)))
-                }
-            }).await
+                    fut
+                        .take_output()
+                        .expect("expected completed future")
+                        .ok()
+                        .expect("expected Ok(_)")
+                },)*)))
+            }
+        }).await
     }};
 
     // ===== Normalize =====