pub struct Module { /* private fields */ }
Expand description
A WebAssembly Module contains stateless WebAssembly code that has already been compiled and can be instantiated multiple times.
Cloning a module
Cloning a module is cheap: it does a shallow copy of the compiled contents rather than a deep copy.
Implementations
sourceimpl Module
impl Module
sourcepub fn new(
store: &impl AsStoreRef,
bytes: impl AsRef<[u8]>
) -> Result<Self, CompileError>
pub fn new(
store: &impl AsStoreRef,
bytes: impl AsRef<[u8]>
) -> Result<Self, CompileError>
Creates a new WebAssembly Module given the configuration in the store.
If the provided bytes are not WebAssembly-like (start with b"\0asm"
),
and the “wat” feature is enabled for this crate, this function will try to
to convert the bytes assuming they correspond to the WebAssembly text
format.
Security
Before the code is compiled, it will be validated using the store features.
Errors
Creating a WebAssembly module from bytecode can result in a
CompileError
since this operation requires to transorm the Wasm
bytecode into code the machine can easily execute.
Example
Reading from a WAT file.
use wasmer::*;
let wat = "(module)";
let module = Module::new(&store, wat)?;
Reading from bytes:
use wasmer::*;
// The following is the same as:
// (module
// (type $t0 (func (param i32) (result i32)))
// (func $add_one (export "add_one") (type $t0) (param $p0 i32) (result i32)
// get_local $p0
// i32.const 1
// i32.add)
// )
let bytes: Vec<u8> = vec![
0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x01, 0x06, 0x01, 0x60,
0x01, 0x7f, 0x01, 0x7f, 0x03, 0x02, 0x01, 0x00, 0x07, 0x0b, 0x01, 0x07,
0x61, 0x64, 0x64, 0x5f, 0x6f, 0x6e, 0x65, 0x00, 0x00, 0x0a, 0x09, 0x01,
0x07, 0x00, 0x20, 0x00, 0x41, 0x01, 0x6a, 0x0b, 0x00, 0x1a, 0x04, 0x6e,
0x61, 0x6d, 0x65, 0x01, 0x0a, 0x01, 0x00, 0x07, 0x61, 0x64, 0x64, 0x5f,
0x6f, 0x6e, 0x65, 0x02, 0x07, 0x01, 0x00, 0x01, 0x00, 0x02, 0x70, 0x30,
];
let module = Module::new(&store, bytes)?;
sourcepub fn from_file(
store: &impl AsStoreRef,
file: impl AsRef<Path>
) -> Result<Self, IoCompileError>
pub fn from_file(
store: &impl AsStoreRef,
file: impl AsRef<Path>
) -> Result<Self, IoCompileError>
Creates a new WebAssembly module from a file path.
sourcepub fn from_binary(
store: &impl AsStoreRef,
binary: &[u8]
) -> Result<Self, CompileError>
pub fn from_binary(
store: &impl AsStoreRef,
binary: &[u8]
) -> Result<Self, CompileError>
Creates a new WebAssembly module from a binary.
Opposed to Module::new
, this function is not compatible with
the WebAssembly text format (if the “wat” feature is enabled for
this crate).
sourcepub unsafe fn from_binary_unchecked(
store: &impl AsStoreRef,
binary: &[u8]
) -> Result<Self, CompileError>
pub unsafe fn from_binary_unchecked(
store: &impl AsStoreRef,
binary: &[u8]
) -> Result<Self, CompileError>
Creates a new WebAssembly module skipping any kind of validation.
Safety
This can speed up compilation time a bit, but it should be only used in environments where the WebAssembly modules are trusted and validated beforehand.
sourcepub fn validate(
store: &impl AsStoreRef,
binary: &[u8]
) -> Result<(), CompileError>
pub fn validate(
store: &impl AsStoreRef,
binary: &[u8]
) -> Result<(), CompileError>
Validates a new WebAssembly Module given the configuration in the Store.
This validation is normally pretty fast and checks the enabled WebAssembly features in the Store Engine to assure deterministic validation of the Module.
sourcepub fn serialize(&self) -> Result<Bytes, SerializeError>
pub fn serialize(&self) -> Result<Bytes, SerializeError>
Serializes a module into a binary representation that the Engine
can later process via
Module::deserialize
.
Usage
let serialized = module.serialize()?;
sourcepub fn serialize_to_file(
&self,
path: impl AsRef<Path>
) -> Result<(), SerializeError>
pub fn serialize_to_file(
&self,
path: impl AsRef<Path>
) -> Result<(), SerializeError>
Serializes a module into a file that the Engine
can later process via
Module::deserialize_from_file
.
Usage
module.serialize_to_file("path/to/foo.so")?;
sourcepub unsafe fn deserialize(
store: &impl AsStoreRef,
bytes: impl IntoBytes
) -> Result<Self, DeserializeError>
pub unsafe fn deserialize(
store: &impl AsStoreRef,
bytes: impl IntoBytes
) -> Result<Self, DeserializeError>
Deserializes a serialized Module binary into a Module
.
Note: the module has to be serialized before with the
serialize
method.
Safety
This function is inherently unsafe as the provided bytes:
- Are going to be deserialized directly into Rust objects.
- Contains the function assembly bodies and, if intercepted, a malicious actor could inject code into executable memory.
And as such, the deserialize
method is unsafe.
Usage
let module = Module::deserialize(&store, serialized_data)?;
sourcepub unsafe fn deserialize_from_file(
store: &impl AsStoreRef,
path: impl AsRef<Path>
) -> Result<Self, DeserializeError>
pub unsafe fn deserialize_from_file(
store: &impl AsStoreRef,
path: impl AsRef<Path>
) -> Result<Self, DeserializeError>
Deserializes a a serialized Module located in a Path
into a Module
.
Note: the module has to be serialized before with the
serialize
method.
Safety
Please check Module::deserialize
.
Usage
let module = Module::deserialize_from_file(&store, path)?;
sourcepub fn name(&self) -> Option<&str>
pub fn name(&self) -> Option<&str>
Returns the name of the current module.
This name is normally set in the WebAssembly bytecode by some
compilers, but can be also overwritten using the Module::set_name
method.
Example
let wat = "(module $moduleName)";
let module = Module::new(&store, wat)?;
assert_eq!(module.name(), Some("moduleName"));
sourcepub fn set_name(&mut self, name: &str) -> bool
pub fn set_name(&mut self, name: &str) -> bool
Sets the name of the current module. This is normally useful for stacktraces and debugging.
It will return true
if the module name was changed successfully,
and return false
otherwise (in case the module is already
instantiated).
Example
let wat = "(module)";
let mut module = Module::new(&store, wat)?;
assert_eq!(module.name(), None);
module.set_name("foo");
assert_eq!(module.name(), Some("foo"));
sourcepub fn imports(&self) -> ImportsIterator<impl Iterator<Item = ImportType> + '_>
pub fn imports(&self) -> ImportsIterator<impl Iterator<Item = ImportType> + '_>
Returns an iterator over the imported types in the Module.
The order of the imports is guaranteed to be the same as in the WebAssembly bytecode.
Example
let wat = r#"(module
(import "host" "func1" (func))
(import "host" "func2" (func))
)"#;
let module = Module::new(&store, wat)?;
for import in module.imports() {
assert_eq!(import.module(), "host");
assert!(import.name().contains("func"));
import.ty();
}
sourcepub fn exports(&self) -> ExportsIterator<impl Iterator<Item = ExportType> + '_>
pub fn exports(&self) -> ExportsIterator<impl Iterator<Item = ExportType> + '_>
Returns an iterator over the exported types in the Module.
The order of the exports is guaranteed to be the same as in the WebAssembly bytecode.
Example
let wat = r#"(module
(func (export "namedfunc"))
(memory (export "namedmemory") 1)
)"#;
let module = Module::new(&store, wat)?;
for export_ in module.exports() {
assert!(export_.name().contains("named"));
export_.ty();
}