Struct TaskStorage

#[repr(C)]
pub struct TaskStorage<F: Future + 'static> { /* private fields */ }

Raw storage in which a task can be spawned.

This struct holds the necessary memory to spawn one task whose future is F. At a given time, the TaskStorage may be in spawned or not-spawned state. You may spawn it with TaskStorage::spawn(), which will fail if it is already spawned.

A TaskStorage must live forever, it may not be deallocated even after the task has finished running. Hence the relevant methods require &'static self. It may be reused, however.

Internally, the embassy_executor::task macro allocates an array of TaskStorages in a static. The most common reason to use the raw Task is to have control of where the memory for the task is allocated: on the stack, or on the heap with e.g. Box::leak, etc.

Implementations

impl<F: Future + 'static> TaskStorage<F>

pub const fn new() -> Self

Create a new TaskStorage, in not-spawned state.

pub fn spawn( &'static self, future: impl FnOnce() -> F, ) -> SpawnToken<impl Sized>

Try to spawn the task.

The future closure constructs the future. It’s only called if spawning is actually possible. It is a closure instead of a simple future: F param to ensure the future is constructed in-place, avoiding a temporary copy in the stack thanks to NRVO optimizations.

This function will fail if the task is already spawned and has not finished running. In this case, the error is delayed: a “poisoned” SpawnToken is returned, which will cause Spawner::spawn() to return the error.

Once the task has finished running, you may spawn it again. It is allowed to spawn it on a different executor.