Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 38 ยท Modules, Memory and Tables

WebAssembly Globals

Learn WebAssembly global variables. Declare mutable and immutable globals, use global.get and global.set, and share them with JavaScript through WebAssembly.Global.

You now know three places where a module keeps state: its stack (temporary values), its linear memory (bytes) and its tables (references). The fourth is the simplest, the global variable. A global is a single typed value that every function in the module can read, and optionally write.

Compilers use globals for things like the stack pointer of a C program, and hosts use them to hand constants such as configuration values or feature flags to a module without calling a function.

Declaring a global

The Global section (id 6) lists globals. Each entry has three parts:

  1. The value type: i32, i64, f32, f64 or a reference type.
  2. A mutability flag: 0x00 for constant, 0x01 for mutable.
  3. An initial value, written as a constant expression ending in end (0x0b), such as i32.const 7 (0x41 0x07 0x0b).

Functions read a global with global.get index (0x23) and, if it is mutable, change it with global.set index (0x24). Trying to set an immutable global is a validation error, so it is caught before the module ever runs.

Globals can be exported (export kind 3) or imported (import kind 0x03, followed by the type and mutability). Immutable globals have been importable for a long time; mutable ones can be imported and exported in all current engines too.

A counter and a constant

This module has a mutable i32 counter and an immutable f64 constant. It exports both and one function, inc, that adds one to the counter. The 8 bytes of the float constant come from a Float64Array, because f64.const stores its operand as raw little-endian bits.

Node.js Mutable and immutable globals

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

An exported global is not a bare number: it is a WebAssembly.Global object with a value property and a valueOf() method. Reading count.value is cheap, but it is a property lookup on every access, so do not poll it in a hot loop.

Creating a Global in JavaScript

You can create globals on the host side and import them. Pass the type and mutability in a descriptor and the starting value as the second argument:

JavaScript
const limit = new WebAssembly.Global({ value: 'i32', mutable: false }, 64);
const total = new WebAssembly.Global({ value: 'i64', mutable: true }, 0n);   // BigInt for i64

Because the object is shared, several instances can use the very same global. That is a simple way to give two modules one counter, one flag or one "current mode".

Node.js Two instances sharing one global

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The two instances used one value, and the host could watch it. Mismatches fail at link time with WebAssembly.LinkError, long before any code runs.

Globals compared with memory

Global Linear memory
Holds One typed value Any number of bytes
Access global.get / global.set, no address load / store with an address
Can hold references Yes (funcref, externref) No (bytes only)
Speed Engine can keep it in a register A memory access
Typical use Stack pointer, flags, counters, config Arrays, strings, structs

A good rule: put a value in a global when it is a small, well-known piece of state with a name, and in memory when it is data. Because JavaScript can read a global without knowing any address, globals are a tidy way to publish a few numbers, such as a version or a buffer's current length.

Constant expressions

Global initializers, data and element segment offsets are constant expressions: they are evaluated at instantiation by a tiny subset of instructions. The classic ones are i32.const, i64.const, f32.const, f64.const and global.get of an imported immutable global. This means a module can place a data segment at an address chosen by the host: import an immutable i32 global and use global.get as the segment offset. Newer engines also allow simple arithmetic in constant expressions (the extended-const proposal), and compilers use that for position-independent code.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the mutability byte 0x01 mean in a global's declaration?

    0x00 means constant (immutable) and 0x01 means mutable.
  2. 2. What type does JavaScript see for an exported global?

    Exports of kind global are WebAssembly.Global objects; read or write them through .value.
  3. 3. What happens if you import an immutable Global where the module declared a mutable import?

    Type and mutability are part of the import's declared type and are checked when instantiating.
  4. 4. Which value must you use to create a mutable i64 Global in JavaScript?

    i64 values are BigInt on the JavaScript side.

Summary

  • A global is one typed, named value, constant or mutable, readable with global.get and writable with global.set.
  • Declare globals in the Global section with a type, mutability and constant initial expression.
  • Exports appear in JavaScript as WebAssembly.Global (.value); you can also create your own and import it.
  • Sharing one Global between instances shares state; mismatched type or mutability gives a LinkError.
  • Use globals for small named state, memory for bulk data.

Next: WebAssembly Text Format (WAT) Basics