Module futures::task

Tasks used to drive a future computation

It's intended over time a particular operation (such as servicing an HTTP request) will involve many futures. This entire operation, however, can be thought of as one unit, as the entire result is essentially just moving through one large state machine.

A "task" is the unit of abstraction for what is driving this state machine and tree of futures forward. A task is used to poll futures and schedule futures with, and has utilities for sharing data between tasks and handles for notifying when a future is ready. Each task also has its own set of task-local data generated by task_local!.

Note that libraries typically should not manage tasks themselves, but rather leave that to event loops and other "executors", or by using the wait method to create and execute a task directly on the current thread.

There are two basic execution models for tasks: manually with a Notify implementation or via an Executor. A Notify is just a source of notifications that a future is ready to progress, where an Executor is generally one or more threads together with a queue of tasks to execute. Again, though, normally these methods are not called manually.

Functions

There is an important bare function in this module: park. The park function is similar to the standard library's thread::park method where it returns a handle to wake up a task at a later date (via an unpark method).

Structs

LocalKey	A key for task-local data stored in a future's task.
Run	Units of work submitted to an Executor, currently only created internally.
Spawn	Representation of a spawned future/stream.
Task	A handle to a "task", which represents a single lightweight "thread" of execution driving a future to completion.
TaskRc	A reference to a piece of data that's accessible only within a specific Task.
UnparkEvent	A set insertion to trigger upon unpark.

Traits

EventSet	A concurrent set which allows for the insertion of usize values.
Executor	A trait representing requests to poll futures.
Unpark	A trait which represents a sink of notifications that a future is ready to make progress.

Functions

park	Returns a handle to the current task to call unpark at a later date.
spawn	Spawns a new future, returning the fused future and task.
with_unpark_event	For the duration of the given callback, add an "unpark event" to be triggered when the task handle is used to unpark the task.