Struct maitake::scheduler::Scheduler

pub struct Scheduler(/* private fields */);

Available on crate feature alloc only.

An atomically reference-counted single-core scheduler implementation.

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.

Implementations

impl Scheduler

pub fn try_steal(&self) -> Result<Stealer<'_, Scheduler>, TryStealError>

Attempt to steal tasks from this scheduler’s run queue.

Returns

• Ok(Stealer`)) if tasks can be stolen from this scheduler’s queue.
• Err(TryStealError::Empty) if there were no tasks in this scheduler’s run queue.
• Err(TryStealError::Busy) if another worker was already stealing from this scheduler’s run queue.

impl Scheduler

pub const DEFAULT_TICK_SIZE: usize = 256usize

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

Chosen by fair dice roll, guaranteed to be random.

pub fn new() -> Self

Returns a new Scheduler.

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

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

Examples

use maitake::scheduler::Scheduler;

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

scheduler.tick();

Multiple tasks can be spawned using the same Builder:

use maitake::scheduler::Scheduler;

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

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

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

scheduler.tick();

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

where F: Future + Send + 'static, F::Output: Send + '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.

Examples

Spawning a task and awaiting its output:

use maitake::scheduler::Scheduler;

let scheduler = Scheduler::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::Scheduler;

let scheduler = Scheduler::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>( &'static self, task: Box<Task<Self, F, BoxStorage>> ) -> JoinHandle<F::Output>

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

Spawn a pre-allocated 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.

Trait Implementations

impl Clone for Scheduler

fn clone(&self) -> Scheduler

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Scheduler

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

Formats the value using the given formatter.

impl Default for Scheduler

fn default() -> Scheduler

Returns the “default value” for a type.

impl Schedule for Scheduler

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.