Using memory pointers

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

The final code for this example can be found on GitHub.

Please take a look at the setup steps for Rust.

cargo new exported-memory
cd exported-memory

This should generate two important files for us, Cargo.toml and src/main.rs. The Cargo.toml is a file that describes your project and its dependencies. The src/main.rs is the entry point for your project, and contains the fn main() { .. } that is run when the project is executed.

We then modify the Cargo.toml to add the Wasmer dependencies as shown below:

[package]
name = "exported-memory"
version = "0.1.0"
authors = ["The Wasmer Engineering Team <[e-mail]>"]
edition = "2018"

[dependencies]
# The Wasmer API
wasmer = "1.0.0-alpha5"

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:

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

let load = instance
    .exports
    .get_native_function::<(), (WasmPtr<u8, Array>, i32)>("load")?;
        
let memory = instance.exports.get_memory("mem")?;

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.

let (ptr, length) = load.call()?;
println!("String offset: {:?}", ptr.offset());
println!("String length: {:?}", length);

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

let str = ptr.get_utf8_string(memory, length as u32).unwrap();
println!("Memory contents: {:?}", str);

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

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]);
}

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:

let new_str = b"Wasmer!";
let values = ptr.deref(memory, 7, new_str.len() as u32).unwrap();

Running

We now have everything we need to run the WASM module, let's do it!

Rust

You should be able to run it using the cargo run command. The output should look like this:

Compiling module...
Instantiating module...
Memory size (pages) 1 pages
Memory size (bytes) 65536
String offset: 42
String length: 13
Memory contents: "Hello, World!"
New string length: 14
New memory contents: "Hello, Wasmer!"

If you want to run the examples from the Wasmer repository codebase directly, you can also do:

git clone https://github.com/wasmerio/wasmer.git
cd wasmer
cargo run --example exported-memory --release --features "cranelift"