Merge a74e610f42 into 9c300510c4

examples/06_05_futuresunordered/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "example_06_05_futuresunordered"
+version = "0.1.0"
+authors = ["capnhawkbill <capnhawkbill@airmail.cc>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+futures = "0.3"

examples/06_05_futuresunordered/src/lib.rs

@@ -0,0 +1,52 @@
+#![allow(unused_variables)]
+#![allow(dead_code)]
+
+extern crate futures;
+use futures::prelude::*;
+use futures::stream::FuturesUnordered;
+
+async fn download_async(_url: &&str) {
+    // ...
+}
+
+// ANCHOR: simple
+async fn simple() {
+    let sites = [
+        "https://www.foo.com",
+        "https://www.bar.com",
+        "https://www.foobar.com",
+    ];
+
+    // Create a empty FuturesUnordered
+    let mut futures = FuturesUnordered::new();
+
+    // Push all the futures into the FuturesUnordered
+    for site in sites.iter() {
+        futures.push(download_async(site));
+    }
+
+    // Poll all the futures by calling next until it returns None.
+    while let Some(returnvalue) = futures.next().await {
+        // Do something with the returnvalue
+    }
+}
+// ANCHOR_END: simple
+
+// ANCHOR: collect
+async fn collect() {
+    let sites = [
+        "https://www.foo.com",
+        "https://www.bar.com",
+        "https://www.foobar.com",
+    ];
+
+    // Construct all the futures and collect them in the FuturesUnordered struct
+    let mut futures: FuturesUnordered<_> =
+        sites.iter().map(download_async).collect();
+
+    // Poll all the futures by calling next until it returns None.
+    while let Some(returnvalue) = futures.next().await {
+        // Do something with the returnvalue
+    }
+}
+// ANCHOR_END: collect

examples/Cargo.toml

@@ -10,6 +10,7 @@ members = [
   "05_02_iteration_and_concurrency",
   "06_02_join",
   "06_03_select",
+  "06_05_futuresunordered",
   "07_05_recursion",
   "09_01_sync_tcp_server",
   "09_02_async_tcp_server",

src/06_multiple_futures/05_futuresunordered.md

@@ -0,0 +1,21 @@
+# `FuturesUnordered`
+
+The `FuturesUnordered` struct is a set of futures which may be completed in any order.
+
+```rust,edition2018,ignore
+{{#include ../../examples/06_05_futuresunordered/src/lib.rs:simple}}
+```
+
+Because `FuturesUnordered` implements the `Stream` trait using `.next()` 
+on it will return a `Future` which returns the return value from one of
+the futures inside of an `Option`.
+It will return `None` when all futures are completed.
+
+# `Collect`
+
+The `FuturesUnordered` struct can be constructed using the `new` method or by using collect.
+The previous example can thus be rewritten like this.
+
+```rust,edition2018,ignore
+{{#include ../../examples/06_05_futuresunordered/src/lib.rs:collect}}
+```

src/SUMMARY.md

@@ -16,9 +16,9 @@
 - [Executing Multiple Futures at a Time](06_multiple_futures/01_chapter.md)
   - [`join!`](06_multiple_futures/02_join.md)
   - [`select!`](06_multiple_futures/03_select.md)
-  - [TODO: Spawning]()
-  - [TODO: Cancellation and Timeouts]()
-  - [TODO: `FuturesUnordered`]()
+  - [TODO: Spawning](404.md)
+  - [TODO: Cancellation and Timeouts](404.md)
+  - [`FuturesUnordered`](06_multiple_futures/05_futuresunordered.md)
 - [Workarounds to Know and Love](07_workarounds/01_chapter.md)
   - [`?` in `async` Blocks](07_workarounds/02_err_in_async_blocks.md)
   - [`Send` Approximation](07_workarounds/03_send_approximation.md)