Wasmex.Module (Wasmex v0.6.0)
A compiled WebAssembly module.
A WebAssembly Module contains stateless WebAssembly code that has already been compiled and can be instantiated multiple times.
# Read a WASM file and compile it into a WASM module
{:ok, bytes } = File.read("wasmex_test.wasm")
{:ok, module} = Wasmex.Module.compile(bytes)
# use the compiled module to start as many running instances as you want
{:ok, instance } = Wasmex.start_link(%{module: module})
Link to this section Summary
Functions
Compiles a WASM module from it's WASM (usually a .wasm file) or WAT (usually a .wat file) representation.
Lists all exports of a WebAssembly module.
Lists all imports of a WebAssembly module grouped by their module namespace.
Returns the name of the current module if a name is given.
Serializes a compiled WASM module into a binary.
Sets the name of the current module.
Deserializes a module from its binary representation.
Link to this section Types
Specs
Link to this section Functions
compile(bytes)
Specs
Compiles a WASM module from it's WASM (usually a .wasm file) or WAT (usually a .wat file) representation.
Compiled modules can be instantiated using Wasmex.start_link/1
.
Since module compilation takes time and resources but instantiation is comparatively cheap, it
may be a good idea to compile a module once and instantiate it often if you want to
run a WASM binary multiple times.
exports(module)
Specs
Lists all exports of a WebAssembly module.
Returns a map which has the exports name (string) as key and export info-tuples as values. Info tuples always start with an atom indicating the exports type:
:fn
(function):global
:table
:memory
Further parts of the info tuple vary depending on the type.
imports(module)
Specs
Lists all imports of a WebAssembly module grouped by their module namespace.
Returns a map of namespaces, each being a map which has the imports name (string) as key and import info-tuples as values. Info tuples always start with an atom indicating the imports type:
:fn
(function):global
:table
:memory
Further parts of the info tuple vary depending on the type.
name(module)
Specs
Returns the name of the current module if a name is given.
This name is normally set in the WebAssembly bytecode by some compilers,
but can be also overwritten using set_name/2
.
serialize(module)
Specs
Serializes a compiled WASM module into a binary.
The generated binary can be deserialized back into a module using unsafe_deserialize/1
.
It is unsafe do alter the binary in any way. See unsafe_deserialize/1
for safety considerations.
set_name(module, name)
Specs
Sets the name of the current module.
This is normally useful for stacktraces and debugging.
It will return :ok
if the module name was changed successfully,
and return an {:error, reason}
tuple otherwise (in case the module is already
instantiated).
unsafe_deserialize(bytes)
Specs
Deserializes a module from its binary representation.
This function is inherently unsafe as the provided binary:
- Is going to be deserialized directly into Rust objects.
- Contains the WASM function assembly bodies and, if intercepted, a malicious actor could inject code into executable memory.
And as such, the deserialize method is unsafe. Only pass binaries directly coming from
serialize/1
, never any user input. Best case is it crashing the NIF, worst case is
malicious input doing... malicious things.
The deserialization must be done on the same CPU architecture as the serialization (e.g. don't serialize a x86_64-compiled module and deserialize it on ARM64).