zena:wasm

zena

import {…} from 'zena:wasm';

zena:wasm — running other Wasm modules and waiting for their results.

A module cannot start a Wasm engine by itself, so this is a host import (wasm module zena_wasm), provided by the zena-cli and zena-run hosts, and available only on the zena-cli target. It is granted together with zena:process: a program that may spawn processes may also run modules, and one that may not gets imports that trap at the first call.

zena

import { runModule } from 'zena:wasm';

let result = runModule('out/array_test.wasm', {
  args: ['array_test'],
  dirs: [{from: '.', to: '.'}],
});
if (!result.succeeded()) {
  console.error(result.stdout);
  console.error(result.message);
}

Each run gets a fresh store on its own host thread. startModule returns straight away, so several modules can run at once; wait blocks until one ends. A trap is reported in the result and does not affect the caller.

Paths — the module's, and each directory handed to it — are in this program's own view of the filesystem and are translated through its preopens. A path outside them, or with a .. segment, makes the run fail to start: a program can pass on only what it can reach itself.

Classes

RunResult

zena

class RunResult

What a finished run produced.

Constructors

zena

new()

Properties

zena

outcome: RunOutcome

zena

exitCode: i32

The status the module 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 module wrote, when its output was captured; otherwise ''.

zena

stderr: String

zena

callTime: Duration

How long the exported call took. Loading and instantiating the module are not included, so this is the number a benchmark wants.

Methods

zena

succeeded(): boolean

True when the module returned or exited with status 0.

Run

zena

final class Run

A started run. wait blocks until it ends; waiting again returns the same result.

Constructors

zena

new(run: RunRef)

Methods

zena

wait(): RunResult

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 module ended itself with exit(code); exitCode is the code.

zena

Trapped

The module trapped. message has the trap and its backtrace.

zena

TimedOut

The run was stopped at its time limit.

zena

Failed

The module 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 handed to a module: from in this program's view of the filesystem, appearing as to in the module's. {from: '.', to: '.'} shares this program's working directory.

RunOptions

zena

type RunOptions = {args?: Array<String>, env?: Map<String, String>, inheritEnv?: boolean, dirs?: Array<DirMapping>, invoke?: String, inheritStdio?: boolean, grant?: boolean, debug?: boolean, timeout?: Duration}

How to run a module. Every field may be left out.

Functions

startModule

zena

function startModule(path: String, options: RunOptions = {}): Run

Starts a module without waiting for it.

runModule

zena

function runModule(path: String, options: RunOptions = {}): RunResult

Runs a module to completion.

precompileModule

zena

function precompileModule(path: String, debug: boolean = false): String

Compiles a module to machine code now and caches it beside the file, so that its first run does not pay for the compile. Returns '' on success and the reason otherwise. Running a module caches it the same way; this is for doing it ahead of time. debug compiles it for runs with debug: true.