Async programs
Every component call normally blocks: your program stops until the answer comes back, and an indirect call (a file read, a robot move, an internet read) takes a whole server tick. That’s how Lua works too.
With the async feature, wackasm-opencomputers adds an executor and a
non-blocking version of every call. The call is queued, your program keeps
running, and the result arrives later. That lets one program wait on many
things at once: several downloads, a timer, the keyboard and a redstone
change.
The feature is optional. Without it nothing changes, and with it the
blocking API, std::fs, println! and everything else still work as
before.
A first async program
Section titled “A first async program”task::run runs a future, and the tasks it spawns, until that future
finishes. Inside it:
| does | |
|---|---|
gpu.set_async(...), robot.move_async(...), … |
every component method has an _async twin returning a future |
component::invoke_async(address, method, args) |
an untyped call, for components the wrappers don’t know |
task::spawn(future) |
runs a task alongside this one; await the JoinHandle for its result |
task::join(a, b), task::join_all(futures) |
waits for several futures at once |
task::sleep(duration) |
waits game time without holding up other tasks |
task::timeout(duration, future) |
gives up on a future after a while |
task::signal(filter), task::next_signal() |
the next signal that matches; see below |
task::yield_now() |
lets other tasks run |
Internet
Section titled “Internet”The internet API has async versions too:
internet::get_async(url), Request::send_async(),
Response::read_async(buf) and read_to_end_async(vec),
TcpStream::connect_async, read_async, write_async and
write_all_async. Since the card downloads in the background on the server,
several requests really are in flight at once:
The fetch program on the shell floppy does this: fetch URL URL URL.
How it runs
Section titled “How it runs”- Calls run on the server in the order they were made, so three
gpu.set_asynccalls draw in order. A blocking call made after async ones waits for them. - Direct calls run as soon as the program next waits. Indirect calls run on
the server tick, as many per tick as the server’s
asyncCallsPerTickallows. The default of 1 matches Lua; servers can raise it so programs overlap several indirect calls in one tick. - A process can have 64 calls outstanding at once. Past that, a call fails with an error instead of queuing.
- Dropping a future cancels its call: if it hasn’t run yet, it never will.
- Everything survives a world save, including calls still in the queue.
Signals
Section titled “Signals”Signals are one queue shared by the whole program, and taking a signal
removes it. Inside task::run, use task::signal: each signal goes to the
first task waiting for one that matches, and signals nobody is waiting for
are kept (up to 256) for whoever asks next. Don’t call signal::pull inside
task::run, because it would take signals other tasks are waiting for.
Blocking calls inside tasks
Section titled “Blocking calls inside tasks”Blocking calls still work inside tasks: the blocking component methods,
std::fs, println!, reading stdin, and running other
programs. While one runs, no other task does,
so in code with other tasks to keep going, prefer the _async versions.
The full API is in the reference for task.
The ABI underneath
Section titled “The ABI underneath”The executor is built on five oc imports:
invoke_async, invoke_value_async, completion_next, cancel and
wait_ms. Programs in other languages can use them directly.