zena:wasm
zena
import {…} from 'zena:wasm';
Running other Wasm programs, for programs the zena command's host
runs: zena-cli:host/wasm as the compiler synthesizes it from the
host's WIT. The test runner runs each compiled test this way. The
host grants it together with process spawning; anywhere else the
imports are stubs that trap.
A program is a component or a core module, and the host tells them
apart from the file itself. A core module — a freestanding build,
hand-written .wat, another language's output — runs with no
imports, so arguments, environment, directories and the grant do not
reach it, and it has no output to capture. The rest of this module's
documentation says "component" for the program being run.
Examples
zena
import { runModule } from 'zena:wasm';
let result = runModule('out/hello.wasm', {args: ['hello', 'world']});
console.log(`${result.outcome} ${result.exitCode}`);
Classes
RunResult
zena
class RunResult
What a run produced.
Constructors
zena
new()
Properties
zena
outcome: RunOutcome
zena
exitCode: i32
The status the component ended with: the i32 its exported
function returned, the code it passed to exit, or 0 when the
function returns nothing. -1 when it trapped, timed out or failed
to start.
zena
resultText: String
What the exported function returned, formatted the way zena run
prints it (7, 2.5); '' when it returned nothing or did not
return.
zena
message: String
Why a run trapped, timed out or failed to start; otherwise ''.
zena
stdout: String
What the component wrote, when its output was captured; otherwise ''.
zena
stderr: String
zena
callTime: Duration
How long the exported call took. Loading and instantiating the component are not included, so this is the number a benchmark wants.
Methods
zena
succeeded(): boolean
True when the component returned or exited with status 0.
Run
zena
resource class Run extends Resource
A run in progress: a resource over the host's handle, held as
Own<Run> and released when the owner leaves scope.
Enums
RunOutcome
zena
enum RunOutcome
How a run ended.
Members
zena
Returned
The exported function returned. exitCode is the i32 it returned,
and resultText its first result however typed.
zena
Exited
The component ended itself with exit(code); exitCode is the code.
zena
Trapped
The component trapped. message has the trap and its backtrace.
zena
TimedOut
The run was stopped at its time limit.
zena
Failed
The component did not start: it could not be read, compiled, linked
or instantiated, or a path it was given is outside what this
program can reach. message says which.
Type aliases
DirMapping
zena
type DirMapping = {from: String, to: String}
A directory of this program's, from, preopened for the run as to.
RunOptions
zena
type RunOptions = {args?: Array<String>, env?: Map<String, String>, inheritEnv?: boolean, dirs?: Array<DirMapping>, invoke?: String, inheritStdio?: boolean, grant?: boolean, grantExtensions?: boolean, debug?: boolean, timeout?: Duration}
How to run a component. Every field is optional.
Functions
startModule
zena
function startModule(path: String, options: RunOptions = {}): Own<Run>
Start a component and return at once.
runModule
zena
function runModule(path: String, options: RunOptions = {}): RunResult
Run a component to its end.
precompileModule
zena
function precompileModule(path: String, debug: boolean = false): String
Write a component's ahead-of-time compiled form beside it, so its first run skips compilation. Returns '' or why it could not.