I need to update the C API

CNA snapshot c1c316b9  ·  Development › Maintainer Handbook  ·  source links pinned to c1c316b9

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. Everything here was read from the TARGET tree at c1c316b9; 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 443 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, 44, 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, validators), then the family file that owns a neighbouring route and its pure-C smoke test.

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 two sound-effect play routes (0.43.0). 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: clear every out_ handle first, validate second.
• 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.46.0, this snapshot, is 0x00002E00). 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) 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.46.0, but [Unreleased] has no entry for most of them (none for 0.46.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, 469 in-scope headers and 8,142 symbols, of which 7,053 implemented, 15 partial, 631 planned and 443 not applicable, with 451 headers deliberately out of scope (content pipeline, design, diagnostics, inspector, phone, platform, renderers and internal paths, each with a recorded reason). Planned rows by module: graphics 275, content 206, graphics-ext 40, input 30, gamer-services 29, math 27, runtime 19, net 15, audio 10, devices 2, storage 2, media 1.

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 631 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 631, and release_gate.json's note still speaks of 654 content-pipeline declarations although the summary now scopes that module out. Trust the generated summary.

Adding a route (procedure, not executed)

The shortest path that satisfies every gate for a new fallible route in an existing family, derived from 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. Implement it in the owning CnaCApi*.cpp family: clear outputs, CallWithExceptionBarrier, kind and thread through the registry, shared validators. 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. 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, now 0.46.0 (moved from 0.44.0 by a recorded compatibility review at its commit 8219a6c; 0.45.0 was never admitted), so 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 Lab) 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 although find_package and CONSUMING.md (“every minor within a major is additive”) suggest otherwise, so 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. 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; assert behaviour.
• 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: outputs cleared first, barrier, kind and thread, 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.