Internals

CNA snapshot 009d40f5  ·  Development › Internals overview  ·  source links pinned to 009d40f5

Internals pages are source tours: they follow one subsystem from construction to teardown through the code as it stands at snapshot 009d40f5, naming the types, functions, ownership rules, failure modes, CMake wiring and tests involved. They answer “how does this actually work?”; the Maintainer Handbook answers “how do I change it safely?”.

How an internals page is organised

A page is only useful to a maintainer if it can answer the same questions for every subsystem. The pages in this section are written to cover, where the subsystem has them:

1. Purpose and boundary — what the subsystem owns and what it deliberately does not.
2. Important types and their relationships, and its dependencies.
3. Construction and ownership — who creates, retains, borrows and destroys each object.
4. Runtime path and state — the normal call flow and the mutable state it touches.
5. Threading — which thread may call what, and which barriers are actually proven in the source.
6. Failures — guards, exceptions, rollback, and whether an attempt can be retried.
7. Destruction — the order that matters, and why.
8. Invariants that later edits must not break.
9. Test evidence and gaps — the tests that exist, what each can and cannot show, and what has no test.
10. Realistic changes and the other subsystems they touch, and a curated reading order through the source.

Diagrams on these pages describe actual paths in the source, not a wish. A page states its evidence basis under its title: source-verified means checked by reading the pinned source; a test being named means it exists, not that it was run.

The internals map

Which modules and renderer families have a dedicated page, and which do not yet, is tabulated mechanically in the generated module index. The maps one level up — how the layers fit together — are the Architecture maps.

Reading orders by goal