Module glommio::task [−][src]
Task abstraction for building executors.
Spawning
To spawn a future onto the Glommio 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.
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.
Paired with a task there usually is a JoinHandle
that can be used to
wait for the task’s completion.
Cancellation
Both Task
and JoinHandle
have methods that cancel the task. When
canceled, the task’s future will not be polled again and will get dropped
instead.
If canceled by the Task
instance, the task is destroyed immediately. If
canceled by the JoinHandle
instance, it will be scheduled one more time
and the next attempt to run it will simply destroy it.
The JoinHandle
future will then evaluate to None
, but only after the
task’s future is dropped.
Performance
Task construction incurs a single allocation 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 usize
s followed by the schedule
function, and then by a union of the future and its output.
Waking
The handy waker_fn
constructor converts any function into a Waker
.
Every time it is woken, the function gets called:
let waker = glommio::task::waker_fn(|| println!("Wake!")); // Prints "Wake!" twice. waker.wake_by_ref(); waker.wake_by_ref();
Structs
JoinHandle | A handle that awaits the result of a task. |
Task | A task reference that runs its future. |
Functions
waker_fn | Creates a waker from a wake function. |