Wasmex.Instance (Wasmex v0.6.0)

Instantiates a WebAssembly module and allows calling exported functions on it.

# Read a WASM file and compile it into a WASM module
{:ok, bytes } = File.read("wasmex_test.wasm")
{:ok, module} = Wasmex.Module.compile(bytes)

# Instantiates the WASM module.
{:ok, instance } = Wasmex.start_link(%{module: module})

# Call a function on it.
{:ok, [result]} = Wasmex.call_function(instance, "sum", [1, 2])

IO.puts result # 3

All exported functions are accessible via call_exported_function. Arguments of these functions are automatically casted to WebAssembly values. Note that WebAssembly only knows number datatypes (floats and integers of various sizes).

You can pass arbitrary data to WebAssembly by writing data into an instances memory. The memory/3 function returns a Wasmex.Memory struct representing the memory of an instance, e.g.:

{:ok, memory} = Wasmex.Instance.memory(instance, :uint8, 0)

This module, especially call_exported_function/4, is assumed to be called within a GenServer context. Usually, functions definedd here are called through the Wasmex module API to satisfy this assumption.

Link to this section Summary

Functions

Calls a function with the given name and params on the WebAssembly instance. This function assumes to be called within a GenServer context, it expects a from argument as given by handle_call etc.

Link to this section Types

Specs

t() :: %Wasmex.Instance{reference: reference(), resource: binary()}

Link to this section Functions

Link to this function

call_exported_function(instance, name, params, from)

Specs

call_exported_function(t(), binary(), [any()], GenServer.from()) ::
  :ok | {:error, binary()}

Calls a function with the given name and params on the WebAssembly instance. This function assumes to be called within a GenServer context, it expects a from argument as given by handle_call etc.

The WebAssembly function will be invoked asynchronously in a new OS thread. The calling process will receive a {:returned_function_call, result, from} message once the execution finished. The result either is an {:error, reason} or the :ok atom.

A BadArg exception may be thrown when given unexpected input data.

Link to this function

from_bytes(bytes, imports)

This function is deprecated. Compile the module with Wasmex.Module.compile/1 and then use new/2 instead.

Specs

from_bytes(binary(), %{optional(binary()) => (... -> any())}) ::
  {:ok, t()} | {:error, binary()}
Link to this function

function_export_exists(instance, name)

Specs

function_export_exists(t(), binary()) :: boolean()
Link to this function

memory(instance, size, offset)

Specs

memory(t(), atom(), pos_integer()) ::
  {:ok, Wasmex.Memory.t()} | {:error, binary()}
Link to this function

new(module, imports)

Specs

new(Wasmex.Module.t(), %{optional(binary()) => (... -> any())}) ::
  {:ok, t()} | {:error, binary()}
Link to this function

new_wasi(module, imports, wasi)

Specs

new_wasi(Wasmex.Module.t(), %{optional(binary()) => (... -> any())}, %{
  optional(:args) => [String.t()],
  optional(:env) => %{required(String.t()) => String.t()},
  optional(:stdin) => Wasmex.Pipe.t(),
  optional(:stdout) => Wasmex.Pipe.t(),
  optional(:stderr) => Wasmex.Pipe.t()
}) :: {:ok, t()} | {:error, binary()}
Link to this function

wasi_from_bytes(bytes, imports, wasi)

This function is deprecated. Compile the module with Wasmex.Module.compile/1 and then use new_wasi/3 instead.

Specs

wasi_from_bytes(binary(), %{optional(binary()) => (... -> any())}, %{
  optional(:args) => [String.t()],
  optional(:env) => %{required(String.t()) => String.t()},
  optional(:stdin) => Wasmex.Pipe.t(),
  optional(:stdout) => Wasmex.Pipe.t(),
  optional(:stderr) => Wasmex.Pipe.t()
}) :: {:ok, t()} | {:error, binary()}