[−][src]Crate async_task
Task abstraction for building executors.
To spawn a future onto an executor, we first need to allocate it on the heap and keep some state alongside it. The state indicates whether the future is ready for polling, waiting to be woken up, or completed. Such a future is called a task.
This crate helps with task allocation and polling its future to completion.
Spawning
All executors have some kind of queue that holds runnable tasks:
let (sender, receiver) = crossbeam::channel::unbounded();
A task is constructed using the spawn
function:
// A future that will be spawned. let future = async { 1 + 2 }; // A function that schedules the task when it gets woken up. let schedule = move |task| sender.send(task).unwrap(); // Construct a task. let (task, handle) = async_task::spawn(future, schedule, ()); // Push the task into the queue by invoking its schedule function. task.schedule();
The last argument to the spawn
function is a tag, an arbitrary piece of data associated
with the task. In most executors, this is typically a task identifier or task-local storage.
The function returns a runnable Task
and a JoinHandle
that can await the result.
Execution
Task executors have some kind of main loop that drives tasks to completion. That means taking runnable tasks out of the queue and running each one in order:
for task in receiver { task.run(); }
When a task is run, its future gets polled. If polling does not complete the task, that means it's waiting for another future and needs to go to sleep. When woken up, its schedule function will be invoked, pushing it back into the queue so that it can be run again.
Cancellation
Both Task
and JoinHandle
have a method that cancels the task. When cancelled, the
task's future will not be polled again and will get dropped instead.
If cancelled by the Task
instance, the task is destroyed immediately. If cancelled by the
JoinHandle
instance, it will be scheduled one more time and the next attempt to run it will
simply destroy it.
Performance
Task construction incurs a single allocation only that holds its state, the schedule function, and the future or the result of the future if completed.
The layout of a task is equivalent to 4 words followed by the schedule function, and then by a union of the future and its output.
Structs
JoinHandle | A handle that awaits the result of a task. |
Task | A task reference that runs its future. |
Functions
spawn | Creates a new task. |