Struct maitake::scheduler::LocalScheduler

source ·
pub struct LocalScheduler { /* private fields */ }
Available on crate feature alloc only.
Expand description

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 threads1, 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§

source§

impl LocalScheduler

source

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.

source

pub fn new() -> Self

Returns a new LocalScheduler.

source

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();
source

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 {}
source

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.

source

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).

source

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.

source

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§

source§

impl Clone for LocalScheduler

source§

fn clone(&self) -> LocalScheduler

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for LocalScheduler

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for LocalScheduler

source§

fn default() -> LocalScheduler

Returns the “default value” for a type. Read more
source§

impl Schedule for LocalScheduler

source§

fn schedule(&self, task: TaskRef)

Schedule a task on this scheduler. Read more
source§

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.
source§

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

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

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more