====== Asynchronous Programming in Rust ======


  * To support async/await, we need the **future** package: <code>[dependencies]
futures = "0.3"</code>
  * To create an asynchronous function, you can use the async fn syntax: <sxh rust; highlight: []>async fn do_something() { /* ... */ }</sxh>
  * The value returned by async fn is a **Future**. For anything to happen, the Future needs to be run on an executor: <sxh rust; highlight: []>// `block_on` blocks the current thread until the provided future has run to
// completion. Other executors provide more complex behavior, like scheduling
// multiple futures onto the same thread.
use futures::executor::block_on;

async fn hello_world() {
    println!("hello, world!");
}

fn main() {
    let future = hello_world(); // Nothing is printed
    block_on(future); // `future` is run and "hello, world!" is printed
}</sxh>
  * Inside an async fn, you can use .await to wait for the completion of another type that implements the Future trait, such as the output of another async fn: <sxh rust; highlight: []>async fn learn_song() -> Song { /* ... */ }
async fn sing_song(song: Song) { /* ... */ }
async fn dance() { /* ... */ }

async fn learn_and_sing() {
    // Wait until the song has been learned before singing it.
    // We use `.await` here rather than `block_on` to prevent blocking the
    // thread, which makes it possible to `dance` at the same time.
    let song = learn_song().await;
    sing_song(song).await;
}

async fn async_main() {
    let f1 = learn_and_sing();
    let f2 = dance();

    // `join!` is like `.await` but can wait for multiple futures concurrently.
    // If we're temporarily blocked in the `learn_and_sing` future, the `dance`
    // future will take over the current thread. If `dance` becomes blocked,
    // `learn_and_sing` can take back over. If both futures are blocked, then
    // `async_main` is blocked and will yield to the executor.
    futures::join!(f1, f2);
}

fn main() {
    block_on(async_main());
}
</sxh>