From 38f1eb2007262b8fcf968075419a3e258fc19e10 Mon Sep 17 00:00:00 2001 From: zachs18 <8355914+zachs18@users.noreply.github.com> Date: Sun, 8 Oct 2023 19:21:49 -0500 Subject: [PATCH 1/3] Update `FuturesOrdered` docs to refer to `poll_next` instead of `poll` and `push_back` instead of `push` (which is deprecated). --- futures-util/src/stream/futures_ordered.rs | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/futures-util/src/stream/futures_ordered.rs b/futures-util/src/stream/futures_ordered.rs index 618bf1b7b..2fe67be30 100644 --- a/futures-util/src/stream/futures_ordered.rs +++ b/futures-util/src/stream/futures_ordered.rs @@ -70,18 +70,18 @@ where /// large numbers of futures. /// /// When a `FuturesOrdered` is first created, it does not contain any futures. -/// Calling `poll` in this state will result in `Poll::Ready(None))` to be -/// returned. Futures are submitted to the queue using `push`; however, the +/// Calling `poll_next` in this state will result in `Poll::Ready(None))` to be +/// returned. Futures are submitted to the queue using `push_back` (or `push_front`); however, the /// future will **not** be polled at this point. `FuturesOrdered` will only -/// poll managed futures when `FuturesOrdered::poll` is called. As such, it -/// is important to call `poll` after pushing new futures. +/// poll managed futures when `FuturesOrdered::poll_next` is called. As such, it +/// is important to call `poll_next` after pushing new futures. /// -/// If `FuturesOrdered::poll` returns `Poll::Ready(None)` this means that +/// If `FuturesOrdered::poll_next` returns `Poll::Ready(None)` this means that /// the queue is currently not managing any futures. A future may be submitted /// to the queue at a later time. At that point, a call to -/// `FuturesOrdered::poll` will either return the future's resolved value +/// `FuturesOrdered::poll_next` will either return the future's resolved value /// **or** `Poll::Pending` if the future has not yet completed. When -/// multiple futures are submitted to the queue, `FuturesOrdered::poll` will +/// multiple futures are submitted to the queue, `FuturesOrdered::poll_next` will /// return `Poll::Pending` until the first future completes, even if /// some of the later futures have already completed. /// @@ -133,7 +133,7 @@ impl FuturesOrdered { /// /// This function submits the given future to the internal set for managing. /// This function will not call `poll` on the submitted future. The caller - /// must ensure that `FuturesOrdered::poll` is called in order to receive + /// must ensure that `FuturesOrdered::poll_next` is called in order to receive /// task notifications. #[deprecated(note = "use `push_back` instead")] pub fn push(&mut self, future: Fut) { @@ -144,7 +144,7 @@ impl FuturesOrdered { /// /// This function submits the given future to the internal set for managing. /// This function will not call `poll` on the submitted future. The caller - /// must ensure that `FuturesOrdered::poll` is called in order to receive + /// must ensure that `FuturesOrdered::poll_next` is called in order to receive /// task notifications. pub fn push_back(&mut self, future: Fut) { let wrapped = OrderWrapper { data: future, index: self.next_incoming_index }; @@ -156,7 +156,7 @@ impl FuturesOrdered { /// /// This function submits the given future to the internal set for managing. /// This function will not call `poll` on the submitted future. The caller - /// must ensure that `FuturesOrdered::poll` is called in order to receive + /// must ensure that `FuturesOrdered::poll_next` is called in order to receive /// task notifications. This future will be the next future to be returned /// complete. pub fn push_front(&mut self, future: Fut) { From d4593812cdca574fb4de1023cf31223c4ad6c5e6 Mon Sep 17 00:00:00 2001 From: Zachary S Date: Sun, 8 Oct 2023 19:43:00 -0500 Subject: [PATCH 2/3] Add doclinks to `FuturesOrdered`'s docs. --- futures-util/src/stream/futures_ordered.rs | 44 +++++++++++----------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/futures-util/src/stream/futures_ordered.rs b/futures-util/src/stream/futures_ordered.rs index 2fe67be30..23d00ce6b 100644 --- a/futures-util/src/stream/futures_ordered.rs +++ b/futures-util/src/stream/futures_ordered.rs @@ -65,29 +65,29 @@ where /// /// Futures are pushed into this queue and their realized values are yielded in /// order. This structure is optimized to manage a large number of futures. -/// Futures managed by `FuturesOrdered` will only be polled when they generate +/// Futures managed by [`FuturesOrdered`] will only be polled when they generate /// notifications. This reduces the required amount of work needed to coordinate /// large numbers of futures. /// -/// When a `FuturesOrdered` is first created, it does not contain any futures. -/// Calling `poll_next` in this state will result in `Poll::Ready(None))` to be -/// returned. Futures are submitted to the queue using `push_back` (or `push_front`); however, the -/// future will **not** be polled at this point. `FuturesOrdered` will only -/// poll managed futures when `FuturesOrdered::poll_next` is called. As such, it -/// is important to call `poll_next` after pushing new futures. +/// When a [`FuturesOrdered`] is first created, it does not contain any futures. +/// Calling [`poll_next`](FuturesOrdered::poll_next) in this state will result in [`Poll::Ready(None)`](Poll::Ready) to be +/// returned. Futures are submitted to the queue using [`push_back`](FuturesOrdered::push_back) (or [`push_front`](FuturesOrdered::push_front)); however, the +/// future will **not** be polled at this point. [`FuturesOrdered`] will only +/// poll managed futures when [`FuturesOrdered::poll_next`] is called. As such, it +/// is important to call [`poll_next`](FuturesOrdered::poll_next) after pushing new futures. /// -/// If `FuturesOrdered::poll_next` returns `Poll::Ready(None)` this means that +/// If [`FuturesOrdered::poll_next`] returns [`Poll::Ready(None)`](Poll::Ready) this means that /// the queue is currently not managing any futures. A future may be submitted /// to the queue at a later time. At that point, a call to -/// `FuturesOrdered::poll_next` will either return the future's resolved value -/// **or** `Poll::Pending` if the future has not yet completed. When -/// multiple futures are submitted to the queue, `FuturesOrdered::poll_next` will -/// return `Poll::Pending` until the first future completes, even if +/// [`FuturesOrdered::poll_next`] will either return the future's resolved value +/// **or** [`Poll::Pending`] if the future has not yet completed. When +/// multiple futures are submitted to the queue, [`FuturesOrdered::poll_next`] will +/// return [`Poll::Pending`] until the first future completes, even if /// some of the later futures have already completed. /// -/// Note that you can create a ready-made `FuturesOrdered` via the +/// Note that you can create a ready-made [`FuturesOrdered`] via the /// [`collect`](Iterator::collect) method, or you can start with an empty queue -/// with the `FuturesOrdered::new` constructor. +/// with the [`FuturesOrdered::new`] constructor. /// /// This type is only available when the `std` or `alloc` feature of this /// library is activated, and it is activated by default. @@ -104,8 +104,8 @@ impl Unpin for FuturesOrdered {} impl FuturesOrdered { /// Constructs a new, empty `FuturesOrdered` /// - /// The returned `FuturesOrdered` does not contain any futures and, in this - /// state, `FuturesOrdered::poll_next` will return `Poll::Ready(None)`. + /// The returned [`FuturesOrdered`] does not contain any futures and, in this + /// state, [`FuturesOrdered::poll_next`] will return [`Poll::Ready(None)`](Poll::Ready). pub fn new() -> Self { Self { in_progress_queue: FuturesUnordered::new(), @@ -132,8 +132,8 @@ impl FuturesOrdered { /// Push a future into the queue. /// /// This function submits the given future to the internal set for managing. - /// This function will not call `poll` on the submitted future. The caller - /// must ensure that `FuturesOrdered::poll_next` is called in order to receive + /// This function will not call [`poll`](Future::poll) on the submitted future. The caller + /// must ensure that [`FuturesOrdered::poll_next`] is called in order to receive /// task notifications. #[deprecated(note = "use `push_back` instead")] pub fn push(&mut self, future: Fut) { @@ -143,8 +143,8 @@ impl FuturesOrdered { /// Pushes a future to the back of the queue. /// /// This function submits the given future to the internal set for managing. - /// This function will not call `poll` on the submitted future. The caller - /// must ensure that `FuturesOrdered::poll_next` is called in order to receive + /// This function will not call [`poll`](Future::poll) on the submitted future. The caller + /// must ensure that [`FuturesOrdered::poll_next`] is called in order to receive /// task notifications. pub fn push_back(&mut self, future: Fut) { let wrapped = OrderWrapper { data: future, index: self.next_incoming_index }; @@ -155,8 +155,8 @@ impl FuturesOrdered { /// Pushes a future to the front of the queue. /// /// This function submits the given future to the internal set for managing. - /// This function will not call `poll` on the submitted future. The caller - /// must ensure that `FuturesOrdered::poll_next` is called in order to receive + /// This function will not call [`poll`](Future::poll) on the submitted future. The caller + /// must ensure that [`FuturesOrdered::poll_next`] is called in order to receive /// task notifications. This future will be the next future to be returned /// complete. pub fn push_front(&mut self, future: Fut) { From ce70fe0c980f54db4cd5dfd6703672ebb1a44dd7 Mon Sep 17 00:00:00 2001 From: Zachary S Date: Sun, 8 Oct 2023 19:54:47 -0500 Subject: [PATCH 3/3] Wrap doc comments in futures_ordered.rs --- futures-util/src/stream/futures_ordered.rs | 52 ++++++++++++---------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/futures-util/src/stream/futures_ordered.rs b/futures-util/src/stream/futures_ordered.rs index 23d00ce6b..3aaef8bde 100644 --- a/futures-util/src/stream/futures_ordered.rs +++ b/futures-util/src/stream/futures_ordered.rs @@ -58,8 +58,8 @@ where /// An unbounded queue of futures. /// -/// This "combinator" is similar to [`FuturesUnordered`], but it imposes a FIFO order -/// on top of the set of futures. While futures in the set will race to +/// This "combinator" is similar to [`FuturesUnordered`], but it imposes a FIFO +/// order on top of the set of futures. While futures in the set will race to /// completion in parallel, results will only be returned in the order their /// originating futures were added to the queue. /// @@ -70,19 +70,22 @@ where /// large numbers of futures. /// /// When a [`FuturesOrdered`] is first created, it does not contain any futures. -/// Calling [`poll_next`](FuturesOrdered::poll_next) in this state will result in [`Poll::Ready(None)`](Poll::Ready) to be -/// returned. Futures are submitted to the queue using [`push_back`](FuturesOrdered::push_back) (or [`push_front`](FuturesOrdered::push_front)); however, the -/// future will **not** be polled at this point. [`FuturesOrdered`] will only -/// poll managed futures when [`FuturesOrdered::poll_next`] is called. As such, it -/// is important to call [`poll_next`](FuturesOrdered::poll_next) after pushing new futures. +/// Calling [`poll_next`](FuturesOrdered::poll_next) in this state will result +/// in [`Poll::Ready(None)`](Poll::Ready) to be returned. Futures are submitted +/// to the queue using [`push_back`](FuturesOrdered::push_back) (or +/// [`push_front`](FuturesOrdered::push_front)); however, the future will +/// **not** be polled at this point. [`FuturesOrdered`] will only poll managed +/// futures when [`FuturesOrdered::poll_next`] is called. As such, it +/// is important to call [`poll_next`](FuturesOrdered::poll_next) after pushing +/// new futures. /// -/// If [`FuturesOrdered::poll_next`] returns [`Poll::Ready(None)`](Poll::Ready) this means that -/// the queue is currently not managing any futures. A future may be submitted -/// to the queue at a later time. At that point, a call to +/// If [`FuturesOrdered::poll_next`] returns [`Poll::Ready(None)`](Poll::Ready) +/// this means that the queue is currently not managing any futures. A future +/// may be submitted to the queue at a later time. At that point, a call to /// [`FuturesOrdered::poll_next`] will either return the future's resolved value /// **or** [`Poll::Pending`] if the future has not yet completed. When -/// multiple futures are submitted to the queue, [`FuturesOrdered::poll_next`] will -/// return [`Poll::Pending`] until the first future completes, even if +/// multiple futures are submitted to the queue, [`FuturesOrdered::poll_next`] +/// will return [`Poll::Pending`] until the first future completes, even if /// some of the later futures have already completed. /// /// Note that you can create a ready-made [`FuturesOrdered`] via the @@ -104,8 +107,9 @@ impl Unpin for FuturesOrdered {} impl FuturesOrdered { /// Constructs a new, empty `FuturesOrdered` /// - /// The returned [`FuturesOrdered`] does not contain any futures and, in this - /// state, [`FuturesOrdered::poll_next`] will return [`Poll::Ready(None)`](Poll::Ready). + /// The returned [`FuturesOrdered`] does not contain any futures and, in + /// this state, [`FuturesOrdered::poll_next`] will return + /// [`Poll::Ready(None)`](Poll::Ready). pub fn new() -> Self { Self { in_progress_queue: FuturesUnordered::new(), @@ -132,9 +136,9 @@ impl FuturesOrdered { /// Push a future into the queue. /// /// This function submits the given future to the internal set for managing. - /// This function will not call [`poll`](Future::poll) on the submitted future. The caller - /// must ensure that [`FuturesOrdered::poll_next`] is called in order to receive - /// task notifications. + /// This function will not call [`poll`](Future::poll) on the submitted + /// future. The caller must ensure that [`FuturesOrdered::poll_next`] is + /// called in order to receive task notifications. #[deprecated(note = "use `push_back` instead")] pub fn push(&mut self, future: Fut) { self.push_back(future); @@ -143,9 +147,9 @@ impl FuturesOrdered { /// Pushes a future to the back of the queue. /// /// This function submits the given future to the internal set for managing. - /// This function will not call [`poll`](Future::poll) on the submitted future. The caller - /// must ensure that [`FuturesOrdered::poll_next`] is called in order to receive - /// task notifications. + /// This function will not call [`poll`](Future::poll) on the submitted + /// future. The caller must ensure that [`FuturesOrdered::poll_next`] is + /// called in order to receive task notifications. pub fn push_back(&mut self, future: Fut) { let wrapped = OrderWrapper { data: future, index: self.next_incoming_index }; self.next_incoming_index += 1; @@ -155,10 +159,10 @@ impl FuturesOrdered { /// Pushes a future to the front of the queue. /// /// This function submits the given future to the internal set for managing. - /// This function will not call [`poll`](Future::poll) on the submitted future. The caller - /// must ensure that [`FuturesOrdered::poll_next`] is called in order to receive - /// task notifications. This future will be the next future to be returned - /// complete. + /// This function will not call [`poll`](Future::poll) on the submitted + /// future. The caller must ensure that [`FuturesOrdered::poll_next`] is + /// called in order to receive task notifications. This future will be + /// the next future to be returned complete. pub fn push_front(&mut self, future: Fut) { let wrapped = OrderWrapper { data: future, index: self.next_outgoing_index - 1 }; self.next_outgoing_index -= 1;