Modules

This is the modules section of niso_runtime.h, owned by niso-modules and kept in crates/niso-core/include/modules.h. The build composes it with the other sections in the order crates/niso-compose/sections.txt gives.

Functions: niso_dom_define_module, niso_module_settle, niso_module_emit, niso_module_release, niso_dom_module, niso_dom_module_call, niso_dom_set_module_hook

Native modules: APIs an app’s own native code gives its pages, declared in WebIDL as [NisoModule] interfaces. niso-idl generates both sides from the IDL file: the page’s import and the native interface the app implements. This channel between them knows neither side’s language.

Values cross it as value lists: tokens of tag 0 and an f64, or tag 1, a u32 byte length and that much UTF-8. Values flatten in IDL order: a boolean is 0 or 1, numbers and enumeration values are themselves, a nullable value is 0 for null or 1 and the value, a sequence its length and its items, a dictionary its members in order (an optional member with no default 0 when absent, or 1 and the value). A call’s arguments flatten the same way, an optional argument with no default like such a member. Little-endian.

Members are numbered in IDL order: calls (each attribute’s getter, then its setter if it has one, and each operation) from 0, and the event handler attributes (attributes of a callback function type) from 0.

The module side: niso_dom_define_module gives the page module name, whose call function runs on the DOM thread for every call, with the member, its arguments and the call’s id. The module answers with niso_module_settle: status 0 and the result’s value list, or a niso_status and a UTF-8 message the page sees as the matching exception. A synchronous member settles before its call function returns; a member returning a promise settles whenever it is done, from any thread. niso_module_emit sends an event, with its arguments’ value list, from any thread. Both are queued as tasks the DOM’s event loop runs (niso_dom_run), so the page never sees them mid-script; a module sending from another thread wakes its host to run them. The port stays valid until niso_module_release, after the DOM too (what it sends then is dropped); free runs with userdata when the DOM is freed.

The binding side: niso_dom_module finds a module by name, and niso_dom_module_call calls a member: a synchronous call stores the result’s value list in *result (valid until the next call into the DOM) or fails with the module’s error; otherwise *result is empty and the result comes to the module hook as a task, with the call’s id. Events come to the hook with call 0.

typedef struct niso_module niso_module;
typedef void (*niso_module_call_fn)(void* userdata, uint32_t member, const uint8_t* args, size_t len, uint64_t call);
typedef void (*niso_module_hook_fn)(void* userdata, uint32_t module, uint64_t call, uint32_t event, int32_t status,
                                    const uint8_t* value, size_t len);
int32_t niso_dom_define_module(niso_dom* dom, const char* name, size_t name_len, niso_module_call_fn call,
                               niso_drop_fn free, void* userdata, niso_module** port);
void niso_module_settle(niso_module* port, uint64_t call, int32_t status, const uint8_t* value, size_t len);
void niso_module_emit(niso_module* port, uint32_t event, const uint8_t* value, size_t len);
void niso_module_release(niso_module* port);
int32_t niso_dom_module(niso_dom* dom, const char* name, size_t len, uint32_t* module);
int32_t niso_dom_module_call(niso_dom* dom, uint32_t module, uint32_t member, const uint8_t* args, size_t len, bool sync,
                             uint64_t* call, niso_bytes* result);
void niso_dom_set_module_hook(niso_dom* dom, niso_module_hook_fn hook, void* userdata);