The C ABI registry and its gates#
The registry#
The headers under include/anira/abi/ are generated, never edited by hand. The one source is
abi/anira.yml:
pip install pyyaml
python3 -B tools/abi/gen.py --repo . --write # or the anira_abi_regen build target
python3 -B tools/abi/gen.py --repo . --check # exit 2 on any drift
python3 -B tools/abi/gen.py --repo . --diff-against v3.0.0-alpha.3 # additions and BREAKING lines
--write validates the registry against the header conventions of
docs/anira-v3-architecture.md and rewrites:
the headers, and
include/anira/anira_em.h;web/src/abi/enums.ts,layout.tsandbindings.ts;the symbol lists (
abi/symbols-<major>.txt,symbols-draft.txt,symbols-emscripten.txt) and the wasm export list;src/capi/generated/(the status texts,struct_sizes.incbehindanira_sizeof) andtest/abi/generated/;abi/layout-<major>.txtand the enum pages underdocs/sphinx/api/enum/.
Commit the registry with every regenerated file. The anira_abi_generate test and the
build_web workflow run --check. --diff-against <ref> says whether the registry changed
since a tag by appending (a minor or a pre-release) or by breaking (a major). Exit codes: 0 clean,
1 a registry error, 2 drift, 3 usage.
The generated files carry a .clang-format with DisableFormat and a
NOLINTBEGIN(readability-identifier-naming) block, so the pinned root configs stay untouched.
layout.ts is written the way prettier prints it (npx prettier --check src/abi/layout.ts),
and web/.prettierignore lists enums.ts and bindings.ts, so npm run format leaves
them as written.
bindings.ts is the TypeScript face of the C ABI: the class AniraBindings, one method per
entry under its C name, derived from the registry’s types. A new entry needs no TypeScript.
the
anira_error*is made on the instance’s stack, and a failed status throws anAniraErrorwith the entry’s message (or the status text);a
const char*is a JS string (with itssize_t lencomputed when one follows);what an entry writes through a non-const pointer to a scalar, an enum, a handle or a
const char*is returned (one value, or an object by parameter name); a_to_jsonreturns its text;anira_boolis aboolean, a 64-bit integer abigint, a pointer or a size anumber; an enumeration entry and a record the caller passes in keep their pointers.
Writing a registry entry#
Kinds:
verbatim,typedef,define,enum,handles,struct,union,callback,function.A struct field or union arm has exactly one shape:
type(a C type, optionalarrayof 1 or more; in a Tier-1 record a fixed-width scalar or an earlier Tier-1 record);ptr(anANIRA_PTRslot);fields(a named member of an unnamed struct type, arms only);arms(a named member of an unnamed union type, Tier-1 structs only).
No truly anonymous struct, which
-pedanticC++ refuses. The generator refuses a member name repeated within one C scope (the fields of a struct, the arms of a union, the fields of one arm; anANIRA_PTRslot takes bothnameandname_bits):duplicate field <name> in <scope>. Arms may reuse a name across arms.A union is a Tier-1 record (
tier: 1withsizeandalign); the layout table has a row per member, written as its C designator (field anira_sync_token.u.vk.value offset 16 size 8).Record attributes:
struct_id: ANIRA_STRUCT_<X>ties a record toanira_sizeof; every Tier-1 record carries one, and an id without a record is legal and answers 0;function_type: truemakes a callback a function type, for anANIRA_PTRslot only;forward: truepre-declares a struct;padding_free: trueon a Tier-2 struct makestest_layout.cassertsizeofequals the sum of its members on every target (a tail slot that would leave a hole is followed by an explicitreserved).
Header kinds:
draft: trueputs a header underinclude/anira/abi/draft/(file: draft/<name>.h, guardANIRA_ABI_DRAFT_*) withstatus: draftfunctions only, no record, enum or handle. Their names go toabi/symbols-draft.txt, and no umbrella butanira_all.hincludes it. Promotion moves a name between the symbol lists and its declaration into a promised header, without renaming it. A draft function is outside the promise, so--diff-againstlists a changed, removed or promoted one as an addition; a changed arm of a frozen union (an appended one included), a changed signature, thread tag ornonblockingand a removedcallback_safeare breaks.platform: emscriptenmakes a companion for one target (file: anira_<name>.h, its ownguard:). Its body sits inside#if defined(__EMSCRIPTEN__) || defined(DOXYGEN), so it is an empty header natively and a native consumer may include it. It declares functions, callbacks, typedefs and defines only, and no header of the registry includes it (the scope-all umbrellaanira_all.hdoes). Its names go toabi/symbols-emscripten.txtand the wasm export list, never toabi/symbols-<major>.txt,abi/symbols-draft.txt, the link probe or the layout test.
Thread tags: every function carries one from the architecture document’s vocabulary (
main-thread,driver-thread,inference-thread,thread-safe, with qualifiers),callback_safewhere it applies andnonblocking: truewhere the body is real-time. The tag becomes the@par Thread contractline.The generator refuses an entry without a tag, and a nonblocking entry with a 64-bit argument or an
anira_error*.The dual tag
driver-thread | inference-thread(a processor callback, the six context accessors, the two default bodies) requiresnonblocking: trueon an entry, asdriver-threaddoes, but no attribute on the callback typedefanira_processor_fn: whether a processor body is real-time is its own promise (anira_processor_desc.realtime_phases, per phase, checked at prepare).The
inference-threadtypedefanira_engine_process_fncarries nononblockingfor the same reason: the engine’s promise isANIRA_ENGINE_FLAG_REALTIME_SAFE.
The 64-bit allowlist is closed:
anira_now_ns,anira_tensor_init_vulkan,anira_tensor_init_opaque_fd,anira_tensor_init_wgpu_buffer,anira_tensor_init_dmabufandanira_tensor_init_iosurface, whose parameters are vendor handles at their wire width. A seventh needs the same argument.Names: the two descriptors share one scheme.
processor/engineon every level that belongs to one side (anira_processor_desc/anira_engine_desc,_ctx, the_fntypedefs,anira::Processor/anira::Engine);no side on what both lifecycles share (
anira_init_info,anira_prepare_info,anira::InitInfo/anira::PrepareInfo,anira_phase);the verb on the record of a level one side alone has (
anira_engine_load_info,anira::EngineLoadInfo);FLAGin every flag define, so that no flag reads like a value of an enum;Prepared/Loadedfor whatprepare/loadhand back;one callback shape, from the outermost level in:
init(info, user_data)andrelease(user_data);load(info, user_data, &loaded)andunload(loaded, user_data)(the engine alone);prepare(info, user_data, &prepared)for the processor,prepare(info, loaded, user_data, &prepared)for the engine, andunprepare(prepared, user_data); every per-chunk callback(ctx, prepared, user_data).
The provider is the engine’s twin wherever the backend pair travels:
provider/provider_idbesideengine/engine_id, andfrom_*/to_*on the two ends ofanira_edge_info. The pair rule: an id if and only if the value isANIRA_ENGINE_CUSTOM/ANIRA_PROVIDER_CUSTOM. The JSON words of both enums live insrc/capi/words.h.Layout: while
ANIRA_ABI_MAJORis 0,--writerewritesabi/layout-0.txtwith the headers. From the v3.0.0 freeze on, a Tier-1 layout changes only with the ABI major.
Every entry needs its body in the same pull request, on Emscripten too: three presence gates make sure every promised and draft name has a body on every leg (the first row below).
The gates#
target |
what it proves |
|---|---|
|
The shared library exports exactly |
|
No engine runtime and no private dependency ( |
|
Every Tier-1 |
|
Every public header alone and the umbrellas together, as C11 and C++17 with no anira define
under strict flags, |
|
The installed package, shared and static: |
the RTSan leg, |
The suite under RealtimeSanitizer ( |
|
Under node, on the |
An abidiff against the last tag joins the gates at the v3.0.0 freeze.