Workers

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

Functions: niso_dom_set_worker_runner, niso_dom_set_worker_host, niso_worker_begin, niso_worker_end, niso_dom_terminate_workers, niso_dom_set_waiting, niso_dom_workers_active, niso_dom_set_message_hook, niso_dom_set_handler_hook, niso_dom_worker_started, niso_dom_worker_closing, niso_dom_interrupted

Workers. A DOM can start dedicated workers once a binding sets its worker runner; workers the DOM starts inherit it. A worker’s DOM has a DedicatedWorkerGlobalScope for its window (niso_dom_window) and no document to speak of. While a worker is active, niso_dom_run waits for it in real time rather than skipping its clock ahead; a worker’s own run never skips ahead, and returns once its closing flag is set. Once its workers are idle the window skips ahead again. A worker’s time origin is its parent’s niso_dom_wall_clock when it starts, skips included. Its loads (its script, importScripts, the scripts of the workers it starts) go through the window’s loader on the window’s thread, which answers them in niso_dom_run: a worker waits for its load while the window’s host is not calling niso_dom_run (the wake hook says when to), or is blocked in a long call. Freeing a DOM ends its workers, waiting up to two seconds in all; a worker’s WebAssembly stops between slices of fuel when it ends.

void niso_dom_set_worker_runner(niso_dom* dom, niso_worker_runner_fn runner);

Instead of a runner, a host starts the DOM’s workers on threads of its own; workers it starts do not inherit it, so it sets one on each worker’s DOM too. On the worker’s thread niso_worker_begin makes its DOM there, or returns NULL when the worker was terminated first or its script could not be fetched (it has ended then). The host makes an engine for the DOM, runs the script as a runner does and then the loop until niso_dom_worker_closing, clears the wake hook, frees the engine and calls niso_worker_end, which frees the DOM. Between runs the host says with niso_dom_set_waiting when the worker waits for its wake hook, so its parent stops waiting for it in real time. A host that runs a page in steps of virtual time keeps the clock from skipping ahead while niso_dom_workers_active, as niso_dom_run does. A start that returns false fires error at the Worker. Before it frees the DOM, while its terminate can still run, the host ends the DOM’s workers with niso_dom_terminate_workers.

void niso_dom_set_worker_host(niso_dom* dom, niso_worker_start_fn start, niso_worker_terminate_fn terminate, void* userdata);
niso_dom* niso_worker_begin(uint64_t worker);
void niso_worker_end(niso_dom* dom);
void niso_dom_terminate_workers(niso_dom* dom);
void niso_dom_set_waiting(niso_dom* dom, bool waiting);
bool niso_dom_workers_active(niso_dom* dom);
void niso_dom_set_message_hook(niso_dom* dom, niso_message_hook_fn hook, void* userdata);
void niso_dom_set_handler_hook(niso_dom* dom, niso_handler_hook_fn hook, void* userdata);

The worker’s script ran: messages from and to it start to flow.

void niso_dom_worker_started(niso_dom* dom);

Whether the DOM is a worker’s whose closing flag is set.

bool niso_dom_worker_closing(niso_dom* dom);

Whether the DOM is a worker’s whose parent terminated it: the binding’s engine aborts the running script when this becomes true.

bool niso_dom_interrupted(niso_dom* dom);