I need to update the C API

CNA snapshot 3b43bd86  ·  Development › Maintainer Handbook  ·  source links pinned to 3b43bd86

Use this recipe when a change touches modules/c-api, a public C++ header the C layer adapts, or anything the C ABI records about itself: its version, layout baseline, coverage inventory or release gate. The C layer is a second ownership model over the canonical C++ surface and has more mechanical gates than any other module; most read files rather than a built library, so they register and run in an ordinary tests build. Since the 0.1.0 release its route boundaries are generated: a route is a header declaration plus one spec line, and only the logic of a complex route is written by hand. Everything here was read from the TARGET tree at 3b43bd86; nothing was configured, built or run for this page.

Find the owner

The C layer lives in one module and is meant to change in the same commit as the C++ it adapts (docs/c-api/README.md). Its pieces and their checks:

First decide whether the change belongs in the ABI at all. The inventory records 453 public C++ symbols as having no C form (templates over types C cannot name, protected hooks, the platform substrate, renderer implementations behind IGraphicsRenderer). Touching such a symbol needs no route but must leave the inventory consistent. The scope rules are in generate_coverage_inventory.py: MODULE_SCOPE classifies every module, so a new module stops the gate instead of inheriting a default.

Read first

1. abi.h: CNA_ABI_VERSION_MAJOR/MINOR/PATCH (0, 50, 0), CNA_ABI_VERSION_ENCODE, CNA_Result codes 0–14, CNA_Handle.
2. docs/c-api/ABI_VERSIONING.md: the 0.x rule, the four evolution paths, the recorded-baseline section.
3. OWNERSHIP.md, HANDLES.md and CALLBACKS_AND_THREADING.md, then C API internals for how the code implements them; this page does not repeat that trace.
4. CnaCApiDetail.hpp (CallWithExceptionBarrier, HandleRegistry, ObjectKind, the named refusals), then the family’s spec in modules/c-api/spec, the CnaCApi<Family>.cpp that owns a neighbouring route, and its pure-C smoke test.
5. GENERATED_ROUTES.md: the route kinds (value, get, call, size, copy, release, result), which conversions the generator applies, and when a route is a hand-written helper.

Contracts a route must keep

• Handles are 64-bit: a 1-based slot in the low 32 bits, a generation in the high 32. HandleRegistry::Get refuses a stale generation or wrong ObjectKind (CNA_RESULT_INVALID_HANDLE) and a foreign creation thread (CNA_RESULT_THREAD); Release and the user-tag accessors check the thread too; only GetFromAnyThread skips it, for the sound-effect play lookup (0.43.0). Once a slot's last 32-bit generation is released the slot is retired, not wrapped. There is one process-wide registry. The kind is the only type guard, so resolving a handle under the wrong C++ type is undefined behaviour, not an error.
• The exception barrier is positional. Catch arms are ordered most-derived first, so a new or re-parented native exception can land in a different arm; CApi_BoundaryDetail pins representative mappings only.
• Threading is part of the contract. A refusal that Get raises only because another thread created the handle is noted, and with cna_game_set_foreign_thread_calls_ext on (0.39.0, off by default) CallWithExceptionBarrier re-runs the whole route body on the game thread while the caller blocks; the game thread serves the queue at the start of each update and draw and in cna_game_run_foreign_thread_calls_ext (0.41.0). A new route that resolves its handles through the registry gets this for free; a route that must itself run on the game thread has to refuse with a THREAD that is not noted, as driving or destroying the game does. Allowing a route on any thread, or in a new phase (before the run, in an event handler), is a rule change that takes a minor.
• A refused creation leaves the output invalid: the generated half of a route clears every handle output to CNA_INVALID_HANDLE and refuses a null output before a helper runs, and checks faults in one order (a null output, then a non-canonical CNA_Bool, then a refused argument, then handles in parameter order).
• Structures are versioned prefixes (struct_size >= sizeof, struct_version == 1); fields are appended, never reordered. Every CNA_Bool route refuses bytes other than 0 and 1, held by the generated CApi_BoolContractSmoke.
• Ownership is written into the header. OWNERSHIP.md names six categories (owned, borrowed, retained, transferred, callback context, caller buffer) and calls a declaration incomplete until its Doxygen names one. No test enforcing this was found; it is a review obligation.
• Owned children block their parent: cna_game_destroy answers CNA_RESULT_INVALID_STATE while an owned graphics resource, content manager, audio resource or game component lives. Event registrations are the deliberate exception. A new owned child type must join the relevant counter, not only the registry.
• Two language levels. Headers are held to C99 (23 declared matrix cells across 7 toolchains); CNA's C targets compile as C17 with extensions off and warnings as errors.

ABI version discipline

The ABI version is independent of the product version string and of Sharp Runtime's; docs/releasing.md says it “moves when the ABI changes, independently of a product release”. It is defined once, by three macros in abi.h, encoded major<<16 | minor<<8 | patch (0.50.0, this snapshot, is 0x00003200). Everything else derives from or is held against them:

When the version moves

While the ABI is 0.x, an incompatible change needs a minor increment, release notes and a regenerated baseline; from 1.x, only additive changes within a major, and any removal or meaning change needs a new major. CNA also increments the minor for additive generations (0.36.0, 0.38.0, 0.39.0 and 0.41.0 each added one route; 0.50.0 added seven routes and some constants) and for a rule that widens with every signature unchanged, “because a consumer needs a number to require”. ABI 1.0 is a separate decision the release gate says it does not make.

How a version is bumped

Read from the tools and workflows; not executed. No script bumps the version: each step is a manual edit that a gate then holds.

1. Edit the macro in abi.h; repeat the literal nowhere that is not gated.
2. With the library built: python3 tools/c-api/generate_abi_baseline.py --write --library <build>/modules/c-api/libcna_c_api.so, and review the abi_baseline.json diff. Additions are permitted; a moved field, changed constant or vanished export is named an ABI break.
3. Write the entry at the top of ABI_VERSIONING.md and keep the export counts in the four gated documents equal to the baseline (check_doc_export_counts.py --check).
4. python3 tools/c-api/check_release_gate.py --write regenerates RELEASE_GATE.md, whose “Release” line names the ABI version.
5. Add a CHANGELOG.md entry under [Unreleased] (the entries that moved the ABI to 0.29.0, 0.31.0 and 0.33.0 name what was removed, the deltas and the deciding plan row). Practice is uneven: ABI_VERSIONING.md records every step from 0.30.0 to 0.50.0, but CHANGELOG.md names only some of them ([Unreleased] names 0.48.0 and 0.49.0, nothing names 0.47.0 or 0.50.0), so read the history in ABI_VERSIONING.md.
6. Leave the installed-consumer example's find_package(CNA 0.1 CONFIG) alone: it requests the version it was written against on purpose. Bindings are updated separately (below).

The coverage inventory and the release gate

generate_coverage_inventory.py parses modules/*/include/{Microsoft,CNA}/**/*.hpp with Doxygen (Internal and Detail path segments excluded) and maps every declaration through the rules. Read the numbers from the generated summary: at TARGET, 466 in-scope headers and 8,134 symbols, of which 7,033 implemented, 15 partial, 633 planned and 453 not applicable, with 406 headers explicitly excluded (content pipeline, design, diagnostics, inspector, phone, platform, renderers, internal paths and the build-time content import and pipeline subtrees, each with a recorded reason). Planned rows by module: graphics 252, content 203, graphics-ext 36, input 32, math 32, gamer-services 28, runtime 19, net 14, audio 11, devices 2, media 2, storage 2.

The release gate reads Not ready: nine criteria are recorded as met, and one, “No public C++ symbol is unaccounted for”, is recorded as not met because of those 633 rows. MODULE_SCOPE at TARGET classifies every module that exists, design, diagnostics and inspector included, so the scope check the inventory runs first has an answer for each; the gate was not re-run for this page. The gate is built to fail in both directions: check_release_gate.py fails when a criterion recorded as met stops being met and when one recorded as blocked has quietly become met, so closing the last planned row also forces a change to release_gate.json. It governs publishing an experimental release only.

The inventory tools need Doxygen and the sibling sharp-runtime checkout (the workflows install Doxygen and run scripts/ci/clone_siblings.sh); the ABI-header, route-coverage, bool-contract and compatibility checks need only Python and a C compiler. Two documentation gaps: the per-task open-row counts in plans/plan_binding.md (320 for CBIND-127) are not kept equal to the generated 633, and the gate’s release note still records 654 content-pipeline declarations under an open task although the summary scopes that module out. Trust the generated summary.

Adding a route (procedure, not executed)

The shortest path that satisfies every gate for a new route in an existing family, derived from GENERATED_ROUTES.md, existing routes and tests. A new handle kind grows steps 3–4; a new module grows the scope row above.

1. Write the contract first. Owned, borrowed, retained, transferred or copied; which thread; which result codes; whether a child count is involved. Put it in the Doxygen of a declaration that is C99, CNA_C_API-marked, cna_-prefixed and fixed-width only (no long, size_t, bool or bit-fields).
2. Classify the ABI change with the table above.
3. Generate it. A mechanically regular route (a property read or write, a command, a value computation, a text size/copy pair, a destroy with nothing to undo) is one line in modules/c-api/spec/<Family>.toml. A route with real semantics (a creation that publishes and counts, an event, a bulk transfer) is a result line in the family’s [helpers] group that calls a hand-written helper named after the route in CamelCase, in CnaCApi<Family>.cpp; the generated half supplies the exception barrier, the null-output refusal, the cleared handle outputs and the CNA_Bool check, so the helper does not repeat them. Run python3 tools/c-api/generate_routes.py and commit the spec, the helper and the regenerated .inc together. Only the cna_error_* queries and cna_get_abi_version are written whole by hand; a new fully manual entry point needs a written reason. A new source file must be added to the explicit add_library(cna_c_api ...) list.
4. If it owns a resource, add an ObjectKind, a parent token and, for a game child, the matching owned counter so cna_game_destroy refuses while it lives. The ELF map exports cna_* by pattern, as does the macOS exported-symbols list (_cna_*, CnaCApiExports.darwin.txt), and the wasm export list is generated from the headers (generate_wasm_exports.py); neither is edited.
5. Write the pure-C test with <CNA/C/cna.h> and CnaTestReport.h (CNA_TEST_FAIL(n) names the failing stage). Cover success, a refused argument (output stays CNA_INVALID_HANDLE), a stale handle, the wrong thread, and child-before-parent destruction. Register it beside its neighbours: add_executable, C_STANDARD 17, C_EXTENSIONS OFF, link cna_c_api, cna_c_api_enable_strict_warnings, add_test(NAME CApi_…), and SDL_VIDEODRIVER=dummy where a window opens.
6. Route-test coverage. CApiRouteTestCoverage has a budget of 0 uncovered routes and counts a route as covered when any file under tests/ or examples/ names it, the generated GeneratedRoutesSmoke.c included, so a generated route is “covered” before anyone tests what it computes. If the route takes a CNA_Bool, run generate_bool_contract_test.py --write or CApiBoolContractCurrent fails.
7. Record layout and exports (generate_abi_baseline.py --write --library ..., additions only expected), then check_declared_exports.py --library ..., which compares declared and exported names both ways.
8. Update the inventory: mapping rule, then generate_coverage_inventory.py --write and generate_limitations.py --write; a route that closes a planned row should lower the count.
9. Bump the version and update ABI_VERSIONING.md, CHANGELOG.md and the family document (AUDIO.md, GRAPHICS_DEVICE.md, …).
10. Run the gates below, and the installed-consumer check if headers, exports or packaging changed.

Tests and gates

CNA_BUILD_C_API=ON requires CNA_ENABLE_NET=ON (a configure-time refusal otherwise) and is OFF in every shipped preset. Pair a lifetime change with a sanitizer tree: the process-exit crash in this module was found and proved with AddressSanitizer, and CApiAbiBaseline forwards CNA_SANITIZE so a sanitized tree can still run it. See debug shutdown and lifetime.

What a C++ change costs downstream

The maintained external binding, CNA.NET (cna-dotnet), is a separate repository on its own cadence. It admits exactly one reviewed ABI point, 0.47.0 (admitted at its commit f1f88e1, 13 October 2026, after 0.46.0 at 8219a6c), so it refuses the 0.50.0 library of this snapshot, and every new minor, additive, incompatible or rule-only, needs a reviewed point there before CNA.NET accepts the library. The eight archived bindings (Common Lisp, Go, Java, Python, Ruby, Rust, Swift and TypeScript, kept in CNA Cemetery) are frozen at their final revisions and receive no C API change; they stopped at 0.21–0.23 (Common Lisp) and 0.35.0 (the other seven), and none is qualified against this ABI (per-binding table on the bindings boundary). For a C API change this means: (a) a 0.x minor is not backwards compatible, yet find_package accepts every later 0.x; ABI_VERSIONING.md and CONSUMING.md therefore ask a 0.x consumer to refuse at startup, through cna_get_abi_version(), any minor it was not written against (hello_cna.c shows the check), and a binding that admits a range trusts a rule, not a guarantee; (b) an additive route is invisible to a binding until its own manifest adds it (the C# binding compiles a matrix, the archived Python binding's loader refuses a missing export by name); (c) a rule-only minor changes no export, so only the binding's own refusals, threading and tests reveal it; (d) CNA cannot run the bindings' suites, so the evidence a maintainer can hand over is the regenerated baseline, the header diff and the release notes. The migration shapes are on the C# page (and, as records, on the archived Java and Python pages), and the propagation checklist is in C API and bindings architecture.

Traps

• Green ordinary build, broken C layer. Build cna_c_api in a CNA_BUILD_C_API=ON tree before claiming a wrapped-header change is unaffected, or say plainly that you did not.
• A defined result code nothing returns. CNA_RESULT_SHUTTING_DOWN (13) is declared, mapped to an error category and documented in HANDLES.md (“runtime is closing or closed”), yet searching modules/c-api/src finds no route returning it; a stale handle answers INVALID_HANDLE. Do not document or test behaviour the implementation lacks.
• Static destruction. The registry is a function-local static in CnaCApiRuntime.cpp that owns games; an atexit handler registered once a game exists destroys what is left before the libraries a device loaded are finalized. CNA made the platform bookkeeping it depends on immortal because reverse-order destruction otherwise read freed memory at exit; a new process-lifetime static that a Game destructor touches must follow that idiom.
• A finalizer is not a destroyer. A garbage-collected wrapper releasing children on another thread gets CNA_RESULT_THREAD and loses the handle.
• Counting a mention as a test. CApiRouteTestCoverage passes on a name appearing in any test source, the generated contract test included; that test proves the boundary rules, not what the route computes, so assert behaviour in the family’s own smoke test.
• Editing a generated file. src/generated/*.inc and GeneratedRoutesSmoke.c are rewritten by the generator and checked by CApiGeneratedRoutesCurrent; change the spec or the helper instead.
• Caller-created devices. cna_graphics_device_destroy disposes without a child-count check in its route body, and that is the documented contract: graphics_device.h says resources on a caller-created device belong to it and are released with it (GraphicsDevice::Dispose disposes its resource list), so destroying the device first is permitted. The pure-C tests still destroy resources first, and what a child handle answers after its device is gone is not pinned by a test. Treat that part as an open rule.

Review checklist

• Header: C99 only, ownership category, thread rule and result codes written down.
• Implementation: a spec line where one suffices, otherwise a result helper; generated files regenerated and committed with their sources; kind and thread through the registry, child counter, callback re-entrancy rules kept.
• ABI: change class named; abi.h, baseline, ABI_VERSIONING.md, CHANGELOG.md, release-gate record and prose export counts agree.
• Tests: a pure-C test that fails when the route is wrong; the destroy-order and wrong-thread cases; which gates ran, which need a built library, which were not run.
• Inventory: no unreviewed planned row, no rule widened without the approval flag, limitations regenerated.
• Bindings: the ABI point CNA.NET admits and whether the change needs a new one, the fact that the archived bindings are not updated, and any removal, renumbering or rule-only widening called out.

Related: Ownership and lifetime master map, Thread and callback map, Blast radius and readiness, Make a release and Change public XNA behaviour.