#Web API of Wren (Wasm imports)

Every function a page or worker module can import, generated from api/*.widl. The same description produces the host trampolines (src/page/api_generated.odin), the Odin guest SDK (sdk/odin), these pages and the conformance tests (examples/apiconformance, src/tools/apiconformance).

#The Odin SDK

sdk/odin is a collection of packages, one per area of the API: a module, or the modules of one package below. A program names the collection when it is built and imports the packages it uses:

import "wren:core"   // errors, host objects, promises, buffers, events: what every other package uses
import "wren:dom"

odin build . -target:freestanding_wasm32 -no-entry-point -default-to-nil-allocator -collection:wren=<path to sdk/odin>

• wren:core holds the modules web, async, events.
• wren:webcodecs holds the modules webcodecs, webcodecs_audio_decoder, webcodecs_codec, webcodecs_encoders, webcodecs_image, webcodecs_video_decoder.
• any other module is the package of its name (module dom is wren:dom).

Names are the Web IDL names of this description, without an interface prefix that repeats the package's name: Fetch_promise of module fetch is fetch.promise, console_log is console.log, URL_parse is url.parse (the prefix compared without case); a prefix naming one interface among several of the package stays (dom.Node_appendChild, dom.Document_getElementById), and so does one whose rest would be an Odin keyword or a builtin the wrappers call. A function's page says its Odin name when it differs.

#ABI

Addresses and lengths are i32 for a module whose memory 0 is 32-bit and i64 for a memory64 module: the browser defines each import with the width of the importing module's memory 0, which is the memory every pointer refers to (other memories of a multi-memory module are not visible to the browser).

Results:

• a number, bool, enum or handle is the wasm result;
• a string (or bytes) result takes two more parameters, a buffer (address, capacity) the browser fills with what fits; the wasm result (address-sized) is the full length, so a guest can retry with a bigger buffer;
• a function that raises returns an i32 status: 0, or a negative Error; its result, if any, is written to a return pointer (the last parameter; a string result keeps the buffer convention, a negative length being the error); the message of the last error is Exception_message (module web);
• a struct result is always written to a return pointer (C layout, natural alignment).

A pointer outside the memory is a trap (as an out-of-bounds load would be). An argument the browser cannot accept (invalid UTF-8 in a string, a handle that is not live or of another kind, an enum out of range) is an error for a function that raises (Type, Invalid_Handle, Invalid_Argument) and a trap for one that does not.

Availability: Window = page modules, Worker = dedicated worker modules; a worker module that imports a function not exposed to workers is not instantiated.

#Modules

1601 imports in 1502 functions.

Edit this page on GitHub