Nanyx
PlaygroundPackages

host.memory

A host's access to linear memory, for the foreign functions it calls

Only a host imports nanyx/host.memory, to pass buffers to and from the foreign functions it calls. How hosts use it is described in Hosts.

Reference

A host’s access to the WebAssembly module’s linear memory, where it passes buffers to and from the foreign functions it calls (those declared with @extern). An address is an I32, the place of a byte in memory.

These are the only unchecked operations a host performs. Nothing checks that an address is in a block the host allocated, or that a read or a write stays inside it: one outside the module’s memory traps, as WebAssembly does, but one inside it where the host has no block reads or overwrites the program’s own data. Every function requires HostRuntime, so only a host can call them.

allocate

def allocate: [HostRuntime] I32 -> I32

A new block of size bytes, whose address nothing else is given until the block is given back with free. Its bytes are not cleared.

free

def free: [HostRuntime] I32 -> ()

Gives back the block at address, which allocate made. The block must not be read, written or freed again.

readByte

def readByte: [HostRuntime] I32 -> I32

The byte at address, from 0 to 255.

writeByte

def writeByte: [HostRuntime] I32, I32 -> ()

Writes the low 8 bits of value at address.

readI32

def readI32: [HostRuntime] I32 -> I32

The I32 in the 4 bytes at address, little-endian.

writeI32

def writeI32: [HostRuntime] I32, I32 -> ()

Writes value in the 4 bytes at address, little-endian.

readI64

def readI64: [HostRuntime] I32 -> int

The I64 in the 8 bytes at address, little-endian.

writeI64

def writeI64: [HostRuntime] I32, int -> ()

Writes value in the 8 bytes at address, little-endian.

addressOf

def addressOf: [HostRuntime] string -> I32

Where the bytes of text are, in UTF-8. When text is held in a name, a parameter or a def, it is kept alive for as long as the code uses the address, or a value made from it, such as addressOf(text) + 4. A string made in the argument itself, as in addressOf(a ++ b), is not: give it a name first. Writing at the address changes text, which must not be done.

byteLength

def byteLength: [HostRuntime] string -> I32

How many bytes of UTF-8 text takes, which addressOf gives the first of.

hostState

def hostState: [HostRuntime] () -> I32

The address of 4096 bytes the module sets aside for its host, all zero when the program starts: where a host keeps what it needs from one call to the next, such as how much of standard input it has read, and the small buffers it passes to foreign functions, without allocating. Nothing else reads or writes them.

keepAlive

def keepAlive: [HostRuntime] string -> ()

Keeps text alive until here. Reference counting follows an address of text only through values made from it, not through memory: when the address is written into memory that a foreign function reads, as an iovec is for WASI’s fd_write, call this after the foreign function.

stringAt

def stringAt: [HostRuntime] I32, I32 -> string

A new string holding a copy of the length bytes at address, which are taken to be UTF-8.