Expand description
A small single-threaded async executor driven by OpenComputers: tasks
wait on component calls, signals and timers, and the computer sleeps until
one of them is ready. Enable the crate’s async feature to use it.
use std::time::Duration;
use wackasm_opencomputers::{prelude::*, task};
task::run(async {
// A background task: blink a cursor in the corner every half second.
task::spawn(async {
let gpu = Gpu::first().expect("no GPU");
let mut on = false;
loop {
on = !on;
let _ = gpu.set_async(1, 1, if on { "_" } else { " " }, None).await;
task::sleep(Duration::from_millis(500)).await;
}
});
// Meanwhile: two component calls in flight at once, then wait for a key.
let gpu = Gpu::first().expect("no GPU");
let (resolution, depth) = task::join(gpu.get_resolution_async(), gpu.get_depth_async()).await;
println!("{resolution:?} at depth {depth:?}");
let key = task::signal(|s| matches!(s, Signal::KeyDown { .. })).await;
println!("pressed {key:?}");
});§How it works
The _async methods queue their component call with the architecture and
return a future at once; the call runs on the server while the program
keeps going, and the future completes when the result comes back. Calls
run in the order they were made. A direct call runs as soon as the program
next waits; indirect calls run on the server tick, as many per tick as the
server’s asyncCallsPerTick allows (1 by default, like Lua).
run polls every task that is ready, then waits for whatever comes
first: a completed call, a signal, or the next timer. Signals go to the
first task waiting for one that matches (signal); signals nobody is
waiting for are kept (up to 256) for later.
Everything blocking still works inside tasks: std::fs, println!,
reading stdin, the blocking component methods and crate::process.
While one runs, though, no other task does, so prefer the _async
versions in code that has other tasks to keep going. Don’t call
crate::signal::pull inside run: it would take signals other tasks
are waiting for. Use signal.
Structs§
- Call
- A component call in flight; see
component::invoke_async. - Join
Handle - A spawned task’s output. Awaiting it waits for the task; dropping it lets the task run on without anyone collecting the output.
- Next
Signal - The future
signalreturns. - Sleep
- The future
sleepreturns.
Functions§
- join
- Waits for both futures, running them at the same time.
- join_
all - Waits for every future, running them at the same time. The outputs are in the same order as the futures.
- next_
signal - The next signal of any kind.
- run
- Runs
futureto completion, along with any tasks itspawns, and returns its output. Tasks still running when it finishes are dropped. - signal
- The next signal that
filteraccepts. Signals that arrived earlier and that no task was waiting for count too, oldest first. - sleep
- Waits for
durationof game time without holding up other tasks. - spawn
- Starts
futureas a separate task, which runs while this one waits. - timeout
future’s output, orErr(Error::Failed("timed out"))ifdurationpasses first (futureis then dropped, cancelling its calls).- yield_
now - Lets other tasks run before continuing.