Struct LocalStaticScheduler

pub struct LocalStaticScheduler { /* private fields */ }

A statically-initialized scheduler for !Send tasks.

This type is identical to the StaticScheduler type, except that it is capable of scheduling Futures that do not implement Send. Because this scheduler’s futures cannot be moved across threads¹, the scheduler itself is also !Send and !Sync, as ticking it from another thread would cause its tasks to be polled from that thread, violating the Send and Sync contracts.

---

1. Or CPU cores, in bare-metal systems. ↩

Implementations

impl LocalStaticScheduler

pub const DEFAULT_TICK_SIZE: usize = 256usize

How many tasks are polled per call to LocalStaticScheduler::tick.

Chosen by fair dice roll, guaranteed to be random.

pub const unsafe fn new_with_static_stub(stub: &'static TaskStub) -> Self

Create a LocalStaticScheduler with a static “stub” task entity

This is used for creating a LocalStaticScheduler as a static variable.

Safety

The “stub” provided must ONLY EVER be used for a single LocalStaticScheduler. Re-using the stub for multiple schedulers may lead to undefined behavior.

For a safe alternative, consider using the new_static! macro to initialize a LocalStaticScheduler in a static variable.

pub fn spawn_allocated<F, STO>( &'static self, task: STO::StoredTask, ) -> JoinHandle<F::Output>

where F: Future + 'static, F::Output: 'static, STO: Storage<&'static Self, F>,

Spawn a pre-allocated, task.

Unlike StaticScheduler::spawn_allocated, this method is capable of spawning Futures which do not implement Send.

This method is used to spawn a task that requires some bespoke procedure of allocation, typically of a custom Storage implementor. See the documentation for the Storage trait for more details on using custom task storage.

This method returns a JoinHandle that can be used to await the task’s output. Dropping the JoinHandle detaches the spawned task, allowing it to run in the background without awaiting its output.

When tasks are spawned on a scheduler, the scheduler must be ticked in order to drive those tasks to completion. See the module-level documentation for more information on implementing a system’s run loop.

pub fn build_task<'a>(&'static self) -> Builder<'a, &'static Self>

Returns a new task Builder for configuring tasks prior to spawning them on this scheduler.

To spawn !Send tasks using a Builder, use the Builder::spawn_local method.

pub fn current_task(&'static self) -> Option<TaskRef>

Returns a TaskRef referencing the task currently being polled by this scheduler, if a task is currently being polled.

Returns

• Some(TaskRef) referencing the currently-polling task, if a task is currently being polled (i.e., the scheduler is ticking and the queue of scheduled tasks is non-empty).

• None if the scheduler is not currently being polled (i.e., the scheduler is not ticking or its run queue is empty and all polls have completed).

pub fn tick(&'static self) -> Tick

Tick this scheduler, polling up to Self::DEFAULT_TICK_SIZE tasks from the scheduler’s run queue.

Only a single CPU core/thread may tick a given scheduler at a time. If another call to tick is in progress on a different core, this method will immediately return.

See the module-level documentation for more information on using this function to implement a system’s run loop.

Returns

A Tick struct with data describing what occurred during the scheduler tick.

pub fn spawner(&'static self) -> LocalStaticSpawner

Returns a new LocalStaticSpawner that can be used by other threads to spawn Send tasks on this scheduler.

impl LocalStaticScheduler

pub fn new() -> Self

Returns a new LocalStaticScheduler with a heap-allocated stub task.

Unlike LocalStaticScheduler::new_with_static_stub, this is not a const fn, as it performs a heap allocation for the stub task. However, the returned StaticScheduler must still be stored in a static variable in order to be used.

This method is generally used with lazy initialization of the scheduler static.

pub fn spawn<F>(&'static self, future: F) -> JoinHandle<F::Output>

where F: Future + 'static, F::Output: 'static,

Spawn a task.

This method returns a JoinHandle that can be used to await the task’s output. Dropping the JoinHandle detaches the spawned task, allowing it to run in the background without awaiting its output.

When tasks are spawned on a scheduler, the scheduler must be ticked in order to drive those tasks to completion. See the module-level documentation for more information on implementing a system’s run loop.

Trait Implementations

impl Debug for LocalStaticScheduler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LocalStaticScheduler

fn default() -> LocalStaticScheduler

Returns the “default value” for a type.

impl Schedule for &'static LocalStaticScheduler

fn schedule(&self, task: TaskRef)

Schedule a task on this scheduler.

fn current_task(&self) -> Option<TaskRef>

Returns a TaskRef referencing the task currently being polled by this scheduler, if a task is currently being polled.

fn build_task<'a>(&self) -> Builder<'a, Self>

Returns a new task Builder for configuring tasks prior to spawning them on this scheduler.