Guides / Compute
Write your first program
Read this before you write a Compute program. It explains how a program runs and what it can ask of the host, then walks through the smallest program that does something.
A program is a small WebAssembly module that works on Ethernet frames. It does not run all the time. It wakes when a frame arrives, when a timer it set expires or when a schedule ticks, does its work, and goes back to sleep.
How a program runs
- Each wake-up is one activation. The module is instantiated afresh, the handlers that apply are called in a fixed order (
start,scheduled,timer,frames), and the instance is dropped. Memory does not survive unless the process is resident (see Run a program as a process). Anything the program must keep goes into its state, up to 1 MiB, set withstate-set. - An activation takes effect completely or not at all. If it finishes, its state, frames and timers take effect together. If it traps or runs too long, none of them do, and the frames it was given are lost, like packets on a failing network card.
- An activation runs in slices of about a millisecond, so that no program starves another. One that does not finish within a second is stopped.
- Frames are Ethernet II datagrams of 14 to MTU + 14 bytes. A program can send only frames whose source address is the one allocated to the interface, and a frame can be lost on the way.
What the host offers and what you export
A program imports functions from etorm:compute/host@0.1.0 and exports handlers under etorm:compute/handler@0.1.0#<name>, using the canonical ABI for lists, strings and results.
| Host function | What it does |
|---|---|
interfaces | The process's interfaces: index, name, MAC address, MTU, link-local address, VPC prefix. |
send | Queue a frame on an interface. Returns an error for an unknown interface, a frame that is too large, a wrong source address or a full queue. |
now, unix-seconds | A monotonic clock in nanoseconds; the wall clock in seconds. |
set-timer, cancel-timer | Wake the process at a time of now. At most 16 timers; setting an id again replaces it. |
state-get, state-set | Read and replace the durable state. |
config | Look up a setting from the process's config. |
random | Up to 4096 random bytes. |
log | A log line (level 0 to 3), kept in the process's status.logs. |
report | Publish a text value under a key in the process's status.reported (4 KiB in all, the last values written). |
objects.get, objects.put, objects.delete | Read, write (also create-only) and delete objects in the buckets listed in the process's spec.buckets; any other bucket is refused. |
| Handler | Called |
|---|---|
start(reason) | Once per life: when the process is created (0), resumed (1), restarted (2) or continued from a snapshot (3). |
frames(batch) | With up to 64 frames, oldest first, each with its interface index. |
timer(id) | When a timer set by the program is due. |
scheduled(name, due, missed) | When a schedule of the process ticks (see Wake a process on a timer or a schedule). |
stop() | Before the process is suspended, stopped or replaced; a small allowance to save state. |
A program implements only the handlers it needs. It must export memory, with a declared maximum of at most 4096 pages, and cabi_realloc. It must not have a start function. It may import only the functions above (the object functions need the matching spec.buckets). Any other import is refused when you register the program, and the message names it.
Write the smallest program, a reflector
This program answers every frame with the same frame, with destination and source swapped. It is written in the WebAssembly text format, and any assembler turns it into a .wasm file.
(module
(import "etorm:compute/host@0.1.0" "send" (func $send (param i32 i32 i32 i32)))
(memory (export "memory") 1 1) ;; one 64 KiB page: fits the smallest allowance
(global $heap (mut i32) (i32.const 4096))
(func (export "cabi_realloc") (param i32 i32 i32 i32) (result i32)
(local $p i32)
(local.set $p (i32.and (i32.add (global.get $heap) (i32.sub (local.get 2) (i32.const 1)))
(i32.xor (i32.sub (local.get 2) (i32.const 1)) (i32.const -1))))
(global.set $heap (i32.add (local.get $p) (local.get 3)))
(local.get $p))
(func (export "etorm:compute/handler@0.1.0#frames") (param $ptr i32) (param $len i32)
(local $e i32) (local $d i32) (local $n i32) (local $i i32)
(local.set $e (local.get $ptr))
(local.set $d (i32.load offset=4 (local.get $e))) ;; address of the frame's bytes
(local.set $n (i32.load offset=8 (local.get $e))) ;; its length
(loop $copy ;; copy the frame to address 600
(i32.store8 (i32.add (i32.const 600) (local.get $i)) (i32.load8_u (i32.add (local.get $d) (local.get $i))))
(local.set $i (i32.add (local.get $i) (i32.const 1)))
(br_if $copy (i32.lt_u (local.get $i) (local.get $n))))
(local.set $i (i32.const 0))
(loop $swap ;; swap destination and source
(i32.store8 (i32.add (i32.const 600) (local.get $i)) (i32.load8_u (i32.add (local.get $d) (i32.add (i32.const 6) (local.get $i)))))
(i32.store8 (i32.add (i32.const 606) (local.get $i)) (i32.load8_u (i32.add (local.get $d) (local.get $i))))
(local.set $i (i32.add (local.get $i) (i32.const 1)))
(br_if $swap (i32.lt_u (local.get $i) (i32.const 6))))
(call $send (i32.load (local.get $e)) (i32.const 600) (local.get $n) (i32.const 64))))
This example answers only the first frame of each batch. A real program loops over all len frames. Frames sent to a multicast address are delivered to every process on the VPC, and the reflector's reply to one would carry that multicast address as its source, so send refuses it. A real program checks the result.
Limits
- A module is at most 256 KiB, and its declared memory at most 256 MiB. Programs the platform itself provides are larger, and every project can use them with
programRef.system. A process has at most 8 interfaces. - Each process is given a memory and processor allowance (64 KiB times a power of two, and a share of a core). The memory a program declares at start must fit in it, and growing past it fails the activation. A program that fits in one 64 KiB page can run in the smallest allowance.
- State is at most 1 MiB. The limit a process enforces is its
stateMaxBytes, 64 KiB by default. Config holds at most 64 entries and 16 KiB. - Each interface queues 256 frames in each direction. A full queue drops the newest frames and counts them in
status.usage.framesDropped. - A process wakes at most 100 times a second.
Next
Run a program as a process registers this file and gives it an interface on a VPC.