WebAssembly.Memory.prototype.grow()

Syntax

grow(delta)

Parameters

delta

The number of WebAssembly pages you want to grow the memory by (each one is 64KiB in size).

Return value

The previous size of the memory, in units of WebAssembly pages.

Exceptions

• RangeError: If the current size added with delta exceeds the Memory instance's maximum size capacity.

Examples

Using grow

The following example creates a new WebAssembly Memory instance with an initial size of 1 page (64KiB), and a maximum size of 10 pages (640KiB).

const memory = new WebAssembly.Memory({
  initial: 1,
  maximum: 10,
});

We can then grow the instance by one page like so:

const bytesPerPage = 64 * 1024;
console.log(memory.buffer.byteLength / bytesPerPage); // "1"
console.log(memory.grow(1)); // "1"
console.log(memory.buffer.byteLength / bytesPerPage); // "2"

Note the return value of grow() here is the previous number of WebAssembly pages.

Detachment upon growing

Every call to grow will detach any references to the old buffer, even for grow(0)! Detachment means that the ArrayBuffer's byteLength becomes zero, and it no longer has bytes accessible to JavaScript. Accessing the buffer property after calling grow, will yield an ArrayBuffer with the correct length.

const memory = new WebAssembly.Memory({
  initial: 1,
});
const oldMemoryView = new Uint8Array(memory.buffer);
memory.grow(1);
// the array is empty!
console.log(oldMemoryView); // Uint8Array []

const memory = new WebAssembly.Memory({
  initial: 1,
});
memory.grow(1);
const currentMemoryView = new Uint8Array(memory.buffer);
// the array is full of zeros
console.log(currentMemoryView); // Uint8Array(131072) [ 0, 0, 0, ... ]
// 131072 = 64KiB * 2

For a shared Memory instance, the initial buffer (which would be a SharedArrayBuffer in such case) will not become detached, but rather its length will not be updated. Accesses to the buffer property after growing will yield a larger SharedArrayBuffer which may access a larger span of memory than the buffer from before growing the Memory. Every SharedArrayBuffer from the buffer property will all refer to the start of the same memory address range, and thus manipulate the same data.

Specifications

Browser compatibility

See also

• WebAssembly overview
• WebAssembly concepts
• Using the WebAssembly JavaScript API