NAME

Wasm::Wasm3 - Self-contained WebAssembly via wasm3

SYNOPSIS

Basic setup:

my $env = Wasm::Wasm3->new();
my $module = $env->parse_module($wasm_binary);
my $runtime = $env->create_runtime(1024)->load_module($module);

Run WASI:

my $exit_code = $runtime->run_wasi('arg1', 'arg2');

WebAssembly-exported globals:

my $global = $module->get_global('some-value');

$module->set_global('some-value', 1234);

WebAssembly-exported memory:

$runtime->set_memory( $offset, $bytes );

my $from_wasm = $runtime->get_memory( $offset, $length );

Call a WebAssembly-exported function:

my @out = $runtime->call('some-func', @args);

Implement a WebAssembly-imported function in Perl:

$runtime->link_function('mod-name', 'func-name', 'v(ii)', $coderef);

(v(ii) is the function’s signature; see Wasm::Wasm3::Runtime for details.)

DESCRIPTION

Well-known WebAssembly runtimes like Wasmer, Wasmtime, or WAVM often require nonstandard dependencies/toolchains (e.g., LLVM or Rust). Their builds can take a while, especially on slow machines, and only the most popular platforms may enjoy support.

wasm3 takes a different tactic from the aforementioned “big dogs”: whereas those are all JIT compilers, wasm3 is a WebAssembly interpreter. This makes it quite small and fast/simple to build, which lets you run WebAssembly in environments that something bigger may not support. Runtime performance lags the “big dogs” significantly, but startup latency will likely be lower, and memory usage is much lower.

This distribution includes wasm3, so you don’t need to build it yourself.

STATUS

This Perl library is EXPERIMENTAL.

Additionally, wasm3 is, as of this writing, rather less complete than Wasmer et al. wasm3 only exports a single WebAssembly memory, for example. It can’t import memories or globals, and it neither imports nor exports tables.

WASI SUPPORT

wasm3 implements WASI via either of (as of this writing) two backends: a wrapper around uvwasi, and a less-complete original implementation. The former needs libuv, which doesn’t compile on all platforms, while the latter should compile everywhere this module can run.

This distribution’s Makefile.PL implements logic to determine which backend to use.

You’re free, of course, to implement your own WASI imports rather than to use wasm3’s. Depending on how much of WASI you actually need that may not be as onerous as it sounds; see the distribution’s t/wasi_pp.t for an example.

MEMORY LEAK DETECTION

To help you avoid memory leaks, instances of all classes warn() if their DESTROY() method runs at global destruction time.

This necessitates extra care when linking Perl functions to WASM; see Wasm::Wasm3::Module for details, and the distribution’s t/wasi_pp.t for an example.

DOCUMENTATION

This module generally documents only those aspects of its usage that are germane to this module specifically. For more details, see wasm3’s documentation.

STATIC FUNCTIONS & CONSTANTS

($MAJOR, $MINOR, $REV) = M3_VERSION

Returns wasm3’s version as 3 integers.

$STRING = M3_VERSION_STRING

Returns wasm3’s version as a string.

TYPE_I32, TYPE_I64, TYPE_F32, TYPE_F64

Numeric constants that indicate the corresponding WebAssembly type.

$YN = WASI_BACKEND

Either uvwasi or simple. See above about WASI support for details.

METHODS

$OBJ = CLASS->new()

Instantiates CLASS. Creates a new wasm3 environment and binds it to the returned object.

$RUNTIME = OBJ->create_runtime( $STACKSIZE )

Creates a new wasm3 runtime from OBJ. Returns a Wasm::Wasm3::Runtime instance.

$MODULE = OBJ->parse_module( $WASM_BINARY )

Loads a WebAssembly module from binary (*.wasm) format. Returns a Wasm::Wasm3::Module instance.

If your WebAssembly module is in text format rather than binary, you’ll need to convert it first. Try wabt if you need such a tool.

LICENSE & COPYRIGHT

Copyright 2022 Gasper Software Consulting. All rights reserved.

This library is licensed under the same terms as Perl itself. See perlartistic.