rename crate, adapter and extension method to FutureQueue

We're going to add a FutureQueueGrouped to this crate.
`buffer_unordered_weighted` is a bit too heady a name, and
`future_queue` describes what the crate does rather than how it's
implemented.

Author: sunshowers

.github/workflows/release.yml

@@ -22,7 +22,7 @@ jobs:
       - uses: taiki-e/create-gh-release-action@v1
         with:
           changelog: CHANGELOG.md
-          title: buffer-unordered-weighted $version
+          title: future-queue $version
           branch: main
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -12,6 +12,6 @@
 
 - Initial release.
 
-[0.1.2]: https://github.com/nextest-rs/buffer-unordered-weighted/releases/tag/0.1.2
-[0.1.1]: https://github.com/nextest-rs/buffer-unordered-weighted/releases/tag/0.1.1
-[0.1.0]: https://github.com/nextest-rs/buffer-unordered-weighted/releases/tag/0.1.0
+[0.1.2]: https://github.com/nextest-rs/future-queue/releases/tag/0.1.2
+[0.1.1]: https://github.com/nextest-rs/future-queue/releases/tag/0.1.1
+[0.1.0]: https://github.com/nextest-rs/future-queue/releases/tag/0.1.0

CONTRIBUTING.md

@@ -28,6 +28,6 @@ able to be built and passes all checks performed by CI.
 
 ## License
 
-By contributing to `buffer-unordered-weighted`, you agree that your contributions will be
+By contributing to `future-queue`, you agree that your contributions will be
 dual-licensed under the terms of the [`LICENSE-MIT`](LICENSE-MIT) and
 [`LICENSE-APACHE`](LICENSE-APACHE) files in the root directory of this source tree.

Cargo.toml

@@ -1,11 +1,11 @@
 [package]
-name = "buffer-unordered-weighted"
+name = "future-queue"
 version = "0.1.2"
-description = "Stream::buffer_unordered where each future can have a different weight."
+description = "Adapters to manage a queue of futures, where each future can have a different weight."
 edition = "2021"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
-repository = "https://github.com/nextest-rs/buffer-unordered-weighted"
+repository = "https://github.com/nextest-rs/future-queue"
 resolver = "2"
 rust-version = "1.56"
 categories = ["asynchronous"]

LICENSE-MIT

@@ -1,4 +1,4 @@
-Copyright (c) The buffer-unordered-weighted Contributors
+Copyright (c) The future-queue Contributors
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

README.md

@@ -1,13 +1,13 @@
-# buffer-unordered-weighted
+# future-queue
 
-[![buffer-unordered-weighted on crates.io](https://img.shields.io/crates/v/buffer-unordered-weighted)](https://crates.io/crates/buffer-unordered-weighted)
-[![Documentation (latest release)](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://docs.rs/buffer-unordered-weighted/)
-[![Documentation (main)](https://img.shields.io/badge/docs-main-purple)](https://nextest-rs.github.io/buffer-unordered-weighted/rustdoc/buffer_unordered_weighted)
+[![future-queue on crates.io](https://img.shields.io/crates/v/future-queue)](https://crates.io/crates/future-queue)
+[![Documentation (latest release)](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://docs.rs/future-queue/)
+[![Documentation (main)](https://img.shields.io/badge/docs-main-purple)](https://nextest-rs.github.io/future-queue/rustdoc/future_queue)
 [![Changelog](https://img.shields.io/badge/changelog-latest-blue)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE-APACHE)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE-MIT)
 
-`buffer_unordered_weighted` is a variant of
+`future_queue` is a variant of
 [`buffer_unordered`](https://docs.rs/futures/latest/futures/stream/trait.StreamExt.html#method.buffer_unordered),
 where each future can be assigned a different weight.
 
@@ -42,7 +42,7 @@ those tests should be run simultaneously.
 
 ## About this crate
 
-This crate provides an adaptor on streams called `buffer_unordered_weighted`, which can run
+This crate provides an adaptor on streams called `future_queue`, which can run
 several futures simultaneously, limiting the concurrency to a maximum *weight*.
 
 Rather than taking a stream of futures, this adaptor takes a stream of `(usize, future)` pairs,
@@ -64,27 +64,27 @@ the future.
 
 The weight of a future can be zero, in which case it doesn't count towards the maximum weight.
 
-If all weights are 1, then `buffer_unordered_weighted` is exactly the same as `buffer_unordered`.
+If all weights are 1, then `future_queue` is exactly the same as `buffer_unordered`.
 
 ## Examples
 
 ```rust
 use futures::{channel::oneshot, stream, StreamExt as _};
-use buffer_unordered_weighted::{StreamExt as _};
+use future_queue::{StreamExt as _};
 
 let (send_one, recv_one) = oneshot::channel();
 let (send_two, recv_two) = oneshot::channel();
 
 let stream_of_futures = stream::iter(vec![(1, recv_one), (2, recv_two)]);
-let mut buffered = stream_of_futures.buffer_unordered_weighted(10);
+let mut queue = stream_of_futures.future_queue(10);
 
 send_two.send("hello")?;
-assert_eq!(buffered.next().await, Some(Ok("hello")));
+assert_eq!(queue.next().await, Some(Ok("hello")));
 
 send_one.send("world")?;
-assert_eq!(buffered.next().await, Some(Ok("world")));
+assert_eq!(queue.next().await, Some(Ok("world")));
 
-assert_eq!(buffered.next().await, None);
+assert_eq!(queue.next().await, None);
 ```
 
 ## Minimum supported Rust version (MSRV)
@@ -95,6 +95,10 @@ The MSRV will likely not change in the medium term, but while this crate is a pr
 (0.x.x) it may have its MSRV bumped in a patch release. Once this crate has reached 1.x, any
 MSRV bump will be accompanied with a new minor version.
 
+## Notes
+
+This crate used to be called `buffer-unordered-weighted`. It was renamed to `future-queue` to be
+more descriptive about what the crate does rather than how it's implemented.
 
 ## Contributing
 

README.tpl

@@ -1,8 +1,8 @@
 # {{crate}}
 
-[![buffer-unordered-weighted on crates.io](https://img.shields.io/crates/v/buffer-unordered-weighted)](https://crates.io/crates/buffer-unordered-weighted)
-[![Documentation (latest release)](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://docs.rs/buffer-unordered-weighted/)
-[![Documentation (main)](https://img.shields.io/badge/docs-main-purple)](https://nextest-rs.github.io/buffer-unordered-weighted/rustdoc/buffer_unordered_weighted)
+[![future-queue on crates.io](https://img.shields.io/crates/v/future-queue)](https://crates.io/crates/future-queue)
+[![Documentation (latest release)](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://docs.rs/future-queue/)
+[![Documentation (main)](https://img.shields.io/badge/docs-main-purple)](https://nextest-rs.github.io/future-queue/rustdoc/future_queue)
 [![Changelog](https://img.shields.io/badge/changelog-latest-blue)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE-APACHE)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE-MIT)

src/future_queue.rs

@@ -1,4 +1,4 @@
-// Copyright (c) The buffer-unordered-weighted Contributors
+// Copyright (c) The future-queue Contributors
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
 use futures_util::{
@@ -14,9 +14,9 @@ use std::{
 };
 
 pin_project! {
-    /// Stream for the [`buffer_unordered_weighted`](StreamExt::buffer_unordered_weighted) method.
+    /// Stream for the [`future_queue`](StreamExt::future_queue) method.
     #[must_use = "streams do nothing unless polled"]
-    pub struct BufferUnorderedWeighted<St>
+    pub struct FutureQueue<St>
     where
         St: Stream,
         St::Item: WeightedFuture,
@@ -29,13 +29,13 @@ pin_project! {
     }
 }
 
-impl<St> fmt::Debug for BufferUnorderedWeighted<St>
+impl<St> fmt::Debug for FutureQueue<St>
 where
     St: Stream + fmt::Debug,
     St::Item: WeightedFuture,
 {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_struct("BufferUnorderedWeighted")
+        f.debug_struct("FutureQueue")
             .field("stream", &self.stream)
             .field("in_progress_queue", &self.in_progress_queue)
             .field("max_weight", &self.max_weight)
@@ -44,7 +44,7 @@ where
     }
 }
 
-impl<St> BufferUnorderedWeighted<St>
+impl<St> FutureQueue<St>
 where
     St: Stream,
     St::Item: WeightedFuture,
@@ -101,7 +101,7 @@ where
     }
 }
 
-impl<St> Stream for BufferUnorderedWeighted<St>
+impl<St> Stream for FutureQueue<St>
 where
     St: Stream,
     St::Item: WeightedFuture,
@@ -120,9 +120,8 @@ where
                     *this.current_weight =
                         this.current_weight.checked_add(weight).unwrap_or_else(|| {
                             panic!(
-                                "buffer_unordered_weighted: added weight {} to current {}, overflowed",
-                                weight,
-                                this.current_weight,
+                                "future_queue: added weight {} to current {}, overflowed",
+                                weight, this.current_weight,
                             )
                         });
                     this.in_progress_queue
@@ -136,13 +135,13 @@ where
         match this.in_progress_queue.poll_next_unpin(cx) {
             Poll::Pending => return Poll::Pending,
             Poll::Ready(Some((weight, output))) => {
-                *this.current_weight = this.current_weight.checked_sub(weight).unwrap_or_else(|| {
-                    panic!(
-                        "buffer_unordered_weighted: subtracted weight {} from current {}, overflowed",
-                        weight,
-                        this.current_weight,
-                    )
-                });
+                *this.current_weight =
+                    this.current_weight.checked_sub(weight).unwrap_or_else(|| {
+                        panic!(
+                            "future_queue: subtracted weight {} from current {}, overflowed",
+                            weight, this.current_weight,
+                        )
+                    });
                 return Poll::Ready(Some(output));
             }
             Poll::Ready(None) => {}

src/lib.rs

@@ -1,7 +1,7 @@
-// Copyright (c) The buffer-unordered-weighted Contributors
+// Copyright (c) The future-queue Contributors
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! `buffer_unordered_weighted` is a variant of
+//! `future_queue` is a variant of
 //! [`buffer_unordered`](https://docs.rs/futures/latest/futures/stream/trait.StreamExt.html#method.buffer_unordered),
 //! where each future can be assigned a different weight.
 //!
@@ -36,7 +36,7 @@
 //!
 //! # About this crate
 //!
-//! This crate provides an adaptor on streams called `buffer_unordered_weighted`, which can run
+//! This crate provides an adaptor on streams called `future_queue`, which can run
 //! several futures simultaneously, limiting the concurrency to a maximum *weight*.
 //!
 //! Rather than taking a stream of futures, this adaptor takes a stream of `(usize, future)` pairs,
@@ -58,28 +58,28 @@
 //!
 //! The weight of a future can be zero, in which case it doesn't count towards the maximum weight.
 //!
-//! If all weights are 1, then `buffer_unordered_weighted` is exactly the same as `buffer_unordered`.
+//! If all weights are 1, then `future_queue` is exactly the same as `buffer_unordered`.
 //!
 //! # Examples
 //!
 //! ```
 //! # futures::executor::block_on(async {
 //! use futures::{channel::oneshot, stream, StreamExt as _};
-//! use buffer_unordered_weighted::{StreamExt as _};
+//! use future_queue::{StreamExt as _};
 //!
 //! let (send_one, recv_one) = oneshot::channel();
 //! let (send_two, recv_two) = oneshot::channel();
 //!
 //! let stream_of_futures = stream::iter(vec![(1, recv_one), (2, recv_two)]);
-//! let mut buffered = stream_of_futures.buffer_unordered_weighted(10);
+//! let mut queue = stream_of_futures.future_queue(10);
 //!
 //! send_two.send("hello")?;
-//! assert_eq!(buffered.next().await, Some(Ok("hello")));
+//! assert_eq!(queue.next().await, Some(Ok("hello")));
 //!
 //! send_one.send("world")?;
-//! assert_eq!(buffered.next().await, Some(Ok("world")));
+//! assert_eq!(queue.next().await, Some(Ok("world")));
 //!
-//! assert_eq!(buffered.next().await, None);
+//! assert_eq!(queue.next().await, None);
 //! # Ok::<(), &'static str>(()) }).unwrap();
 //! ```
 //!
@@ -90,6 +90,11 @@
 //! The MSRV will likely not change in the medium term, but while this crate is a pre-release
 //! (0.x.x) it may have its MSRV bumped in a patch release. Once this crate has reached 1.x, any
 //! MSRV bump will be accompanied with a new minor version.
+//!
+//! # Notes
+//!
+//! This crate used to be called `buffer-unordered-weighted`. It was renamed to `future-queue` to be
+//! more descriptive about what the crate does rather than how it's implemented.
 
 mod future_queue;
 
@@ -98,7 +103,7 @@ use futures_util::{Future, Stream};
 impl<T: ?Sized> StreamExt for T where T: Stream {}
 
 /// An extension trait for `Stream`s that provides
-/// [`buffer_unordered_weighted`](StreamExt::buffer_unordered_weighted).
+/// [`future_queue`](StreamExt::future_queue).
 pub trait StreamExt: Stream {
     /// An adaptor for creating a buffered list of pending futures (unordered), where
     /// each future has a different weight.
@@ -121,17 +126,12 @@ pub trait StreamExt: Stream {
     /// # Examples
     ///
     /// See [the crate documentation](crate#examples) for an example.
-    fn buffer_unordered_weighted<Fut>(
-        self,
-        max_weight: usize,
-    ) -> future_queue::BufferUnorderedWeighted<Self>
+    fn future_queue<Fut>(self, max_weight: usize) -> future_queue::FutureQueue<Self>
     where
         Self: Sized + Stream<Item = (usize, Fut)>,
         Fut: Future,
     {
-        assert_stream::<Fut::Output, _>(future_queue::BufferUnorderedWeighted::new(
-            self, max_weight,
-        ))
+        assert_stream::<Fut::Output, _>(future_queue::FutureQueue::new(self, max_weight))
     }
 }
 

tests/test_properties.rs

@@ -1,7 +1,7 @@
-// Copyright (c) The buffer-unordered-weighted Contributors
+// Copyright (c) The future-queue Contributors
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-use buffer_unordered_weighted::StreamExt as _;
+use future_queue::StreamExt as _;
 use futures::{stream, StreamExt as _};
 use proptest::prelude::*;
 use proptest_derive::Arbitrary;
@@ -30,8 +30,8 @@ fn duration_strategy() -> BoxedStrategy<Duration> {
 
 proptest! {
     #[test]
-    fn proptest_buffer_unordered(state: TestState) {
-        proptest_buffer_unordered_impl(state)
+    fn proptest_future_queue(state: TestState) {
+        proptest_future_queue_impl(state)
     }
 }
 
@@ -41,7 +41,7 @@ enum FutureEvent {
     Finished(usize, TestFutureDesc),
 }
 
-fn proptest_buffer_unordered_impl(state: TestState) {
+fn proptest_future_queue_impl(state: TestState) {
     let runtime = tokio::runtime::Builder::new_current_thread()
         .enable_time()
         .start_paused(true)
@@ -75,7 +75,7 @@ fn proptest_buffer_unordered_impl(state: TestState) {
 
     runtime.block_on(async move {
         // Record values that have been completed in this map.
-        let mut stream = stream.buffer_unordered_weighted(state.max_weight);
+        let mut stream = stream.future_queue(state.max_weight);
         loop {
             tokio::select! {
                 // biased ensures that the receiver is drained before the stream is polled. Without