The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Wasm-Wasm3-0.02
River stage zero No dependents
1 ++
/ Wasm::Wasm3::Module

NAME

Wasm::Wasm3::Module

SYNOPSIS

See Wasm::Wasm3.

DESCRIPTION

This module exposes wasm3’s module object to Perl.

METHODS

This class is not directly instantiated; see Wasm::Wasm3 for details.

$value = OBJ->get_global( $NAME )

Returns the value of the $NAMEd export global.

$type = OBJ->get_global_type( $NAME )

Returns the type (e.g., Wasm::Wasm3::TYPE_I32) of the $NAMEd export global.

Sets $CODEREF as $MODULE_NAME.$FUNCTION_NAME’s implementation inside the WebAssembly module. See below for "$SIGNATURE".

$CODEREF will always be called in list context. $CODEREF MUST return the number of arguments that $SIGNATURE indicates, or you’ll get an error (possibly an unhelpful one).

If $CODEREF throws, the exception is warn()ed, and a generic callback-failed error is thrown to the link_function() caller.

WASM Context in Callbacks

Your callback may need to reference either the wasm3 runtime or module. When doing this, be sure to use a weaken()ed copy (cf. Scalar::Util) of that object, or you’ll leak memory (and eventually get a warn()ing about it).

For example:

    my $weak_runtime = $runtime;
    Scalar::Util::weaken($weak_runtime);

    $module->link_function(
        mymodule => myfuncname => 'v(ii)',
        sub {
            my ($buf_p, $buflen) = @_;

            my $buf = $weak_runtime->get_memory($buf_p, $buflen);

            # Now do something cool with $buf.

            return;
        },
    );

The distribution’s t/wasi_pp.t shows this technique in action.

(An alternative design would be to pass a special context object to every callback, but the weak-reference approach is more efficient.)

$SIGNATURE

$SIGNATURE is wasm3’s own convention to describe a function’s inputs & outputs. As of this writing wasm3’s documentation doesn’t describe it very well, so we’ll describe it here.

The format is $RETURNS($ARGS), where $RETURNS and $ARGS are both either:

  • v, to indicate empty (v meaning “void”)

  • … a sequence of one or more of: i (i32), I (i64), f (f32), F, (f64)

Space characters are ignored.

For example: v(if) indicates a function that takes i32 and f32 as arguments and returns nothing.

A quick helper to link WASI includes via wasm3’s uvwasi integration.

This uses wasm3’s built-in WASI defaults, e.g., STDIN becomes WASI file descriptor 0.

(NB: Only available if uvwasi is your WASI backend; see Wasm::Wasm3 for details.)

Like link_wasi_default() but takes a list of key/value pairs that offer the following controls:

%OPTS are:

  • in, out, err - File handles to the WASI input, output, and error streams. Defaults are file descriptors 0, 1, and 2 respectively.

  • env - A reference to an array of key/value byte-string pairs to pass as the WASI environment.

  • preopen - A reference to a hash of WASI paths to system/real paths.

    IMPORTANT: WASI paths are character strings, while system paths are byte strings. The discrepancy arises because WASI paths are always character strings, while Perl treats all system paths as byte strings (even on OSes like Windows where paths are character strings).

    So if, for example, you have directory /tmp/føø that you’ll access in WASI as /épée, your code might look thus:

        preopen => {
        do { use utf8; '/épée' } => do { no utf8; '/tmp/føø' },
    },