Auto merge of #52735 - Mark-Simulacrum:rollup, r=Mark-Simulacrum

Rollup of 16 pull requests

Successful merges:

 - #52558 (Add tests for ICEs which no longer repro)
 - #52610 (Clarify what a task is)
 - #52617 (Don't match on region kinds when reporting NLL errors)
 - #52635 (Fix #[linkage] propagation though generic functions)
 - #52647 (Suggest to take and ignore args while closure args count mismatching)
 - #52649 (Point spans to inner elements of format strings)
 - #52654 (Format linker args in a way that works for gcc and ld)
 - #52667 (update the stdsimd submodule)
 - #52674 (Impl Executor for Box<E: Executor>)
 - #52690 (ARM: expose `rclass` and `dsp` target features)
 - #52692 (Improve readability in a few sorts)
 - #52695 (Hide some lints which are not quite right the way they are reported to the user)
 - #52718 (State default capacity for BufReader/BufWriter)
 - #52721 (std::ops::Try impl for std::task::Poll)
 - #52723 (rustc: Register crates under their real names)
 - #52734 (sparc ABI issue - structure returning from function is returned in 64bit registers (with tests))

Failed merges:

 - #52678 ([NLL] Use better spans in some errors)

r? @ghost

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, ()>,
 }