Wasmex.Memory (Wasmex v0.3.0)

A WebAssembly instance has its own memory, represented by the Memory struct. It is accessible by the Wasmex.Instance.memory getter.

The Memory.grow methods allows to grow the memory by a number of pages (of 65kb each).

Wasmex.Memory.grow(memory, 1)

The current size of the memory can be obtained with the length method:

Wasmex.Memory.length(memory) # in bytes, always a multiple of the the page size (65kb)

When creating the memory struct, the offset param can be provided, to subset the memory array at a particular offset.

offset = 7
index = 4
value = 42

{:ok, memory} = Wasmex.Instance.memory(instance, :uint8, offset)
Wasmex.Memory.set(memory, index, value)
IO.puts Wasmex.Memory.get(memory, index) # 42

The Memory struct views the WebAssembly memory of an instance as an array of values of different types. Possible types are: uint8, int8, uint16, int16, uint32, and int32. The underlying data is not changed when viewed in different types - its just its representation that changes.

View memory buffer as a sequence of…Bytes per element
int81
uint81
int162
uint162
int324
uint324

Link to this section Summary

Functions

Returns the number of bytes used to represent a unit in memory.

Same as bytes_per_element/1 except the unit size and offset given at memory creation are overwritten by the given values.

Grows the amount of available memory by the given number of pages and returns the number of previously available pages. Note that the maximum number of pages is 65_536

Returns the number of elements that fit into memory for the given unit size and offset.

Same as length/1 except the unit size and offset given at memory creation are overwritten by the given values.

Link to this section Types

Specs

t() :: %Wasmex.Memory{
  offset: term(),
  reference: reference(),
  resource: binary(),
  size: term()
}

Link to this section Functions

Link to this function

bytes_per_element(memory)

Specs

bytes_per_element(t()) :: pos_integer()

Returns the number of bytes used to represent a unit in memory.

For the limited number of unit sizes the byte values are the following:

size | Bytes per element | |----------|---| | int8 | 1 | | uint8 | 1 | | int16 | 2 | | uint16 | 2 | | int32 | 4 | | uint32 | 4 |

{:ok, memory} = Wasmex.Instance.memory(instance, :uint16, 0)
Wasmex.Memory.bytes_per_element(memory) # 2
Link to this function

bytes_per_element(memory, size, offset)

Specs

bytes_per_element(t(), atom(), non_neg_integer()) :: pos_integer()

Same as bytes_per_element/1 except the unit size and offset given at memory creation are overwritten by the given values.

{:ok, memory} = Wasmex.Instance.memory(instance)
Wasmex.Memory.bytes_per_element(memory, :uint32, 0) # 4
Link to this function

from_instance(instance)

Specs

from_instance(Wasmex.Instance.t()) :: {:error, binary()} | {:ok, t()}
Link to this function

from_instance(instance, size, offset)

Specs

from_instance(Wasmex.Instance.t(), atom(), non_neg_integer()) ::
  {:error, binary()} | {:ok, t()}
Link to this function

get(memory, index)

Specs

get(t(), non_neg_integer()) :: number()
Link to this function

get(memory, size, offset, index)

Specs

Link to this function

grow(memory, pages)

Specs

grow(t(), pos_integer()) :: pos_integer()

Grows the amount of available memory by the given number of pages and returns the number of previously available pages. Note that the maximum number of pages is 65_536

Link to this function

grow(memory, size, offset, pages)

Specs

grow(t(), atom(), non_neg_integer(), pos_integer()) :: pos_integer()

Specs

length(t()) :: pos_integer()

Returns the number of elements that fit into memory for the given unit size and offset.

Note that the WebAssembly memory consists of pages of 65kb each. Different unit sizes needs a different number of bytes per element and the offset may reduce the number of available elements.

{:ok, memory} = Wasmex.Memory.from_instance(instance, :uint8, 0)
Wasmex.Memory.length(memory) # 1114112 (17 * 65_536)
Link to this function

length(memory, size, offset)

Specs

length(t(), atom(), non_neg_integer()) :: pos_integer()

Same as length/1 except the unit size and offset given at memory creation are overwritten by the given values.

{:ok, memory} = Wasmex.Instance.memory(instance)
Wasmex.Memory.length(memory, :uint8, 0) # 1114112 (17 * 65_536)
Link to this function

read_binary(memory, index, length)

Specs

read_binary(t(), non_neg_integer(), non_neg_integer()) :: binary()
Link to this function

read_binary(memory, size, offset, index, length)

Specs

read_binary(
  t(),
  atom(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer()
) :: binary()
Link to this function

read_string(memory, index, length)

Specs

read_string(t(), non_neg_integer(), non_neg_integer()) :: String.t()
Link to this function

read_string(memory, size, offset, index, length)

Specs

read_string(
  t(),
  atom(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer()
) :: String.t()
Link to this function

set(memory, index, value)

Specs

set(t(), non_neg_integer(), number()) :: number()
Link to this function

set(memory, size, offset, index, value)

Specs

Link to this function

wrap_resource(resource, size, offset)

Link to this function

write_binary(memory, index, str)

Specs

write_binary(t(), non_neg_integer(), binary()) :: :ok
Link to this function

write_binary(memory, size, offset, index, str)

Specs

write_binary(t(), atom(), non_neg_integer(), non_neg_integer(), binary()) :: :ok