Module hb_beamr_io.erl

Simple interface for memory management for Beamr instances.

Description

It allows for reading and writing to memory, as well as allocating and freeing memory by calling the WASM module's exported malloc and free functions.

Unlike the majority of HyperBEAM modules, this module takes a defensive approach to type checking, breaking from the conventional Erlang style, such that failures are caught in the Erlang-side of functions rather than in the C/WASM-side.

Function Index

do_read_string/3*
free/2	Free space allocated in the Beamr instance's native memory via a call to the exported free function from the WASM.
malloc/2	Allocate space for (via an exported malloc function from the WASM) in the Beamr instance's native memory.
malloc_test/0*	Test allocating and freeing memory.
read/3	Read a binary from the Beamr instance's native memory at a given offset and of a given size.
read_string/2	Simple helper function to read a string from the Beamr instance's native memory at a given offset.
read_string/3*
read_test/0*	Test reading memory in and out of bounds.
size/1	Get the size (in bytes) of the native memory allocated in the Beamr instance.
size_test/0*
string_write_and_read_test/0*	Write and read strings to memory.
write/3	Write a binary to the Beamr instance's native memory at a given offset.
write_string/2	Simple helper function to allocate space for (via malloc) and write a string to the Beamr instance's native memory.
write_test/0*	Test writing memory in and out of bounds.

Function Details

do_read_string/3 *

do_read_string(WASM, Offset, ChunkSize) -> any()

free/2

free(WASM, Ptr) -> any()

Free space allocated in the Beamr instance's native memory via a call to the exported free function from the WASM.

malloc/2

malloc(WASM, Size) -> any()

Allocate space for (via an exported malloc function from the WASM) in the Beamr instance's native memory.

malloc_test/0 *

malloc_test() -> any()

Test allocating and freeing memory.

read/3

read(WASM, Offset, Size) -> any()

Read a binary from the Beamr instance's native memory at a given offset and of a given size.

read_string/2

read_string(Port, Offset) -> any()

Simple helper function to read a string from the Beamr instance's native memory at a given offset. Memory is read by default in chunks of 8 bytes, but this can be overridden by passing a different chunk size. Strings are assumed to be null-terminated.

read_string/3 *

read_string(WASM, Offset, ChunkSize) -> any()

read_test/0 *

read_test() -> any()

Test reading memory in and out of bounds.

size/1

size(WASM) -> any()

Get the size (in bytes) of the native memory allocated in the Beamr instance. Note that WASM memory can never be reduced once granted to an instance (although it can, of course, be reallocated inside the environment).

size_test/0 *

size_test() -> any()

string_write_and_read_test/0 *

string_write_and_read_test() -> any()

Write and read strings to memory.

write/3

write(WASM, Offset, Data) -> any()

Write a binary to the Beamr instance's native memory at a given offset.

write_string/2

write_string(WASM, Data) -> any()

Simple helper function to allocate space for (via malloc) and write a string to the Beamr instance's native memory. This can be helpful for easily pushing a string into the instance, such that the resulting pointer can be passed to exported functions from the instance. Assumes that the input is either an iolist or a binary, adding a null byte to the end of the string.

write_test/0 *

write_test() -> any()

Test writing memory in and out of bounds.