The Fragile Base Class Problem in Compiled Hierarchies

A header change that recompiles cleanly can still break every program that was compiled against the previous version, and the breakage surfaces as a crash in a client that was never edited. The class of failures has a name — the fragile base class problem — and it is not a defect in one compiler. It follows from the fact that a class definition is simultaneously an interface, a memory layout, and a dispatch table, and a client compiled against it bakes all three into its own object code.

What the client actually depends on

Consider a client that holds a Document * and calls doc->render(). The code the compiler emits does three things: it reads a pointer from offset zero of the object, loads a function address from a fixed slot in the table, and calls it with the object pointer. Nothing else about Document appears at the call site. But the client also constructed the object, so it embedded sizeof(Document) into its allocation call, and if it derived from Document it embedded the offsets of every base subobject and the contents of the base vtable into its own layout.

Those are three distinct dependencies with different tolerances:

• The slot index of render must not change.
• The table must contain an entry at that index for every class in the hierarchy, including classes the client defines.
• The size and field offsets must not change if the client allocates or subclasses.

A change is binary compatible only if it preserves all three for every client that was compiled against the previous version. The set of such changes is much smaller than the set of changes that compile.

Adding a virtual function

Appending a new virtual function to a base class changes the length of the base vtable. Clients that merely call existing methods are unaffected: their slot indices still hold, and the table they read is the one the object points to, which the new library supplies. Clients that define subclasses of the base are a different matter. In the Itanium ABI a subclass’s vtable begins with the base’s function pointers in the base’s slot order, followed by the subclass’s own new functions; the subclass’s compiler placed its entries at offsets computed from the base layout it saw. A new base virtual function occupies an existing reserved position only if one was reserved for it; otherwise it takes the next slot after the base’s current ones, which is precisely where the subclass’s own new entries sit. The subclass’s entry for its own function is then read through the base’s new slot.

The consequence is that the derived class’s table is now shorter than the base class expects. A call to the new function through a base pointer reads past the derived table’s allocated entries, and a virtual call that the derived class’s compiler thought it was making to an unrelated inherited function lands on a different entry than the one it compiled against. Either way the program jumps to an address that is wrong for the object it has; the failure is memory-unsafe and shows up as a crash or as a call with a nonsensical this.

There is a standard mitigation, and its shape explains the ABI. Reserving slots in advance — declaring a set of private virtual functions as placeholders — keeps the prefix length stable, so later releases can replace placeholders with real functions without shifting anything. The cost is a fixed number of pointer-sized entries per class plus the awkwardness of naming functions nobody calls. The alternative used by some libraries is to avoid adding virtual functions to published base classes entirely and to put new behaviour on a separate interface that clients opt into.

Adding a data member

Adding a non-static data member to a base class changes sizeof and every subsequent field offset. A client that allocates the object with the old size under-allocates, and the library’s constructor writes past the end of the allocation. A client that derives from the class places its own fields at the old end offset, so the library’s new field overlaps the client’s first field. Both failures are silent in the sense that no diagnostic is produced; the corruption appears later.

The mitigations are equally structural. A class can reserve padding — a private byte array sized generously — so later fields consume the reserve instead of growing the object. A class can keep its data behind a pointer to an implementation struct, so the object’s size is one pointer regardless of how the implementation evolves; this is the pimpl idiom, and it trades an indirection and an allocation on construction for complete layout stability. A class can be made abstract with no data members at all, so clients never allocate it directly.

None of these is free. Padding wastes space in every instance, and a library that guesses wrong must either grow again or leave the reserve unused. The pimpl idiom replaces a load at a fixed offset with a load of a pointer followed by a load through it, which adds a dependent memory access on every field read and moves the allocation for the object’s state into construction. Making the base class abstract removes the possibility of stack allocation and value semantics.

The vtable itself is data

Because the vtable is emitted in the library and referenced by the client, anything the client knows about its contents is a dependency. Three cases recur:

The key function rule. In the Itanium ABI, the vtable for a class is emitted in the translation unit that defines the class’s first non-inline, non-pure virtual function. Move that function to another source file and the vtable moves with it, so a client that linked against the old object file may find the symbol undefined, or may link against a stale copy in a static archive. The rule is a convention rather than a language rule, and it is why libraries are careful about which function is declared first.

Inline virtual functions. A virtual function defined inline in the class body is emitted with vague linkage: every translation unit that uses the class may emit its own copy, and the linker coalesces the copies within one linked image. If the library changes the body in the header but a client was compiled earlier, the client’s copy still contains the old body, and a virtual call made from that client can reach the stale copy rather than the library’s current one. The behaviour difference is silent: the program links, runs, and executes the old logic. This is the reason inline functions in published headers are treated as part of the ABI, not as an implementation detail.

RTTI. The type information structure is emitted alongside the vtable and referenced by its mangled name, so code in another shared object that asks for a type’s typeid or dynamic_cast resolves against whichever copy the linker binds it to. A change to the class name, the number of base classes, or the visibility of the type affects that symbol, and a mismatch between the client’s and the library’s idea of a type’s identity makes dynamic_cast fail or, worse, succeed incorrectly across a shared-library boundary where the two copies of the type info are distinct.

Why interfaces and opaque handles escape

An abstract interface with only pure virtual functions has no data members, so its size is a single vptr and adding a virtual function to it appends a slot without changing layout. A client that implements the interface must still be recompiled to provide the new slot; if it is not, its vtable is shorter than the interface now expects, and the same misdispatch reappears one level down. This is why interfaces that cross compilation boundaries are also treated as append-only or versioned. Java and C# avoid the layout half of the problem because objects are allocated by the runtime and field layout is not the client’s business, and they avoid the dispatch half because the method table is built by the loader from metadata rather than emitted by the client’s compiler. The fragility does not vanish; it moves to the metadata, where a class that adds a method changes the resolution of an existing call if the new method happens to be a better match for an argument list. That is the same problem in a different representation.

Opaque handles are the most restrictive arrangement available in a language without a stable ABI: the client sees a pointer to an incomplete type, allocates nothing, computes no offsets, and calls only functions that the library exports. Adding a field or a virtual function inside the implementation affects no client. The price is that the client loses value semantics, stack allocation, and the ability to subclass, and every operation becomes a function call through a pointer. The visibility half of the same boundary is covered in symbol visibility and the one definition rule.

Testing the boundary

Binary compatibility is a property of a pair of builds, so it has to be tested as one. The practical method is to compile a client against version A of the header, link it against version B of the library, and run it. A test that only recompiles everything against B cannot detect the class of failure described here, because recompilation fixes all of it. Libraries that publish ABI guarantees therefore keep an old client binary in their test matrix, alongside a report of the class layouts and vtable contents produced by an ABI checker, so a change that moves a slot is caught before release rather than after.

The reporting tools do the mechanical part: a tool such as abidiff from libabigail, or an equivalent ABI checker maintained by the project, dumps the size, alignment, base offsets, and virtual function order of every exported class for two builds and diffs the results. A diff that adds a field at the end of a class with no subclasses is usually acceptable; a diff that changes a virtual function’s slot or a base offset is not, regardless of how small the source change looks.

The design conclusion

The general lesson is that inheritance across a compilation boundary converts the base class’s representation into part of its interface. A class designed to be subclassed by unknown code must be designed for it from the start: reserved slots, reserved padding or a pimpl, stable inline definitions, and a documented rule about which functions are virtual. A class not designed that way can still be subclassed inside one build, where recompilation is guaranteed, but publishing it as a base class is a commitment to a layout. The commitment is invisible in the header, which is why the failure is discovered by users rather than by the author. The related question of what a linker can still enforce when the layout is not stable is covered in symbol visibility and the one definition rule.