NAME

Wasm - Write Perl extensions using Wasm

VERSION

version 0.06

SYNOPSIS

lib/MathStuff.pm:

package MathStuff;

use strict;
use warnings;
use base qw( Exporter );
use Wasm
  -api => 0,
  -exporter => 'ok',
  -wat => q{
    (module
      (func (export "add") (param i32 i32) (result i32)
        local.get 0
        local.get 1
        i32.add)
      (func (export "subtract") (param i32 i32) (result i32)
        local.get 0
        local.get 1
        i32.sub)
      (memory (export "frooble") 2 3)
    )
  };

1;

mathstuff.pl:

use MathStuff qw( add subtract );

print add(1,2), "\n";      # prints 3
print subtract(3,2), "\n", # prints 1

DESCRIPTION

WARNING: WebAssembly and Wasmtime are a moving target and the interface for these modules is under active development. Use with caution.

The Wasm Perl dist provides tools for writing Perl bindings using WebAssembly (Wasm).

OPTIONS

-api

use Wasm -api => 0;

As of this writing, since the API is subject to change, this must be provided and set to 0.

-exporter

use Wasm -api => 0, -exporter => 'all';
use Wasm -api => 0, -exporter => 'ok';

Configure the caller as an Exporter, with all the functions in the WebAssembly either @EXPORT (all) or @EXPORT_OK (ok).

-file

use Wasm -api => 0, -file => $file;

Path to a WebAssembly file in either WebAssembly Text (.wat) or WebAssembly binary (.wasm) format.

-imports

use Wasm -api => 0, -imports => \@imports;

Use the given imports when creating the module instance.

-package

use Wasm -api => 0, -package => $package;

Install subroutines in to $package namespace instead of the calling namespace.

-self

use Wasm -api => 0, -self;

Look for a WebAssembly Text (.wat) or WebAssembly binary (.wasm) file with the same base name as the Perl source this is called from.

For example if you are calling this from lib/Foo/Bar.pm, it will look for lib/Foo/Bar.wat and lib/Foo/Bar.wasm. If both exist, then it will use the newer of the two.

-wat

use Wasm -api => 0, -wat => $wat;

String containing WebAssembly Text (WAT). Helpful for inline WebAssembly inside your Perl source file.

CAVEATS

As mentioned before as of this writing this dist is a work in progress. I won't intentionally break stuff if I don't have to, but practicality may demand it in some situations.

This interface is implemented using the bundled Wasm::Wasmtime family of modules, which depends on the Wasmtime project. Because of the way Wasmtime handles out-of-bounds memory errors, large PROT_NONE pages are allocated at startup. While these pages do not consume any actual resources (as used by Wasmtime), they can cause out-of-memory errors on Linux systems with virtual memory limits (ulimit -v). Similar techniques are common in modern programming languages, and this seems to be more a limitation of the Linux kernel.

SEE ALSO

Wasm::Wasmtime

Low level interface to wasmtime.

Wasm::Hook

Load WebAssembly modules as though they were Perl modules.

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Wasm

perl -MCPAN -e shell
install Wasm