API referencestd/embedded

std/embedded/executor

Public declarations, types, methods, and source contracts for std/embedded/executor.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/embedded/executor"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
cpu core/cpu executor.dodo
hal std/embedded/hal executor.dodo

MAX_TASKS

Constant · Source

Tasks one executor runs, signals a program can number, and cores that can each run an executor.

pub const MAX_TASKS: usize = 32

MAX_SIGNALS

Constant · Source

pub const MAX_SIGNALS: u32 = 32

MAX_CORES

Constant · Source

pub const MAX_CORES: u32 = 2

Poll

Enum · Source

What a poll reports: Pending to be polled again, Ready when the task is done and is not polled again.

pub enum Poll {
    Pending,
    Ready
}

Task

Interface · Source

A unit of work the executor runs. Implemented by any value with this method; see the package comment.

pub interface Task {
    fn poll(&mut self, cx: &mut Context) -> Poll
}

Clock

Interface · Source

Where the time comes from and how the core sleeps. A chip’s timer alarm implements it on hardware, std/embedded/hal/fake.Clock on a desktop.

pub interface Clock {
    // Microseconds since some fixed start; never decreases.
    fn now_us(&self) -> u64
    // Sleep until an interrupt is pending or the time reaches `deadline`,
    // whichever comes first; none waits for an interrupt only. Returning
    // earlier is allowed. The executor calls this with interrupts masked, so
    // an interrupt that arrives before or during the sleep still ends it,
    // and its handler runs once the executor lifts the mask.
    fn sleep_until(&mut self, deadline: Option<u64>)
}

Context

Struct · Source

What a task sees while it is polled: the time, and where it records when to be polled again.

pub struct Context {
    // Private implementation fields omitted.
}

Context.new

Function · Source

A context at time now_us belonging to no executor, for calling a task’s poll directly in a test. Signals taken through it register no waiting task; wake_time reports what the task asked for.

pub fn new(now_us: u64) -> Context

Context.now_us

Function · Source

The time the poll started, in the clock’s microseconds.

pub fn now_us(&self) -> u64

Context.task

Function · Source

The polled task’s position in the executor’s task list.

pub fn task(&self) -> u32

Context.wake_at

Function · Source

Poll this task again once the clock reaches time_us. Of several requests the earliest counts; a time already past polls it again right after the tasks that are due now.

pub fn wake_at(&mut self, time_us: u64)

Context.wake_in

Function · Source

Poll this task again microseconds from the start of this poll.

pub fn wake_in(&mut self, microseconds: u64)

Context.wake_in_ms

Function · Source

Poll this task again milliseconds from the start of this poll.

pub fn wake_in_ms(&mut self, milliseconds: u32)

Context.yield_now

Function · Source

Poll this task again as soon as the other due tasks have run, for work split into steps that should not delay them.

pub fn yield_now(&mut self)

Context.wake_time

Function · Source

The earliest time requested so far in this poll.

pub fn wake_time(&self) -> Option<u64>

Signal

Struct · Source

An event that interrupt handlers or tasks raise and tasks wait for, numbered by the program: const RX: executor.Signal = executor.Signal { id: 1 }. A signal counts raises until a task takes them, and keeps the last value sent with it. Raising wakes every task that took the signal since it was last raised. Each id is one signal wherever it is used; an id of MAX_SIGNALS or more traps when used.

pub struct Signal {
    pub id: u32
}

Signal.raise

Function · Source

Record one occurrence and wake the waiting tasks. Safe in interrupt handlers. The count stops at the largest u32.

pub fn raise(&self)

Signal.send

Function · Source

raise, keeping value for receive; a later value replaces it.

pub fn send(&self, value: u32)

Signal.take

Function · Source

True if the signal was raised since it was last taken, which it now is. Either way the polled task waits for the next raise, so a task that takes its signal on every poll never misses one.

pub fn take(&self, cx: &mut Context) -> bool

Signal.take_count

Function · Source

How many times the signal was raised since it was last taken, and take it, as take does.

pub fn take_count(&self, cx: &mut Context) -> u32

Signal.receive

Function · Source

The last value sent, if the signal was raised since it was last taken; takes it, as take does.

pub fn receive(&self, cx: &mut Context) -> Option<u32>

Signal.is_raised

Function · Source

True if the signal was raised since it was last taken. Takes nothing and waits for nothing.

pub fn is_raised(&self) -> bool

Signal.reset

Function · Source

Forget raises, the value, and waiting tasks, for example before a test or when a program restarts the work the signal belongs to.

pub fn reset(&self)

Signal.wait

Function · Source

A future that is ready once the signal is raised, or at once if it was raised since it was last taken: count := await BUTTON.wait().

pub fn wait(&self) -> SignalWait

Signal.next_value

Function · Source

A future that is ready with the value of the next send: value := await READING.next_value().

pub fn next_value(&self) -> SignalValue

Ticker

Struct · Source

Periodic work: ready is true once per period. The first tick comes one period after the first call. Ticks keep their schedule, so the period does not drift with how late a poll runs; ticks missed entirely, because the task was not polled for longer than a period, count as one.

pub struct Ticker {
    // Private implementation fields omitted.
}

Ticker.every

Function · Source

A ticker with a period of microseconds, at least 1.

pub fn every(microseconds: u64) -> Ticker

Ticker.every_ms

Function · Source

A ticker with a period of milliseconds, at least 1.

pub fn every_ms(milliseconds: u32) -> Ticker

Ticker.period_us

Function · Source

pub fn period_us(&self) -> u64

Ticker.ready

Function · Source

True if a tick is due, which it then consumes. Either way the polled task is woken for the next tick.

pub fn ready(&mut self, cx: &mut Context) -> bool

Ticker.reset

Function · Source

Start over: the next tick comes one period after the next call.

pub fn reset(&mut self)

Ticker.tick

Function · Source

A future that is ready at the next tick, for async code: await ticker.tick().

pub fn tick(&mut self) -> Tick

Timer

Struct · Source

A one-shot deadline: start it, and expired turns true once when the time comes. A stopped timer never expires.

pub struct Timer {
    // Private implementation fields omitted.
}

Timer.new

Function · Source

pub fn new() -> Timer

Timer.start

Function · Source

Expire microseconds after the start of the current poll, replacing any earlier deadline, and wake the polled task then.

pub fn start(&mut self, cx: &mut Context, microseconds: u64)

Timer.start_ms

Function · Source

pub fn start_ms(&mut self, cx: &mut Context, milliseconds: u32)

Timer.start_at

Function · Source

Expire at clock time time_us.

pub fn start_at(&mut self, cx: &mut Context, time_us: u64)

Timer.stop

Function · Source

pub fn stop(&mut self)

Timer.is_running

Function · Source

True from start until it expires or is stopped.

pub fn is_running(&self) -> bool

Timer.expired

Function · Source

True once, when the deadline has passed; the timer then stops. While it runs, the polled task is woken at the deadline.

pub fn expired(&mut self, cx: &mut Context) -> bool

Executor

Struct · Source

Runs tasks until they are all done, keeping what it knows about them between calls of run_until, so a test can advance in steps.

pub struct Executor {
    // Private implementation fields omitted.
}

Executor.new

Function · Source

pub fn new() -> Executor

Executor.run

Function · Source

Run until every task is done. Firmware whose tasks never finish stays here. Traps for more than MAX_TASKS tasks. Pass the same tasks in the same order on every call.

pub fn run<C: Clock>(&mut self, tasks: &mut[&mut dyn Task], clock: &mut C)

Executor.run_until

Function · Source

Run until every task is done, true, or the clock reaches end_us, false.

pub fn run_until<C: Clock>(&mut self, tasks: &mut[&mut dyn Task], clock: &mut C, end_us: u64) -> bool

Executor.polls

Function · Source

Polls so far, over all tasks.

pub fn polls(&self) -> u64

Executor.sleeps

Function · Source

Times the executor asked the clock to sleep.

pub fn sleeps(&self) -> u64

Executor.is_finished

Function · Source

Whether task index returned Ready.

pub fn is_finished(&self, index: usize) -> bool

run

Function · Source

Run tasks with a new executor until they are all done; see Executor.run.

pub fn run<C: Clock>(tasks: &mut[&mut dyn Task], clock: &mut C)

Sleep

Struct · Source

Waits until a time: await executor.sleep_ms(250). The time is counted from the first poll, which is when the awaiting code reaches it.

pub struct Sleep {
    // Private implementation fields omitted.
}

Sleep.poll

Function · Source

pub fn poll(&mut self, cx: &mut Context) -> Poll

sleep

Function · Source

Wait microseconds.

pub fn sleep(microseconds: u64) -> Sleep

sleep_ms

Function · Source

Wait milliseconds.

pub fn sleep_ms(milliseconds: u32) -> Sleep

sleep_until

Function · Source

Wait until the clock reaches time_us; a time already past is ready at once.

pub fn sleep_until(time_us: u64) -> Sleep

YieldNow

Struct · Source

Lets the other due tasks run first: await executor.yield_now() splits long work into steps.

pub struct YieldNow {
    // Private implementation fields omitted.
}

YieldNow.poll

Function · Source

pub fn poll(&mut self, cx: &mut Context) -> Poll

yield_now

Function · Source

pub fn yield_now() -> YieldNow

Now

Struct · Source

The time, without waiting: now := await executor.now() is the clock’s microseconds when the current poll started, as cx.now_us() is for a hand-written task. Code that ran earlier in the same poll is not counted in it; await executor.yield_now() first starts a new poll.

pub struct Now {
    // Private implementation fields omitted.
}

Now.poll

Function · Source

pub fn poll(&mut self, cx: &mut Context) -> Poll

Now.output

Function · Source

pub fn output(&mut self) -> u64

now

Function · Source

pub fn now() -> Now

Tick

Struct · Source

The next tick of a Ticker: await ticker.tick(). Ticks keep the ticker’s schedule however long the code between them takes.

pub struct Tick {
    // Private implementation fields omitted.
}

Tick.poll

Function · Source

pub fn poll(&mut self, cx: &mut Context) -> Poll

SignalWait

Struct · Source

The next raise of a signal: count := await BUTTON.wait(). A raise since the signal was last taken counts, so code that waits in a loop never misses one. The output is the number of raises taken.

pub struct SignalWait {
    // Private implementation fields omitted.
}

SignalWait.poll

Function · Source

pub fn poll(&mut self, cx: &mut Context) -> Poll

SignalWait.output

Function · Source

pub fn output(&mut self) -> u32

SignalValue

Struct · Source

The value sent with the next raise of a signal: value := await RX.next_value().

pub struct SignalValue {
    // Private implementation fields omitted.
}

SignalValue.poll

Function · Source

pub fn poll(&mut self, cx: &mut Context) -> Poll

SignalValue.output

Function · Source

pub fn output(&mut self) -> u32

Which

Enum · Source

Which of two futures of a select finished first.

pub enum Which {
    First,
    Second
}

Select

Struct · Source

Waits for whichever of two futures is ready first, and drops the other:

match await executor.select(BUTTON.wait(), executor.sleep_ms(500)) { executor.Which.First => pressed(), executor.Which.Second => timed_out(), }

The first is polled first, so when both are ready it wins.

pub struct Select<A: Task, B: Task> {
    // Private implementation fields omitted.
}

Select.poll

Function · Source

pub fn poll(&mut self, cx: &mut Context) -> Poll

Select.output

Function · Source

pub fn output(&mut self) -> Which

select

Function · Source

pub fn select<A: Task, B: Task>(first: A, second: B) -> Select<A, B> from(first, second)

Join

Struct · Source

Runs two futures together until both are done: await executor.join(a, b). Their outputs are dropped; let them store results through references.

pub struct Join<A: Task, B: Task> {
    // Private implementation fields omitted.
}

Join.poll

Function · Source

pub fn poll(&mut self, cx: &mut Context) -> Poll

join

Function · Source

pub fn join<A: Task, B: Task>(first: A, second: B) -> Join<A, B> from(first, second)

Search every guide, reference page, and API declaration.