grow: Wasm table instruction

Try it

(module
  ;; Define function type
  (type $ret_i32 (func (result i32)))

  ;; table with 0 function slots
  (table $return_funcs 0 funcref)

  ;; Define a function of the specified type
  (func $f1 (type $ret_i32)
    (i32.const 42)
  )

  (elem declare func $f1)

  (func $populate
    (table.grow $return_funcs
      ref.null func
      (i32.const 1)
    )
    (drop)
    (table.set $return_funcs
      (i32.const 0)
      (ref.func $f1)
    )
  )

  (func (export "run") (result i32)
    (call $populate)
    (call_indirect (type $ret_i32) (i32.const 0))
  )
)

WebAssembly.instantiateStreaming(fetch("{%wasm-url%}")).then((result) => {
  const value = result.instance.exports.run();
  console.log(value);
});

Syntax

table.grow identifier

table.grow

The table.grow instruction type. Must always be included first.

identifier Optional

An identifier for the table you want to grow. This can be one of the following:

name

An identifying name set for the table when it was first created. This must begin with a $ symbol, for example $my_table.

index

The table's index number, for example 0 for the first table in the wasm script, 1 for the second, etc.

If the identifier is omitted, it will default to 0.

Type

[initial_value, grow_amount] -> [previous_length]

initial_value

The initial value to set for the new table elements. Its type must be the same as the type initially set when the table was created.

grow_amount

The number of elements to grow the table by. This must be an i32 value, for example (i32.const 1).

previous_length

An i32 equal to the size of the table before the grow instruction is applied to it, or -1 if the table failed to grow, for example due to an out-of-memory (OOM) error or the new size being greater than the table's maximum size.

To retrieve the new table size after the grow instruction is applied to it, use the table.size instruction.

Opcodes

Description

table.grow is used to increase the size of a table by a specified number of elements.

A wasm table can be grown from JavaScript using the table.grow() method.

Examples

Creating, growing, and setting a table

This example shows how to create a table, grow its size, dynamically change the functions stored in it, and then call the function stored in the table at each point.

JavaScript

In our script, we start by grabbing a reference to a <p> element that we will output results to. We then define an obj object containing a function called output() that adds a given value to the textContent of a given element.

We then compile and instantiate our Wasm module using the WebAssembly.instantiateStreaming() method, importing the obj object in the process.

When the result is returned, we invoke the exported Wasm run() function available on the WebAssembly Instance exports object, passing it the outputElem element as a parameter.

<p></p>

const outputElem = document.querySelector("p");

const obj = {
  output: function (elem, val) {
    elem.textContent += `${val} `;
  },
};

WebAssembly.instantiateStreaming(fetch("{%wasm-url%}"), {
  obj,
}).then((result) => {
  value = result.instance.exports.run(outputElem);
});

Wasm

In our Wasm module, we first import the JavaScript output() function, making sure to declare that it has two parameters, an externref and an i32.

Next, we define a function type called $ret_i32, which returns an i32 value. We then define two functions based on this type called $f1 and $f2, which return the values defined within, and forward-declare them using (elem declare func $f1 $f2) so they can be referenced later on. Next, we define a table called $func_table, which stores function references (hence funcref being specified) and is initially empty.

Finally, we export the run() function, which takes an externref named $elem as a parameter. Inside the function body, we:

• Use table.grow to grow the table size by 1, with an initial ref.null value, checking whether the operation result is -1, which would indicate failure.
• Set our table element to contain the $f1 function using table.set, then call the imported $output function, passing it as parameters the $elem externref passed into the output() function, and the value returned by the $f1 function, which is being referenced from the table using (call_indirect (type $ret_i32) (i32.const 0)).
• Set our table element to contain the $f2 function using table.set, then call the output() function again.

(module
  ;; Import output function
  (import "obj" "output" (func $output (param externref) (param i32)))

  ;; Define function type
  (type $ret_i32 (func (result i32)))

  ;; Define basic functions that return i32s
  (func $f1 (result i32)
    (i32.const 42)
  )
  (func $f2 (result i32)
    (i32.const 100)
  )

  (elem declare func $f1 $f2)

  ;; Define an initially empty table of funcrefs
  (table $func_table 0 funcref)

  (func (export "run") (param $elem externref)
    ;; Grow the table by 1, setting the initial value to null.
    ;; Check the result for -1, which indicates failure.
    (if
      (i32.eq
        (table.grow $func_table
          ref.null func
          (i32.const 1)
        )
        i32.const -1
      )

      ;; Trap if we failed to grow the table
      (then unreachable)
    )

    ;; Set the first function in the table to f1
    (table.set $func_table
        (i32.const 0)
        (ref.func $f1)
    )

    ;; Call the output function, to output the table
    ;; function's return value to the DOM
    (call $output
      (local.get $elem)
      (call_indirect (type $ret_i32) (i32.const 0))
    )

    ;; Set the first function in the table to f2
    (table.set $func_table
        (i32.const 0)
        (ref.func $f2)
    )

    ;; Call the output function, to output the table
    ;; function's return value to the DOM
    (call $output
      (local.get $elem)
      (call_indirect (type $ret_i32) (i32.const 0))
    )
  )
)

Result

The output is as follows:

This makes sense, as each time the output() function is run from inside the wasm module, the value passed into it as its second parameter is printed into our result <p> in the DOM. Each value is the value returned by the $f1 and $f2 functions — 42 and 100 respectively.

Specifications

Browser compatibility

See also

• table.set
• table.size