Subject: Leaked internal types¶
An internal/detail::-namespace type reaches the public ABI by inheritance, by-value embedding, or a shared vtable -- a layout change the author thought was private moves the public class's own size, offsets, or dispatch table.
4 case(s). ← back to all subjects
The pattern¶
These four cases are the same lesson told through four different C++ embedding mechanisms: a plain base class (case74), a by-value member (case75), a polymorphic base's vtable (case76), and a class template's base (case77). In every case the library author changed something living under a detail::/internal namespace -- exactly the convention real projects like oneDAL, oneTBB, and Boost use to signal "do not depend on this" -- and assumed that convention was load-bearing. It is not: C++ has no language mechanism that makes a detail:: type's layout private once something public inherits from it, embeds it by value, or shares its vtable. The size, field offsets, and vtable slots of the public class are a direct, computable function of the internal class's own definition, so any change to the internal type changes the public one's binary contract, with no change to the public type's own source at all. What a maintainer should watch for: grep for detail::/internal::/impl:: base classes and by-value members reachable from any public class, and treat every one of them as public ABI surface unless it is hidden behind a pointer (the pimpl idiom's actual job -- see each case's own "Safe redesign" section). A namespace name is a documentation convention, not an ABI boundary.
Cases¶
| Case | Title | Verdict | Category |
|---|---|---|---|
| case74_detail_base_class_changed | Internal detail:: base class layout change leaks via public API |
🔴 BREAKING | Breaking |
| case75_detail_embedded_by_value | Internal detail:: Struct Embedded by Value |
🔴 BREAKING | Breaking |
| case76_detail_pimpl_vtable_changed | Internal detail:: Polymorphic Base Vtable Change |
🔴 BREAKING | Breaking |
| case77_detail_templated_base_changed | Internal detail:: Templated Base Class Layout Change |
🔴 BREAKING | Breaking |