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](1328fc9e8a/src/task_impl/mod.rs (L49-L50)
)
I think that this change will make it much easier to explain everything.
r? @aturon
@cramertj
This commit is contained in:
commit
0127704c98
|
@ -17,21 +17,27 @@ use future::{FutureObj, LocalFutureObj};
|
||||||
|
|
||||||
/// A task executor.
|
/// A task executor.
|
||||||
///
|
///
|
||||||
/// A *task* is a `()`-producing async value that runs at the top level, and will
|
/// Futures are polled until completion by tasks, a kind of lightweight
|
||||||
/// be `poll`ed until completion. It's also the unit at which wake-up
|
/// "thread". A *task executor* is responsible for the creation of these tasks
|
||||||
/// notifications occur. Executors, such as thread pools, allow tasks to be
|
/// and the coordination of their execution on real operating system threads. In
|
||||||
/// spawned and are responsible for putting tasks onto ready queues when
|
/// particular, whenever a task signals that it can make further progress via a
|
||||||
/// they are woken up, and polling them when they are ready.
|
/// 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 {
|
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
|
/// # Errors
|
||||||
///
|
///
|
||||||
/// The executor may be unable to spawn tasks, either because it has
|
/// The executor may be unable to spawn tasks, either because it has
|
||||||
/// been shut down or is resource-constrained.
|
/// 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
|
/// # Returns
|
||||||
///
|
///
|
||||||
|
@ -75,8 +81,8 @@ pub struct SpawnObjError {
|
||||||
/// The kind of error
|
/// The kind of error
|
||||||
pub kind: SpawnErrorKind,
|
pub kind: SpawnErrorKind,
|
||||||
|
|
||||||
/// The task for which spawning was attempted
|
/// The future for which spawning inside a task was attempted
|
||||||
pub task: FutureObj<'static, ()>,
|
pub future: FutureObj<'static, ()>,
|
||||||
}
|
}
|
||||||
|
|
||||||
/// The result of a failed spawn
|
/// The result of a failed spawn
|
||||||
|
@ -85,6 +91,6 @@ pub struct SpawnLocalObjError {
|
||||||
/// The kind of error
|
/// The kind of error
|
||||||
pub kind: SpawnErrorKind,
|
pub kind: SpawnErrorKind,
|
||||||
|
|
||||||
/// The task for which spawning was attempted
|
/// The future for which spawning inside a task was attempted
|
||||||
pub task: LocalFutureObj<'static, ()>,
|
pub future: LocalFutureObj<'static, ()>,
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue