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

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 functionWhat it does
interfacesThe process's interfaces: index, name, MAC address, MTU, link-local address, VPC prefix.
sendQueue 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-secondsA monotonic clock in nanoseconds; the wall clock in seconds.
set-timer, cancel-timerWake the process at a time of now. At most 16 timers; setting an id again replaces it.
state-get, state-setRead and replace the durable state.
configLook up a setting from the process's config.
randomUp to 4096 random bytes.
logA log line (level 0 to 3), kept in the process's status.logs.
reportPublish 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.deleteRead, write (also create-only) and delete objects in the buckets listed in the process's spec.buckets; any other bucket is refused.
HandlerCalled
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

Next

Run a program as a process registers this file and gives it an interface on a VPC.