From fc904a22cd9b888ea4aa119f33840d3589ad8577 Mon Sep 17 00:00:00 2001 From: Yoshua Wuyts Date: Wed, 9 Oct 2019 13:03:38 +0200 Subject: [PATCH] add task::blocking docs Signed-off-by: Yoshua Wuyts --- src/task/block_on.rs | 4 ++++ src/task/mod.rs | 24 +++++++++++++++++++++++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/src/task/block_on.rs b/src/task/block_on.rs index f585693..1150400 100644 --- a/src/task/block_on.rs +++ b/src/task/block_on.rs @@ -19,6 +19,10 @@ use kv_log_macro::trace; /// Calling this function is similar to [spawning] a thread and immediately [joining] it, except an /// asynchronous task will be spawned. /// +/// See also: [`task::blocking`]. +/// +/// [`task::blocking`]: fn.blocking.html +/// /// [spawning]: https://doc.rust-lang.org/std/thread/fn.spawn.html /// [joining]: https://doc.rust-lang.org/std/thread/struct.JoinHandle.html#method.join /// diff --git a/src/task/mod.rs b/src/task/mod.rs index a23a7c8..a14e5d5 100644 --- a/src/task/mod.rs +++ b/src/task/mod.rs @@ -51,7 +51,29 @@ pub(crate) mod blocking; /// Spawns a blocking task. /// -/// The task will be spawned onto a thread pool specifically dedicated to blocking tasks. +/// The task will be spawned onto a thread pool specifically dedicated to blocking tasks. This +/// is useful to prevent long-running synchronous operations from blocking the main futures +/// executor. +/// +/// See also: [`task::block_on`]. +/// +/// [`task::block_on`]: fn.block_on.html +/// +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// # fn main() { async_std::task::block_on(async { +/// # +/// use async_std::task; +/// +/// task::blocking(async { +/// println!("long-running task here"); +/// }).await; +/// # +/// # }) } +/// ``` // Once this function stabilizes we should merge `blocking::spawn` into this so // all code in our crate uses `task::blocking` too. #[cfg(any(feature = "unstable", feature = "docs"))]