From 2dfdc1c4821c097066f93f64d49abe035616c9dc Mon Sep 17 00:00:00 2001 From: Yoshua Wuyts Date: Tue, 12 Nov 2019 23:07:39 +0100 Subject: [PATCH 1/4] polish lib.rs examples Signed-off-by: Yoshua Wuyts --- src/lib.rs | 50 ++++++++++++++++++++++++++++++++++++++------ src/task/block_on.rs | 8 ++++--- 2 files changed, 49 insertions(+), 9 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index ddc6462c..5442909f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -131,17 +131,55 @@ //! //! # Examples //! -//! Spawn a task and block the current thread on its result: +//! All examples require the [`"attributes"` feature](#features) to be enabled. +//! This feature is not enabled by default because it significantly impacts +//! compile times. See [`task::block_on`] for an alternative way to start +//! executing tasks. //! +//! Call an async function from the main function: +//! +//! ``` +//! async fn say_hello() { +//! println!("Hello, world!"); +//! } +//! +//! #[async_std::main] +//! async fn main() { +//! say_hello().await; +//! } +//! ``` +//! +//! Await two futures concurrently, and return a tuple of their output: +//! +//! ``` +//! #[async_std::main] +//! async fn main() { +//! let a = || async move { 1u8 }; +//! let b = || async move { 2u8 }; +//! assert_eq!(a.join(b).await, (1u8, 2u8)) +//! } //! ``` -//! use async_std::task; //! -//! fn main() { -//! task::block_on(async { -//! println!("Hello, world!"); -//! }) +//! Create a UDP server that echoes back each received message to the sender: +//! +//! ```no_run +//! use async_std::net::UdpSocket; +//! +//! #[async_std::main] +//! async fn main() -> std::io::Result<()> { +//! let mut socket = UdpSocket::bind("127.0.0.1:8080")?; +//! println!("Listening on {}", socket.local_addr()?); +//! +//! let mut buf = vec![0u8; 1024]; +//! +//! loop { +//! let (recv, peer) = socket.recv_from(&mut buf).await?; +//! let sent = socket.send_to(&buf[..recv], &peer).await?; +//! println!("Sent {} out of {} bytes to {}", sent, recv, peer); +//! } //! } //! ``` +//! [`task::block_on`]: task/fn.block_on.html //! //! # Features //! diff --git a/src/task/block_on.rs b/src/task/block_on.rs index f61a22b6..80259c57 100644 --- a/src/task/block_on.rs +++ b/src/task/block_on.rs @@ -28,9 +28,11 @@ use crate::task::{Context, Poll, Task, Waker}; /// ```no_run /// use async_std::task; /// -/// task::block_on(async { -/// println!("Hello, world!"); -/// }) +/// fn main() { +/// task::block_on(async { +/// println!("Hello, world!"); +/// }) +/// } /// ``` pub fn block_on(future: F) -> T where From 1431ee04220bd3292f38a913523e4b432997a41b Mon Sep 17 00:00:00 2001 From: Yoshua Wuyts Date: Tue, 12 Nov 2019 23:25:52 +0100 Subject: [PATCH 2/4] polish README.md examples Signed-off-by: Yoshua Wuyts --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9af20a39..3c074fee 100644 --- a/README.md +++ b/README.md @@ -75,19 +75,21 @@ syntax. ## Examples ```rust -use async_std::task; +async fn say_hello() { + println!("Hello, world!"); +} -fn main() { - task::block_on(async { - println!("Hello, world!"); - }) +#[async_std::main] +async fn main() { + say_hello().await; } ``` More examples, including networking and file access, can be found in our -[`examples`] directory. +[`examples`] directory and in our [documentation]. [`examples`]: https://github.com/async-rs/async-std/tree/master/examples +[documentation]: https://docs.rs/async-std#examples ## Philosophy From 79962e20a5a9fe346a02e2eefd258569259732d8 Mon Sep 17 00:00:00 2001 From: Yoshua Wuyts Date: Tue, 12 Nov 2019 23:37:43 +0100 Subject: [PATCH 3/4] enable attributes feature Signed-off-by: Yoshua Wuyts --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 99436b72..1d14e21d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -62,7 +62,7 @@ jobs: uses: actions-rs/cargo@v1 with: command: test - args: --all --features unstable + args: --all --features unstable attributes check_fmt_and_docs: name: Checking fmt and docs From cffacf7fa32d448a4b0707bfddd51fc0f06d2850 Mon Sep 17 00:00:00 2001 From: Yoshua Wuyts Date: Thu, 21 Nov 2019 21:21:19 +0100 Subject: [PATCH 4/4] feedback from review Signed-off-by: Yoshua Wuyts --- README.md | 6 ++++++ src/lib.rs | 4 ++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3c074fee..34ebe6df 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,10 @@ syntax. ## Examples +All examples require the [`"attributes"` feature] to be enabled. This feature +is not enabled by default because it significantly impacts compile times. See +[`task::block_on`] for an alternative way to start executing tasks. + ```rust async fn say_hello() { println!("Hello, world!"); @@ -90,6 +94,8 @@ More examples, including networking and file access, can be found in our [`examples`]: https://github.com/async-rs/async-std/tree/master/examples [documentation]: https://docs.rs/async-std#examples +[`task::block_on`]: task/fn.block_on.html +[`"attributes"` feature]: https://docs.rs/async-std/#features ## Philosophy diff --git a/src/lib.rs b/src/lib.rs index 5442909f..d0c87ff5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -154,8 +154,8 @@ //! ``` //! #[async_std::main] //! async fn main() { -//! let a = || async move { 1u8 }; -//! let b = || async move { 2u8 }; +//! let a = async { 1u8 }; +//! let b = async { 2u8 }; //! assert_eq!(a.join(b).await, (1u8, 2u8)) //! } //! ```