Document task::spawn's support for blocking tasks.

src/task/spawn.rs

@@ -23,6 +23,24 @@ use crate::task::{Builder, JoinHandle};
 /// #
 /// # })
 /// ```
+///
+/// # Blocking
+///
+/// It is fine to use `spawn` to start tasks that may carry out long-running
+/// computations, use blocking I/O primitives, or otherwise engage in activities
+/// that mean that polling the task's future may not always return quickly.
+///
+/// This function begins executing the given future on a thread pool shared with
+/// other asynchronous tasks. If polling a particular task takes too long, that
+/// thread is removed from the general pool and assigned to run that task
+/// exclusively. A new thread is created to take its place in the general pool.
+///
+/// Although the usual expectation in asynchronous programming is that polling a
+/// future should return quickly, in practice it can be hard to anticipate how a
+/// given task will behave. A computation that has the potential to take a long
+/// time might return quickly in practice, and vice versa. The `spawn` function
+/// observes each task's behavior and chooses dynamically whether to assign it a
+/// dedicated thread or let it share the thread pool with other tasks.
 pub fn spawn<F, T>(future: F) -> JoinHandle<T>
 where
     F: Future<Output = T> + Send + 'static,