memory: Wasm definition

Try it

(module
  (import "console" "log" (func $log (param i32)))
  (memory $my_mem 1 2) ;; start with one memory page, and max of 2 pages
  (func $main

    ;; grow memory by 1 page
    ;; grow returns 1 for success and -1 for failure
    ;; will fail if you grow to more than 2 pages
    (memory.grow $my_mem (i32.const 1))
    call $log ;; log the result

  )
  (start $main)
)

const url = "{%wasm-url%}";
await WebAssembly.instantiateStreaming(fetch(url), { console });

Syntax

memory name address_type min max

memory

The memory definition type. Must always be included first.

name Optional

An optional identifying name for the memory. This must begin with a $ symbol, for example $my_mem. If this is omitted, the memory can be identified by its index, for example 0 for the first memory in the Wasm module, 1 for the second, etc.

address_type Optional

An integer value type that indicates what address type the memory will have. Possible values are:

i32

Data will be stored at 32-bit addresses. Pointers used to identify memory addresses (for example when storing or loading) will be i32 values.

i64

Data will be stored at 64-bit addresses. Pointers used to identify memory addresses (for example when storing or loading) will be i64 values.

If omitted, address_type defaults to i32.

min

The minimum number of 64KiB pages in the memory, which is also the initial number of pages.

max Optional

The maximum number of 64KiB pages in the memory.

Description

WebAssembly memories provide raw working memory for Wasm modules. The memory definition itself declares the data store, while data definitions can be used to initialize a memory with data. For example:

(module
  (memory $my_mem 1 2)
  (data $greeting (memory $my_mem) (i32.const 0) "Hello world")
  ;; ...
)

Each memory is defined as a number of "pages", each one 64KiB (65,536 bytes) in size. After the optional identifying memory name, the two number values define the minimum (and initial) number of pages, and the maximum number of pages the memory can contain. The data definition is also named, and specifies an identifier for the memory to store the data in. A Wasm module can contain multiple memories, each identifiable by name or index.

If you only have one memory in your module, or you want to store the data in the first memory in the module, you can omit the memory name and identifier, like so:

(module
  (memory 1 2)
  (data $greeting (i32.const 0) "Hello world")
  ;; ...
)

By default, the data is written to memory 0.

Once a memory has been created, there are several memory instructions available for manipulating it. You can find more details about using Wasm memories in WebAssembly memory.

Manipulating Wasm memories from JavaScript

WebAssembly memories can be exported from a Wasm module:

(module
  (memory (export "memory") 1)
  (data $greeting (i32.const 0) "Hello world")
  ;; ...
)

Over in the JavaScript host, they are then available in the relevant exports object, for example:

WebAssembly.instantiateStreaming(fetch("module.wasm")).then((result) => {
  const mem = result.instance.exports.memory;
  // ...
});

The memory is represented by a JavaScript WebAssembly.Memory object instance, which can be viewed and modified using typed array objects or DataView objects. See memory.init for an example.

You can also create a new memory using the JavaScript WebAssembly.Memory() constructor and import it into a Wasm module.

Specifications

Browser compatibility

See also

• WebAssembly memory instructions
• WebAssembly.Memory JavaScript API