✏️ Using guest (exported) globals

A WASM module can export entities, like functions, memories, globals and tables. This example illustrates how to use exported globals.

In this example we'll be using a simple WASM module which exports some globals.

Globals are probably the simplest entity we'll encounter in WASM modules but there is still some interesting things to talk about. For example, globals come in two flavors:

• Immutable globals (const)

• Mutable globals (var)

We will cover both in this example.

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 exports-global
cd exports-global

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

[dependencies]
# The Wasmer API
wasmer = "1.0"

Go

C/C++

Now that we have everything set up, let's go ahead and try it out!

Querying types information

The first interesting thing to do is to query their type information in order to know if they are mutable or not. Our module exports two globals, one and some. Which one is mutable and which one is not?

Rust

l​​et one = instance.exports.get_global("one")?;
let some = instance.exports.get_global("some")?;

​let one_type = one.ty();
let some_type = some.ty();

​println!("one type: {:?} {:?}", one_type.mutability, one_type.ty);
println!("some type: {:?} {:?}", some_type.mutability, some_type.ty);

Go

C/C++

Getting globals values

The global API is straightforward: it provides a dedicated method to get the value of a given global. Look how easy it is:

Rust

let some_value = some.get();

println!("`some` value: {:?}", some_value);

Go

C/C++

Setting globals

As we said before, globals come in two flavor. Immutable globals, for which we can only set a value once and mutable ones.

First we'll try to set the value of a immutable global and see what happens:

Rust

let result = one.set(Value::F32(42.0));

assert_eq!(
    result.expect_err("Expected an error").message(),
    "Attempted to set an immutable global"
);

Go

C/C++

As you can see here, trying to set a value on a immutable global will always lead to an error.

Now let's see how to correctly set a value on a mutable global:

Rust

some.set(Value::F32(42.0))?;

Go

C/C++

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...
Getting globals types information...
`one` type: Const F32
`some` type: Var F32
Getting global values...
`one` value: 1.0
`some` value: F32(0.0)
Setting global values...
`one` value after `set`: F32(1.0)
`some` value after `set_some`: F32(21.0)
`some` value after `set`: F32(42.0)

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-function --release --features "cranelift"

Go

C/C++