#Module js

What the JavaScript engine (native/js, a C guest) needs from the browser beyond the web API itself: the console with its levels, uncaught exceptions with their position, compiled code handed back for the bytecode cache, the local time zone, and the bookkeeping of the wrappers that keep DOM nodes alive (a node referenced by a JavaScript object is "pinned": it is not freed when it leaves the tree, and a detached tree is freed once nothing pins it any more).

Exposed to: Window, Worker. Source: api/js.widl.

Odin: import "wren:js".

#Types

#enum ConsoleLevel : i32

The level of a console message.

#struct WrappedNode

A new node of the realm's own document with what its wrapper needs (Node_wrap's work in the same call).

#Functions

#Engine_console

void Engine_console(ConsoleLevel level, usvstring text)

console.log / info / warn / error / debug..., the arguments already formatted.

Host: Engine_console :: proc(c: ^Call, level: Api_ConsoleLevel, text: string)

#Engine_reportException

void Engine_reportException(usvstring message, usvstring stack, usvstring source, i32 line, i32 column)

An exception nothing caught (after the error event, when no handler cancelled it): message, stack, and where it was thrown (source URL, 1-based line and column; 0 when unknown).

Host: Engine_reportException :: proc(c: ^Call, message: string, stack: string, source: string, line: i32, column: i32)

#Engine_storeBytecode

void Engine_storeBytecode(bytes code)

The bytecode of the script being run (asked for with a flag of wj_eval_script): the browser keeps it in its bytecode cache under the key it computed for that script.

Host: Engine_storeBytecode :: proc(c: ^Call, code: []u8)

#Engine_timezoneOffset

i32 Engine_timezoneOffset(f64 time_ms)

Minutes to add to local time to get UTC at time_ms (ms since the Unix epoch), as Date.prototype.getTimezoneOffset.

Host: Engine_timezoneOffset :: proc(c: ^Call, time_ms: f64) -> i32

#Engine_timeZone

string Engine_timeZone()

The IANA name of the local time zone ("Europe/Paris"; "UTC" when unknown), for Intl.

Host: Engine_timeZone :: proc(c: ^Call) -> string

#Engine_locale

string Engine_locale()

The language of the user interface ("en-US"), for Intl.

Host: Engine_locale :: proc(c: ^Call) -> string

#Engine_jitCompile

i32 Engine_jitCompile(bytes module)

Machine code for a hot function (the engine's JIT, native/js/jit): module is a WebAssembly module whose imports are the engine's own exports (module "e") and that exports one function "f". The browser compiles it, instantiates it next to the engine (same store, same memory) and puts "f" in the engine's function table: the result is that table index, 0 when it refused (javascript.jit.* limits, invalid module, not the realm's engine), or minus a ticket when it compiles it in the background: Engine_jitPoll then tells when it is ready.

Host: Engine_jitCompile :: proc(c: ^Call, module: []u8) -> i32

#Engine_jitPoll

i32 Engine_jitPoll(i32 ticket)

The table index of the function of an Engine_jitCompile ticket once compiled and attached; -1 while it still compiles; 0 when it failed (the ticket is then forgotten).

Host: Engine_jitPoll :: proc(c: ^Call, ticket: i32) -> i32

#Node_wrap

u32 Node_wrap(Node node)

A JavaScript object (its wrapper) now refers to node: pins it (it stays alive while pinned, even out of the tree) and returns the wrapper's interface, an index into the engine's interface table (gen/bindings.c) chosen from the node's type, namespace and local name (HTMLDivElement, SVGSVGElement, Text...). One call per new wrapper.

Host: Node_wrap :: proc(c: ^Call, node: Api_Node) -> u32

#Document_createElementWrapped

WrappedNode Document_createElementWrapped(string local_name) raises

document.createElement(localName) in the realm's own document (Document_createElementChecked: its checks, its errors, a defined custom element constructed before it returns), then Node_wrap's pin and interface: one call for the element and its wrapper. A custom element's constructor may have made the wrapper already: the engine then drops the extra pin.

Raises: returns an Error (see web).

Host: Document_createElementWrapped :: proc(c: ^Call, local_name: string) -> (Api_WrappedNode, Api_Error)

#Document_createTextWrapped

WrappedNode Document_createTextWrapped(string text) raises

document.createTextNode(data) in the realm's own document, then Node_wrap's pin and interface.

Raises: returns an Error (see web).

Host: Document_createTextWrapped :: proc(c: ^Call, text: string) -> (Api_WrappedNode, Api_Error)

#Node_unpin

void Node_unpin(u64 node)

That object is gone (called while the engine collects garbage: a handle that died meanwhile is ignored). A detached tree no longer pinned anywhere is freed.

Host: Node_unpin :: proc(c: ^Call, node: u64)

#Node_treeRoots

void Node_treeRoots(u64[] nodes, out bytes roots)

For each node, the root of its tree as a u64 in roots (8 bytes per node): 1 for a node of the document's own tree, else the handle of its topmost ancestor (itself when it has none), 0 for a dead handle. The engine keeps the wrappers of one tree alive together.

Host: Node_treeRoots :: proc(c: ^Call, nodes: []u64, roots: []u8)

Edit this page on GitHub