diff --git a/CHANGELOG.md b/CHANGELOG.md index 7756a471e61..e2822cc821f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ Looking for changes that affect our C API? See the [C API Changelog](lib/c-api/C - #[3096](https://github.com/wasmerio/wasmer/pull/3096) create-exe: use cached wasmer tarballs for network fetches ### Changed +- #[3131](https://github.com/wasmerio/wasmer/pull/3131) Update migration docs for MemoryView changes ### Fixed diff --git a/docs/migration_to_3.0.0.md b/docs/migration_to_3.0.0.md index 2a87147af62..c115578cd5c 100644 --- a/docs/migration_to_3.0.0.md +++ b/docs/migration_to_3.0.0.md @@ -117,6 +117,62 @@ env_mut.memory = Some(instance.exports.get_memory("memory")); env_mut.alloc_guest_memory = Some(instance.exports.get_typed_function("__alloc")); ``` +### New `MemoryView` API (preparation for shared memory) + +Reading from memory has slightly changed compared to 2.x: + +```rust +// 2.x +let memory = instance.exports.get_memory("mem")?; +println!("Memory size (pages) {:?}", memory.size()); +println!("Memory size (bytes) {:?}", memory.data_size()); + +let load = instance + .exports + .get_native_function::<(), (WasmPtr, i32)>("load")?; + +let (ptr, length) = load.call(&mut store)?; +let str = ptr.get_utf8_string(memory, length as u32).unwrap(); +println!("Memory contents: {:?}", str); +``` + +```rust +// 3.x +let memory = instance.exports.get_memory("mem")?; +let memory_view = memory.view(&store); +println!("Memory size (pages) {:?}", memory_view.size()); +println!("Memory size (bytes) {:?}", memory_view.data_size()); + +let load: TypedFunction<(), (WasmPtr, i32)> = + instance.exports.get_typed_function(&mut store, "load")?; + +let (ptr, length) = load.call(&mut store)?; +let memory_view = memory.view(&store); +let str = ptr.read_utf8_string(&memory_view, length as u32).unwrap(); +println!("Memory contents: {:?}", str); +``` + +The reason for this change is that in the future this will enable +safely sharing memory across threads. The same thing goes for reading slices: + +```rust +// 2.x +let new_str = b"Hello, Wasmer!"; +let values = ptr.deref(memory, 0, new_str.len() as u32).unwrap(); +for i in 0..new_str.len() { + values[i].set(new_str[i]); +} +``` + +```rust +// 3.x +let memory_view = memory.view(&store); // (can be reused) +let new_str = b"Hello, Wasmer!"; +let values = ptr.slice(&memory_view, new_str.len() as u32).unwrap(); +for i in 0..new_str.len() { + values.index(i as u64).write(new_str[i]).unwrap(); +} +``` ### Managing imports diff --git a/examples/exports_memory.rs b/examples/exports_memory.rs index 5f8b0a9d217..8cb29e2e6dc 100644 --- a/examples/exports_memory.rs +++ b/examples/exports_memory.rs @@ -75,7 +75,7 @@ fn main() -> Result<(), Box> { println!("String offset: {:?}", ptr.offset()); println!("String length: {:?}", length); - // We now know where to fin our string, let's read it. + // We now know where to find our string, let's read it. // // We will get bytes out of the memory so we need to // decode them into a string.