Rollup merge of #52610 - MajorBreakfast:task-terminology, r=cramertj

Clarify what a task is

Currently we call two distinct concepts "task":
1. The top-level future that is polled until completion
2. The lightweight "thread" that is responsible for polling the top-level future. What additional data beside the future is stored in this type varies between different `Executor` implementations.

I'd prefer to return to the old formulation by @alexcrichton:
```rust
/// A handle to a "task", which represents a single lightweight "thread" of
/// execution driving a future to completion.
pub struct Task {
```
Source: [`task_impl/mod.rs` in futures-rs 0.1](https://github.com/rust-lang-nursery/futures-rs/blob/1328fc9e8af5737183df477c7501e6ea24ff2053/src/task_impl/mod.rs#L49-L50)

I think that this change will make it much easier to explain everything.

r? @aturon
@cramertj

1 files changed, 18 insertions, 12 deletions

diff --git a/src/libcore/task/executor.rs b/src/libcore/task/executor.rs
index f1db5093e98..affcbf464da 100644
--- a/src/libcore/task/executor.rs
+++ b/src/libcore/task/executor.rs
@@ -17,21 +17,27 @@ use future::{FutureObj, LocalFutureObj};
 
 /// A task executor.
 ///
-/// A *task* is a `()`-producing async value that runs at the top level, and will
-/// be `poll`ed until completion. It's also the unit at which wake-up
-/// notifications occur. Executors, such as thread pools, allow tasks to be
-/// spawned and are responsible for putting tasks onto ready queues when
-/// they are woken up, and polling them when they are ready.
+/// Futures are polled until completion by tasks, a kind of lightweight
+/// "thread". A *task executor* is responsible for the creation of these tasks
+/// and the coordination of their execution on real operating system threads. In
+/// particular, whenever a task signals that it can make further progress via a
+/// wake-up notification, it is the responsibility of the task executor to put
+/// the task into a queue to continue executing it, i.e. polling the future in
+/// it, later.
 pub trait Executor {
-    /// Spawn the given task, polling it until completion.
+    /// Spawns a new task with the given future. The future will be polled until
+    /// completion.
     ///
     /// # Errors
     ///
     /// The executor may be unable to spawn tasks, either because it has
     /// been shut down or is resource-constrained.
-    fn spawn_obj(&mut self, task: FutureObj<'static, ()>) -> Result<(), SpawnObjError>;
+    fn spawn_obj(
+        &mut self,
+        future: FutureObj<'static, ()>,
+    ) -> Result<(), SpawnObjError>;
 
-    /// Determine whether the executor is able to spawn new tasks.
+    /// Determines whether the executor is able to spawn new tasks.
     ///
     /// # Returns
     ///
@@ -75,8 +81,8 @@ pub struct SpawnObjError {
     /// The kind of error
     pub kind: SpawnErrorKind,
 
-    /// The task for which spawning was attempted
-    pub task: FutureObj<'static, ()>,
+    /// The future for which spawning inside a task was attempted
+    pub future: FutureObj<'static, ()>,
 }
 
 /// The result of a failed spawn
@@ -85,6 +91,6 @@ pub struct SpawnLocalObjError {
     /// The kind of error
     pub kind: SpawnErrorKind,
 
-    /// The task for which spawning was attempted
-    pub task: LocalFutureObj<'static, ()>,
+    /// The future for which spawning inside a task was attempted
+    pub future: LocalFutureObj<'static, ()>,
 }