ADR-0016: Virtual functions only at the three run-time boundaries¶
- Status: Accepted
- Date: 2026-11-06
Context¶
The standard said two different things. The library page said Base* interfaces are "the one place above the
bind with virtual functions", while the HAL page defines ManagerBase with pure virtual functions and a virtual
CollectDiagnostics(DiagnosticsSink&), and kb-core's BaseThread is a base class products derive from. A rule
that the code already breaks cannot be enforced, and a checker needs one list it can test against.
Decision¶
Virtual functions are allowed in exactly three places, each a boundary where the concrete type is chosen when the board or product is built, not when the library is written:
- the
Base*peripheral interfaces in kb-core'sinterfaces/base/(the MCU boundary); - kb-hal-common's
ManagerBase,FacadeBaseand the sink interfaces they take, such asDiagnosticsSink(the board boundary); - kb-core's
BaseThreadandBaseThreadsManager(the task boundary).
Everywhere else, including every driver, port, handler and utility, there are no virtual functions; ports use CRTP
(ADR-0003). A class at a boundary is abstract, is never deleted through a base pointer (there is no heap after
start-up, ADR-0004), and declares either a public virtual or a protected non-virtual destructor (C++ Core
Guidelines C.35). The repositories that own a boundary list its folders in .kokeb/handbook.yml, and the
forbidden-patterns/virtual-outside-interfaces check rejects virtual anywhere else.
Consequences¶
- The library page's sentence is corrected to name all three boundaries; rule KB-ARCH-011 says the same.
- Adding a fourth boundary needs a new decision record, not a quiet exception.