► Using memory pointers

Search…
In this example we will learn how to pass data between the host system and Wasm using memory pointers.
Linear memory is a major concept in WebAssembly:
Because WebAssembly is sandboxed, memory must be copied between the host (your Rust application) and the Wasm module. Upcoming proposals like WebAssembly Interface Types will make this process much easier, but it is still a work in progress.
The way that this memory is allocated, freed, passed, organized, etc... can vary depending on the ABI of the Wasm module.
For example, some ABIs will provide functions, either as imports or exports, for allocation and freeing of memory from the host or guest. Some Wasm ABIs may want to control their memory implicitly, for example the ABI may say that the host can reserve memory addresses 0 to 1000 for a special purpose and simply write there directly. You will want to take a look at the documentation of the ABI of your Wasm module, to see what conventions are used for memory allocation.
In this example, let's say we have a Wasm module that can perform transformations on a string passed into the module's memory. This module exports a function that returns a pointer to a fixed size static buffer. This Wasm module will take in a string, and append the string " Wasm is cool!" to the end. This example shows how we can read and write memory from the host (your Rust application), and how the Wasm module can also read and write to the same memory.
First we are going to want to initialize a new project. To do this we can navigate to our project folder, or create one. In this example, we will create a new project. Lets create it and navigate to it:
Rust
Ruby
The final Rust code for this example can be found on Github: exports_memory.rs.
Please take a look at the setup steps for Rust.
1
cargo new exported-memory
2
cd exported-memory
Copied!
We have to modify Cargo.toml to add the Wasmer dependencies as shown below:
1
[dependencies]
2
# The Wasmer API
3
wasmer = "2.0"
Copied!
The final Ruby code for this example can be found on Github: exports_memory.rb.
Please take a look at the setup steps for Ruby.
1
gem install wasmer
Copied!
Now that we have everything set up, let's go ahead and try it out!
Before you go further in this example, it is recommended you read the example on the basics of interacting with guest memory:
💾
Interacting with memory
Reading the memory
The guest module exports a bunch of things that will be useful for us:
A memory exported as mem;
A function to retrieve information about the memory contents exported as load.
The load function will return two things: the offset of the contents and its length. Let's see how we can use that to read the memory.
Rust
Ruby
1
let load = instance
2
    .exports
3
    .get_native_function::<(), (WasmPtr<u8, Array>, i32)>("load")?;
4
​
5
let memory = instance.exports.get_memory("mem")?;
Copied!
When importing the function we tell Wasmer that it return a WasmPtr as its first return value. This WasmPtr is what will give us the ability to interact with the memory.
1
let (ptr, length) = load.call()?;
2
println!("String offset: {:?}", ptr.offset());
3
println!("String length: {:?}", length);
Copied!
1
memory = instance.exports.mem
Copied!
Let's call the hello exported function: it will return what we'll call a pointer.
1
pointer = instance.exports.hello.()
Copied!
This pointer is actually just an integer which is the position in the memory where we'll find our data.
Now that we have our pointer, let's read the data. We know we are about to read a string and the load function gave us its length. We have everything we need!
Rust
Ruby
1
let str = ptr.get_utf8_string(memory, length as u32).unwrap();
2
println!("Memory contents: {:?}", str);
Copied!
1
reader = memory.uint8_view pointer
2
returned_string = reader.take(13).pack("U*")
3
raise "Error" unless returned_string == 'Hello, World!'
Copied!
Done! We were able to get a string out of the Wasm module memory.
Writing to the memory
It's now time to write a new string int the guest module's memory. To do that will continue using our pointer.
Rust
What we do here is dereferencing the pointer to get a slice of Cells: we want this slice to be the size of the new string starting at the same offset as our pointer. This allows us to completely overwrite the old string with the new one.
We could have just changed a single word in the old string. To do that we would have changed the offset and length of the slice when dereferencing the pointer. Here is how we would have done the dereferencing part if we wanted to only change the "World!" part:
1
let new_str = b"Wasmer!";
2
let values = ptr.deref(memory, 7, new_str.len() as u32).unwrap();
Copied!
Running
We now have everything we need to run the Wasm module, let's do it!
Rust
Ruby
1
Compiling module...
2
Instantiating module...
3
Memory size (pages) 1 pages
4
Memory size (bytes) 65536
5
String offset: 42
6
String length: 13
7
Memory contents: "Hello, World!"
8
New string length: 14
9
New memory contents: "Hello, Wasmer!"
Copied!
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer.git
2
cd wasmer
3
cargo run --example exported-memory --release --features "cranelift"
Copied!
You should be able to run it using the ruby instance.rb command.
If you want to run the examples from the Wasmer Ruby repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer-ruby.git
2
cd wasmer-ruby
3
ruby examples/exports_memory.rb
Copied!
Interrupting Execution
Next - Community
Built with Wasmer
Last modified 6mo ago
Copy link
Contents
Reading the memory
Writing to the memory
Running