Introduction to WasmEdge module instance

Overview

In this section, we will talk about module instance. In wasmedge-sys crate, four kinds of module instances are defined:

  • Instance

    • An Instance represents a runtime module instance which is held by a WasmEdge Store context. The Store context is either held by a WasmEdge Vm, or related to a WasmEdge Executor.

    • APIs to retrieve an Instance.

      • If a Vm is available, then

        • with the Vm::active_module API, you can get an anonymous module instance from this Vm.

        • with the Vm::store_mut and Store::module APIs, you can get a named module instance from this Vm.

      • If an Executor is available, then

        • with the Executor::register_named_module API, you can get a named module instance from this Executor.

        • with the Executor::register_active_module API, you can get an anonymous module instance from this Executor.

  • ImportModule

    • ImportModule, also called import module, represents a module instance to be registered into a WasmEdge Vm or Executor. ImportModule implements the ImportObject trait, meaning that WebAssembly function, table, memory and global instances can be added to an import module, and then be registered and instantiated together when the import module is registered into a Vm or Executor.

  • WasiModule and WasmEdgeProcessModule

    • WasiModule and WasmEdgeProcessModule are module instances for WASI and WasmEdgeProcess specification, respectively. They also implement the ImportObject trait. Different from ImportModule, these two kinds of module instances can not only be created, but be retrieved from a Vm.

    • APIs to retrieve WasiModule and WasmEdgeProcessModule.

      • If a Vm is available, then

        • with the Vm::wasi_module API, you can get a module instance of WasiModule type.

        • with the Vm::wasmedge_process_module API, you can get a WasmEdgeProcessModule from this Vm.

Examples

Example 1

In this example, we’ll demonstrate how to use the APIs of Vm to

  • Create Wasi and WasmEdgeProcess module instances implicitly by using a Config while creating a Vm.

    2. #![allow(unused)]
    4. fn main() {
    5. // create a Config context
    6. let mut config = Config::create()?;
    7. config.bulk_memory_operations(true);
    8. assert!(config.bulk_memory_operations_enabled());
    9. config.wasi(true);
    10. assert!(config.wasi_enabled());
    11. config.wasmedge_process(true);
    12. assert!(config.wasmedge_process_enabled());
    14. // create a Vm context with the given Config and Store
    15. let mut vm = Vm::create(Some(config), None)?;
    17. }

  • Retrieve the Wasi and WasmEdgeProcess module instances from the Vm.

    2. #![allow(unused)]
    4. fn main() {
    5. // get the default Wasi module
    6. let wasi_instance = vm.wasi_module_mut()?;
    7. assert_eq!(wasi_instance.name(), "wasi_snapshot_preview1");
    8. // get the default WasmEdgeProcess module instance
    9. let wasmedge_process_instance = vm.wasmedge_process_module_mut()?;
    10. assert_eq!(wasmedge_process_instance.name(), "wasmedge_process");
    12. }

  • Register an import module as a named module into the Vm.

    2. #![allow(unused)]
    4. fn main() {
    5. // create ImportModule instance
    6. let module_name = "extern_module";
    7. let mut import = ImportModule::create(module_name)?;
    9. // a function to import
    10. fn real_add(inputs: Vec<WasmValue>) -> Result<Vec<WasmValue>, u8> {
    11.     if inputs.len() != 2 {
    12.         return Err(1);
    13.     }
    15.     let a = if inputs[0].ty() == ValType::I32 {
    16.         inputs[0].to_i32()
    17.     } else {
    18.         return Err(2);
    19.     };
    21.     let b = if inputs[1].ty() == ValType::I32 {
    22.         inputs[1].to_i32()
    23.     } else {
    24.         return Err(3);
    25.     };
    27.     let c = a + b;
    29.     Ok(vec![WasmValue::from_i32(c)])
    30. }
    32. // add host function
    33. let func_ty = FuncType::create(vec![ValType::I32; 2], vec![ValType::I32])?;
    34. let host_func = Function::create(&func_ty, Box::new(real_add), 0)?;
    35. import.add_func("add", host_func);
    37. // add table
    38. let table_ty = TableType::create(RefType::FuncRef, 0..=u32::MAX)?;
    39. let table = Table::create(&table_ty)?;
    40. import.add_table("table", table);
    42. // add memory
    43. let mem_ty = MemType::create(0..=u32::MAX)?;
    44. let memory = Memory::create(&mem_ty)?;
    45. import.add_memory("mem", memory);
    47. // add global
    48. let ty = GlobalType::create(ValType::F32, Mutability::Const)?;
    49. let global = Global::create(&ty, WasmValue::from_f32(3.5))?;
    50. import.add_global("global", global);
    52. // register the import module as a named module
    53. vm.register_wasm_from_import(ImportObject::Import(import))?;
    55. }

  • Retrieve the internal Store instance from the Vm, and retrieve the named module instance from the Store instance.

    2. #![allow(unused)]
    4. fn main() {
    5. let mut store = vm.store_mut()?;
    6. let named_instance = store.module(module_name)?;
    7. assert!(named_instance.get_func("add").is_ok());
    8. assert!(named_instance.get_table("table").is_ok());
    9. assert!(named_instance.get_memory("mem").is_ok());
    10. assert!(named_instance.get_global("global").is_ok());
    12. }

  • Register an active module into the Vm.

    2. #![allow(unused)]
    4. fn main() {
    5. // read the wasm bytes
    6. let wasm_bytes = wat2wasm(
    7.     br#"
    8.     (module
    9.         (export "fib" (func $fib))
    10.         (func $fib (param $n i32) (result i32)
    11.         (if
    12.         (i32.lt_s
    13.         (get_local $n)
    14.         (i32.const 2)
    15.         )
    16.         (return
    17.         (i32.const 1)
    18.         )
    19.         )
    20.         (return
    21.         (i32.add
    22.         (call $fib
    23.             (i32.sub
    24.             (get_local $n)
    25.             (i32.const 2)
    26.             )
    27.         )
    28.         (call $fib
    29.             (i32.sub
    30.             (get_local $n)
    31.             (i32.const 1)
    32.             )
    33.         )
    34.         )
    35.         )
    36.         )
    37.     )
    38. "#,
    39. )?;
    41. // load a wasm module from a in-memory bytes, and the loaded wasm module works as an anoymous
    42. // module (aka. active module in WasmEdge terminology)
    43. vm.load_wasm_from_bytes(&wasm_bytes)?;
    45. // validate the loaded active module
    46. vm.validate()?;
    48. // instatiate the loaded active module
    49. vm.instantiate()?;
    51. // get the active module instance
    52. let active_instance = vm.active_module()?;
    53. assert!(active_instance.get_func("fib").is_ok());
    55. }

  • Retrieve the active module from the Vm.

    2. #![allow(unused)]
    4. fn main() {
    5. // get the active module instance
    6. let active_instance = vm.active_module()?;
    7. assert!(active_instance.get_func("fib").is_ok());
    9. }

The complete code in this demo can be found on WasmEdge Github.

Example 2

In this example, we’ll demonstrate how to use the APIs of Executor to

  • Create an Executor and a Store.

    2. #![allow(unused)]
    4. fn main() {
    5. // create an Executor context
    6. let mut executor = Executor::create(None, None)?;
    8. // create a Store context
    9. let mut store = Store::create()?;
    11. }

  • Register an import module into the Executor.

    2. #![allow(unused)]
    4. fn main() {
    5. // read the wasm bytes
    6. let wasm_bytes = wat2wasm(
    7.     br#"
    8. (module
    9.     (export "fib" (func $fib))
    10.     (func $fib (param $n i32) (result i32)
    11.         (if
    12.         (i32.lt_s
    13.         (get_local $n)
    14.         (i32.const 2)
    15.         )
    16.         (return
    17.         (i32.const 1)
    18.         )
    19.         )
    20.         (return
    21.         (i32.add
    22.         (call $fib
    23.         (i32.sub
    24.             (get_local $n)
    25.             (i32.const 2)
    26.         )
    27.         )
    28.         (call $fib
    29.         (i32.sub
    30.             (get_local $n)
    31.             (i32.const 1)
    32.         )
    33.         )
    34.         )
    35.         )
    36.     )
    37.     )
    38. "#,
    39. )?;
    41. // load module from a wasm file
    42. let config = Config::create()?;
    43. let loader = Loader::create(Some(config))?;
    44. let module = loader.from_bytes(&wasm_bytes)?;
    46. // validate module
    47. let config = Config::create()?;
    48. let validator = Validator::create(Some(config))?;
    49. validator.validate(&module)?;
    51. // register a wasm module into the store context
    52. let module_name = "extern";
    53. let named_instance = executor.register_named_module(&mut store, &module, module_name)?;
    54. assert!(named_instance.get_func("fib").is_ok());
    56. }

  • Register an active module into the Executor.

    2. #![allow(unused)]
    4. fn main() {
    5. // read the wasm bytes
    6. let wasm_bytes = wat2wasm(
    7.     br#"
    8. (module
    9.     (export "fib" (func $fib))
    10.     (func $fib (param $n i32) (result i32)
    11.         (if
    12.         (i32.lt_s
    13.         (get_local $n)
    14.         (i32.const 2)
    15.         )
    16.         (return
    17.         (i32.const 1)
    18.         )
    19.         )
    20.         (return
    21.         (i32.add
    22.         (call $fib
    23.         (i32.sub
    24.             (get_local $n)
    25.             (i32.const 2)
    26.         )
    27.         )
    28.         (call $fib
    29.         (i32.sub
    30.             (get_local $n)
    31.             (i32.const 1)
    32.         )
    33.         )
    34.         )
    35.         )
    36.     )
    37.     )
    38. "#,
    39. )?;
    41. // load module from a wasm file
    42. let config = Config::create()?;
    43. let loader = Loader::create(Some(config))?;
    44. let module = loader.from_bytes(&wasm_bytes)?;
    46. // validate module
    47. let config = Config::create()?;
    48. let validator = Validator::create(Some(config))?;
    49. validator.validate(&module)?;
    51. // register a wasm module as an active module
    52. let active_instance = executor.register_active_module(&mut store, &module)?;
    53. assert!(active_instance.get_func("fib").is_ok());
    55. }

The complete code in this demo can be found on WasmEdge Github.