Conventions

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

The hand-written part of the niso C API: types and runtime functions that do not come from WebIDL. The generated niso.h includes this file.

Rules every caller follows:

• All calls are synchronous and happen on the thread that created the DOM.
• Strings are UTF-8 plus length, never NUL-terminated.
• Strings and arrays returned through out parameters stay valid until the

  next call into the same DOM. Copy them before calling again.

• Functions return 0 on success or a niso_status error code; the message is

  in niso_dom_last_error().

• Handles are generational: a stale handle is NISO_INVALID_HANDLE, never a

  different object. 0 is the null handle.

• A handle stays usable only while something holds it: the document (for

  connected nodes), a detached tree that something else holds, or a
  niso_retain. niso_dom_collect() drops everything else.

• Callbacks passed with a drop function are owned by the DOM, which calls

  drop exactly once when it no longer needs them. Drop functions must not
  call back into the DOM.

• A WebIDL dictionary is a struct in niso.h whose fields follow the order

  the IDL declares its members in, inherited members first. A member added
  later goes at the end, so existing fields keep their offsets: in
  niso_add_event_listener_options, capture, passive and once are where they
  were, and has_signal and signal (AbortSignal) come after them.