Add Table example; fix local Table and Memory metadata ownership

CHANGELOG.md

@@ -9,6 +9,8 @@
 
 ### Added
 
+
+- [#1687](https://github.com/wasmerio/wasmer/pull/1687) Add basic usage examples; fix ownership of local memory and local table metadata in the VM.
 - [#1709](https://github.com/wasmerio/wasmer/pull/1709) Implement `wasm_module_name` and `wasm_module_set_name` in the Wasm(er) C API.
 - [#1700](https://github.com/wasmerio/wasmer/pull/1700) Implement `wasm_externtype_copy` in the Wasm C API.
 

Cargo.toml

@@ -193,3 +193,13 @@ required-features = ["cranelift"]
 name = "wasi"
 path = "examples/wasi.rs"
 required-features = ["cranelift", "wasi"]
+
+[[example]]
+name = "table"
+path = "examples/table.rs"
+required-features = ["cranelift"]
+
+[[example]]
+name = "memory"
+path = "examples/memory.rs"
+required-features = ["cranelift"]

examples/README.md

@@ -182,6 +182,35 @@ example.
 
    </details>
 
+### Basic Usage
+
+10. Tables, explains how to use Wasm Tables from the Wasmer API.
+
+   _Keywords_: basic, table, call_indirect
+
+   <details>
+   <summary><em>Execute the example</em></summary>
+
+   ```shell
+   $ cargo run --example table --release --features "cranelift"
+   ```
+
+   </details>
+
+11. Memories, explains how to use Wasm Memories from the Wasmer API.
+    Memory example is a work in progress.
+
+   _Keywords_: basic, memory
+
+   <details>
+   <summary><em>Execute the example</em></summary>
+
+   ```shell
+   $ cargo run --example memory --release --features "cranelift"
+   ```
+
+   </details>
+
 [engine-jit]: ./engine_jit.rs
 [engine-native]: ./engine_native.rs
 [engine-headless]: ./engine_headless.rs

examples/memory.rs

@@ -0,0 +1,89 @@
+use wasmer::{
+    imports, wat2wasm, Extern, Function, Instance, Memory, MemoryType, Module, NativeFunc, Pages,
+    Store, Table, TableType, Type, Value,
+};
+use wasmer_compiler_cranelift::Cranelift;
+use wasmer_engine_jit::JIT;
+
+// this example is a work in progress:
+// TODO: clean it up and comment it
+
+fn main() -> anyhow::Result<()> {
+    let wasm_bytes = wat2wasm(
+        r#"
+(module
+  (type $mem_size_t (func (result i32)))
+  (type $get_at_t (func (param i32) (result i32)))
+  (type $set_at_t (func (param i32) (param i32)))
+
+  (memory $mem 1)
+  ;;(import "env" "memory" (memory $mem 1))
+
+  (func $get_at (type $get_at_t) (param $idx i32) (result i32)
+    (i32.load (local.get $idx)))
+
+  (func $set_at (type $set_at_t) (param $idx i32) (param $val i32)
+    (i32.store (local.get $idx) (local.get $val)))
+
+  (func $mem_size (type $mem_size_t) (result i32)
+    (memory.size))
+
+  (export "get_at" (func $get_at))
+  (export "set_at" (func $set_at))
+  (export "mem_size" (func $mem_size))
+  (export "memory" (memory $mem)))
+"#
+        .as_bytes(),
+    )?;
+
+    // We set up our store with an engine and a compiler.
+    let store = Store::new(&JIT::new(&Cranelift::default()).engine());
+    // Then compile our Wasm.
+    let module = Module::new(&store, wasm_bytes)?;
+    //let memory = Memory::new(&store, MemoryType::new(1, None, false))?;
+    let import_object = imports! {
+        /*"env" => {
+            "memory" => memory,
+        }*/
+    };
+    // And instantiate it with no imports.
+    let instance = Instance::new(&module, &import_object)?;
+
+    let mem_size: NativeFunc<(), i32> = instance.exports.get_native_function("mem_size")?;
+    let get_at: NativeFunc<i32, i32> = instance.exports.get_native_function("get_at")?;
+    let set_at: NativeFunc<(i32, i32), ()> = instance.exports.get_native_function("set_at")?;
+    let memory = instance.exports.get_memory("memory")?;
+
+    let mem_addr = 0x2220;
+    let val = 0xFEFEFFE;
+
+    assert_eq!(memory.size(), Pages::from(1));
+    memory.grow(2)?;
+    assert_eq!(memory.size(), Pages::from(3));
+    let result = mem_size.call()?;
+    assert_eq!(result, 3);
+
+    // -------------
+    set_at.call(mem_addr, val)?;
+    // -------------
+
+    let page_size = 0x1_0000;
+    let result = get_at.call(page_size * 3 - 4)?;
+    memory.grow(1025)?;
+    assert_eq!(memory.size(), Pages::from(1028));
+    set_at.call(page_size * 1027 - 4, 123456)?;
+    let result = get_at.call(page_size * 1027 - 4)?;
+    assert_eq!(result, 123456);
+    set_at.call(1024, 123456)?;
+    let result = get_at.call(1024)?;
+    assert_eq!(result, 123456);
+
+    // -------------
+    let result = get_at.call(mem_addr)?;
+    assert_eq!(result, val);
+    // -------------
+
+    //let result = get_at.call(page_size * 1028 - 4)?;
+
+    Ok(())
+}

examples/table.rs

@@ -0,0 +1,154 @@
+use wasmer::{
+    imports, wat2wasm, Function, Instance, Module, NativeFunc, Store, TableType, Type, Value,
+};
+use wasmer_compiler_cranelift::Cranelift;
+use wasmer_engine_jit::JIT;
+
+/// A function we'll call through a table.
+fn host_callback(arg1: i32, arg2: i32) -> i32 {
+    arg1 + arg2
+}
+
+fn main() -> anyhow::Result<()> {
+    let wasm_bytes = wat2wasm(
+        r#"
+(module
+  ;; All our callbacks will take 2 i32s and return an i32.
+  ;; Wasm tables are not limited to 1 type of function, but the code using the
+  ;; table must have code to handle the type it finds.
+  (type $callback_t (func (param i32 i32) (result i32)))
+
+  ;; We'll call a callback by passing a table index as an i32 and then the two
+  ;; arguments that the function expects.
+  (type $call_callback_t (func (param i32 i32 i32) (result i32)))
+
+  ;; Our table of functions that's exactly size 3 (min 3, max 3).
+  (table $t1 3 6 funcref)
+
+  ;; Call the function at the given index with the two supplied arguments.
+  (func $call_callback (type $call_callback_t) (param $idx i32)
+                                               (param $arg1 i32) (param $arg2 i32)
+                                               (result i32)
+    (call_indirect (type $callback_t) 
+                   (local.get $arg1) (local.get $arg2)
+                   (local.get $idx)))
+
+  ;; A default function that we'll pad the table with.
+  ;; This function doubles both its inputs and then sums them.
+  (func $default_fn (type $callback_t) (param $a i32) (param $b i32) (result i32)
+     (i32.add 
+       (i32.mul (local.get $a) (i32.const 2))
+       (i32.mul (local.get $b) (i32.const 2))))
+
+  ;; Fill our table with the default function.
+  (elem $t1 (i32.const 0) $default_fn $default_fn $default_fn)
+
+  ;; Export things for the host to call.
+  (export "call_callback" (func $call_callback))
+  (export "__indirect_function_table" (table $t1)))
+"#
+        .as_bytes(),
+    )?;
+
+    // We set up our store with an engine and a compiler.
+    let store = Store::new(&JIT::new(&Cranelift::default()).engine());
+    // Then compile our Wasm.
+    let module = Module::new(&store, wasm_bytes)?;
+    let import_object = imports! {};
+    // And instantiate it with no imports.
+    let instance = Instance::new(&module, &import_object)?;
+
+    // We get our function that calls (i32, i32) -> i32 functions via table.
+    // The first argument is the table index and the next 2 are the 2 arguments
+    // to be passed to the function found in the table.
+    let call_via_table: NativeFunc<(i32, i32, i32), i32> =
+        instance.exports.get_native_function("call_callback")?;
+
+    // And then call it with table index 1 and arguments 2 and 7.
+    let result = call_via_table.call(1, 2, 7)?;
+    // Because it's the default function, we expect it to double each number and
+    // then sum it, giving us 18.
+    assert_eq!(result, 18);
+
+    // We then get the table from the instance.
+    let guest_table = instance.exports.get_table("__indirect_function_table")?;
+    // And demonstrate that it has the properties that we set in the Wasm.
+    assert_eq!(guest_table.size(), 3);
+    assert_eq!(
+        guest_table.ty(),
+        &TableType {
+            ty: Type::FuncRef,
+            minimum: 3,
+            maximum: Some(6),
+        }
+    );
+
+    // == Setting elements in a table ==
+
+    // We first construct a `Function` over our host_callback.
+    let func = Function::new_native(&store, host_callback);
+
+    // And set table index 1 of that table to the host_callback `Function`.
+    guest_table.set(1, func.into())?;
+
+    // We then repeat the call from before but this time it will find the host function
+    // that we put at table index 1.
+    let result = call_via_table.call(1, 2, 7)?;
+    // And because our host function simply sums the numbers, we expect 9.
+    assert_eq!(result, 9);
+
+    // == Growing a table ==
+
+    // We again construct a `Function` over our host_callback.
+    let func = Function::new_native(&store, host_callback);
+
+    // And grow the table by 3 elements, filling in our host_callback in all the
+    // new elements of the table.
+    let previous_size = guest_table.grow(3, func.into())?;
+    assert_eq!(previous_size, 3);
+
+    assert_eq!(guest_table.size(), 6);
+    assert_eq!(
+        guest_table.ty(),
+        &TableType {
+            ty: Type::FuncRef,
+            minimum: 3,
+            maximum: Some(6),
+        }
+    );
+    // Now demonstarte that the function we grew the table with is actually in the table.
+    for table_index in 3..6 {
+        if let Value::FuncRef(f) = guest_table.get(table_index as _).unwrap() {
+            let result = f.call(&[Value::I32(1), Value::I32(9)])?;
+            assert_eq!(result[0], Value::I32(10));
+        } else {
+            panic!("expected to find funcref in table!");
+        }
+    }
+
+    // Call function at index 0 to show that it's still the same.
+    let result = call_via_table.call(0, 2, 7)?;
+    assert_eq!(result, 18);
+
+    // Now overwrite index 0 with our host_callback.
+    let func = Function::new_native(&store, host_callback);
+    guest_table.set(0, func.into())?;
+    // And verify that it does what we expect.
+    let result = call_via_table.call(0, 2, 7)?;
+    assert_eq!(result, 9);
+
+    // Now demonstrate that the host and guest see the same table and that both
+    // get the same result.
+    for table_index in 3..6 {
+        if let Value::FuncRef(f) = guest_table.get(table_index as _).unwrap() {
+            let result = f.call(&[Value::I32(1), Value::I32(9)])?;
+            assert_eq!(result[0], Value::I32(10));
+        } else {
+            panic!("expected to find funcref in table!");
+        }
+        let result = call_via_table.call(table_index, 1, 9)?;
+        assert_eq!(result, 10);
+    }
+
+    Ok(())
+}

lib/api/src/externals/memory.rs

@@ -37,7 +37,7 @@ impl Memory {
     pub fn new(store: &Store, ty: MemoryType) -> Result<Self, MemoryError> {
         let tunables = store.tunables();
         let style = tunables.memory_style(&ty);
-        let memory = tunables.create_memory(&ty, &style)?;
+        let memory = tunables.create_host_memory(&ty, &style)?;
 
         Ok(Self {
             store: store.clone(),

lib/api/src/externals/table.rs

@@ -43,7 +43,7 @@ impl Table {
         let tunables = store.tunables();
         let style = tunables.table_style(&ty);
         let table = tunables
-            .create_table(&ty, &style)
+            .create_host_table(&ty, &style)
             .map_err(RuntimeError::new)?;
 
         let num_elements = table.size();

lib/api/src/tunables.rs

@@ -1,12 +1,16 @@
 use crate::{MemoryType, Pages, TableType};
 use more_asserts::assert_ge;
 use std::cmp::min;
+use std::ptr::NonNull;
 use std::sync::Arc;
 use target_lexicon::{OperatingSystem, PointerWidth};
 use wasmer_compiler::Target;
 use wasmer_engine::Tunables as BaseTunables;
 use wasmer_vm::MemoryError;
-use wasmer_vm::{LinearMemory, LinearTable, Memory, MemoryStyle, Table, TableStyle};
+use wasmer_vm::{
+    LinearMemory, LinearTable, Memory, MemoryStyle, Table, TableStyle, VMMemoryDefinition,
+    VMTableDefinition,
+};
 
 /// Tunable parameters for WebAssembly compilation.
 #[derive(Clone)]
@@ -84,17 +88,55 @@ impl BaseTunables for Tunables {
         TableStyle::CallerChecksSignature
     }
 
-    /// Create a memory given a [`MemoryType`] and a [`MemoryStyle`].
-    fn create_memory(
+    /// Create a memory owned by the host given a [`MemoryType`] and a [`MemoryStyle`].
+    fn create_host_memory(
         &self,
         ty: &MemoryType,
         style: &MemoryStyle,
     ) -> Result<Arc<dyn Memory>, MemoryError> {
         Ok(Arc::new(LinearMemory::new(&ty, &style)?))
     }
 
-    /// Create a table given a [`TableType`] and a [`TableStyle`].
-    fn create_table(&self, ty: &TableType, style: &TableStyle) -> Result<Arc<dyn Table>, String> {
+    /// Create a memory owned by the VM given a [`MemoryType`] and a [`MemoryStyle`].
+    ///
+    /// # Safety
+    /// - `vm_definition_location` must point to a valid location in VM memory.
+    unsafe fn create_vm_memory(
+        &self,
+        ty: &MemoryType,
+        style: &MemoryStyle,
+        vm_definition_location: NonNull<VMMemoryDefinition>,
+    ) -> Result<Arc<dyn Memory>, MemoryError> {
+        Ok(Arc::new(LinearMemory::from_definition(
+            &ty,
+            &style,
+            vm_definition_location,
+        )?))
+    }
+
+    /// Create a table owned by the host given a [`TableType`] and a [`TableStyle`].
+    fn create_host_table(
+        &self,
+        ty: &TableType,
+        style: &TableStyle,
+    ) -> Result<Arc<dyn Table>, String> {
         Ok(Arc::new(LinearTable::new(&ty, &style)?))
     }
+
+    /// Create a table owned by the VM given a [`TableType`] and a [`TableStyle`].
+    ///
+    /// # Safety
+    /// - `vm_definition_location` must point to a valid location in VM memory.
+    unsafe fn create_vm_table(
+        &self,
+        ty: &TableType,
+        style: &TableStyle,
+        vm_definition_location: NonNull<VMTableDefinition>,
+    ) -> Result<Arc<dyn Table>, String> {
+        Ok(Arc::new(LinearTable::from_definition(
+            &ty,
+            &style,
+            vm_definition_location,
+        )?))
+    }
 }