Module abi 

L0’s ABI over handles: step 2 of todo/l0-interface.md.

The functions a compiled program imports from fjs:l0, with the WASM types of the summary, over super, the typed L0. It is still native Rust: step 3 exports it from a .wasm.

• A value is an i64 handle, an index into a table of naive values, with the slot’s generation in the high 32 bits, so a handle used after its drop traps even when its slot holds a new value. The four constants are the handles 0 to 3, which dup answers as they are and drop leaves alone, and every undefined, null or boolean an L0 function answers is one of them. Every other handle is one owned reference: dup makes a new handle and drop frees one.
• A builder is an i32 handle, an index into a table of open builders, with a generation the same way.
• Bytes cross through with_memory, which stands in for the memory the loader makes.
• Code is a Code in a table, add_code, which stands in for the shared WASM table. A function L0 makes keeps its code index as the item 0 of its NaNVM frame, before the frame the program gave, so one Rust StaticCode runs every code index.
• A throw traps (l0-throw-trap.md). throw keeps the value and traps: in WASM it reaches unreachable, and here it panics with Thrown. A throw from NaNVM’s own Rust code is an Err, turned into a throw only at the export, in call, so nothing is borrowed or half made when it traps. The host reads it through has_thrown, thrown and recover, with enter and leave around each call, which are not L0 imports. catch is a native host’s whole sequence.

A misuse traps as super does, with the text l0.<name>: <reason>, including a handle that names no value, not a value, and bytes out of the memory, out of bounds.

Structs

Thrown

The payload of the panic throw causes in native code. The value is kept apart, in the runtime, for thrown.

Constants

FALSE

The constant false.

NULL

The constant null.

TRUE

The constant true.

UNDEFINED

The constant undefined.

Functions

add_code

The loader’s step that puts a code in the table, answering its index.

begin_array

L0 begin_array.

begin_object

L0 begin_object.

call

L0 call. A throw, from the code or from NaNVM’s own, becomes throw here.

catch

A native host’s call into the program: Ok with the result, or Err with the thrown value, after recover. A misuse panics on. It needs panic = "unwind": with abort, every trap ends the process, and a WASM host catches the trap itself.

concat

L0 concat.

drop

L0 drop. It takes v.

dup

L0 dup.

enter

Marks the start of a call of the host into the program, for recover. Calls may nest, as when the host answers an effect.

find

L0 find.

frame

L0 frame: the item i of the frame the program gave make_function, read through the running function, self_.

from_bool

L0 from_bool: the constant true for any b but 0.

from_f64

L0 from_f64.

from_unit

L0 from_unit. A number that is not a UTF-16 unit traps.

has_thrown

1 when a throw caused the last trap, else 0: the trap was a misuse.

item

L0 item.

join

L0 join.

key

L0 key.

kind

L0 kind.

leave

Ends the call enter marked, after it returned.

length

L0 length.

live

The number of handles in use, besides the constants: for tests of ownership.

make_bigint

L0 make_bigint: a sign and len u64 words at ptr.

make_function

L0 make_function. It takes frame and text, a string or undefined.

make_string

L0 make_string: len UTF-16 units at ptr.

push

L0 push. It takes v.

push_property

L0 push_property. It takes key and v.

read_units

L0 read_units: len units of s from start, written at ptr.

read_words

L0 read_words: len words of b’s magnitude from start, written at ptr.

recover

Makes the runtime ready to go on after a caught throw, and ends the call enter marked. It frees every value handle and builder made after that mark and before the throw: what the abandoned frames held, since a program keeps no handle across a call of the host but its literals, made before any. Then it clears has_thrown. A handle that thrown made stays. Without a mark it frees nothing.

same

L0 same.

seal

L0 seal. It consumes the builder.

sign

L0 sign.

substring

L0 substring.

text

L0 text.

throw

L0 throw: keeps v, which it takes, and traps.

thrown

The value the last throw kept, as an owned handle, or undefined.

to_bool

L0 to_bool.

to_f64

L0 to_f64.

unit

L0 unit.

with_memory

The host’s access to the memory, as a loader writes the program’s bytes.

Type Aliases

Code

The code of a function: (param $self i64) (param $args i64) (result i64) (l0-design.md §12). It borrows both handles and answers an owned one, or calls throw.