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.Clockon 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_usbelonging 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
microsecondsfrom the start of this poll.
pub fn wake_in(&mut self, microseconds: u64)
Context.wake_in_ms
Function · Source
Poll this task again
millisecondsfrom 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, keepingvalueforreceive; 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
takedoes.
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
takedoes.
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:
readyis 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:
startit, andexpiredturns 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
microsecondsafter 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
indexreturned Ready.
pub fn is_finished(&self, index: usize) -> bool
run
Function · Source
Run
taskswith 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, ascx.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
selectfinished 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)