Struct LocalScheduler

pub struct LocalScheduler { /* private fields */ }

A reference-counted scheduler for !Send tasks.

This type is identical to the LocalScheduler 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 multiple threads would move ownership of a !Send future.

This type stores the core of the scheduler inside an Arc, which is cloned by each task spawned on the scheduler. The use of Arc allows schedulers to be created and dropped dynamically at runtime. This is in contrast to the StaticScheduler type, which must be stored in a static variable for the entire lifetime of the program.

Due to the use of Arc, this type requires the “alloc” feature flag to be enabled.

---

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

Implementations

impl LocalScheduler

pub const DEFAULT_TICK_SIZE: usize = 256usize

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

Chosen by fair dice roll, guaranteed to be random.

pub fn new() -> Self

Returns a new LocalScheduler.

pub fn build_task<'a>(&self) -> Builder<'a, 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.

Examples

use maitake::scheduler::LocalScheduler;

let scheduler = LocalScheduler::new();
scheduler.build_task().name("hello world").spawn_local(async {
    // ...
});

scheduler.tick();

Multiple tasks can be spawned using the same Builder:

use maitake::scheduler::LocalScheduler;

let scheduler = LocalScheduler::new();
let builder = scheduler
    .build_task()
    .kind("my_cool_task");

builder.spawn_local(async {
    // ...
});

builder.spawn_local(async {
    // ...
});

scheduler.tick();

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

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

Spawn a !Send 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.

Examples

Spawning a task and awaiting its output:

use maitake::scheduler::LocalScheduler;

let scheduler = LocalScheduler::new();

// spawn a new task, returning a `JoinHandle`.
let task = scheduler.spawn(async move {
    // ... do stuff ...
   42
});

// spawn another task that awaits the output of the first task.
scheduler.spawn(async move {
    // await the `JoinHandle` future, which completes when the task
    // finishes, and unwrap its output.
    let output = task.await.expect("task is not cancelled");
    assert_eq!(output, 42);
});

// run the scheduler, driving the spawned tasks to completion.
while scheduler.tick().has_remaining {}

Spawning a task to run in the background, without awaiting its output:

use maitake::scheduler::LocalScheduler;

let scheduler = LocalScheduler::new();

// dropping the `JoinHandle` allows the task to run in the background
// without awaiting its output.
scheduler.spawn(async move {
    // ... do stuff ...
});

// run the scheduler, driving the spawned tasks to completion.
while scheduler.tick().has_remaining {}

pub fn spawn_allocated<F>( &self, task: Box<Task<Self, F, BoxStorage>>, ) -> JoinHandle<F::Output>

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

Spawn a pre-allocated !Send task.

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 current_task(&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(&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(&self) -> LocalSpawner

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

Trait Implementations

impl Clone for LocalScheduler

fn clone(&self) -> LocalScheduler

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LocalScheduler

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

Formats the value using the given formatter.

impl Default for LocalScheduler

fn default() -> LocalScheduler

Returns the “default value” for a type.

impl Schedule for LocalScheduler

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.