skip to content

Your header-only C++ serialization templates dominate build time across 2,000 files: when do you switch to explicit instantiation with extern template, and what does it cost?

level: principalimportance: should knowfreq 30%

answer

  1. measure where the time goes first
  2. closed versus open set of types
  3. declaration in header, definition in one .cpp
  4. inline members still get instantiated

basics

~20 s

Switch when profiling shows a few heavy specializations instantiated in many files and the type set is closed. extern template in the header plus one explicit instantiation removes duplicate code generation; parsing and inline members still cost every includer.

solid answer

~40 s

First measure: clang's `-ftime-trace` or GCC's `-ftime-report` shows whether time goes to parsing headers, to instantiating templates, or to optimizing the generated code. If a few specializations — `Serializer<Record>`, `Serializer<Event>` — are instantiated in hundreds of files, declare them `extern template class Serializer<Record>;` in the header and define them once with `template class Serializer<Record>;` in a `.cpp`. Other files then stop generating out-of-line member code and reference the single copy. The costs: the header is still parsed everywhere; in-class members are inline, so they are still instantiated where used; a new type still instantiates implicitly; and a forgotten instantiation definition is ill-formed with no diagnostic required, usually surfacing as a link error. For an open set of client types, stay header-only and cut parse cost instead.

code

cpp · 22 lines
cpp
#include <cstdio>
#include <string>

struct Record { int id; double score; };

template <class T> class Serializer {        // normally in serializer.h
public:
    std::string encode(const T& v) const;                 // defined out of class
    std::size_t width() const { return sizeof(T); }       // in class: implicitly inline
};
template <class T>
std::string Serializer<T>::encode(const T& v) const {
    return std::string(reinterpret_cast<const char*>(&v), sizeof v);
}
extern template class Serializer<Record>;    // header: includers do not generate members

int main() {
    Serializer<Record> s;
    std::printf("%zu %zu\n", s.encode({1, 2.0}).size(), s.width());
}

template class Serializer<Record>;           // normally alone in serializer_inst.cpp

go deeper

for a junior

Know that template code in headers is compiled again in every file that uses it, and that C++ offers explicit instantiation to generate a specialization once.

for a middle

Explain extern template as a declaration that suppresses instantiation and template class as the one definition, and what nm shows in each object file.

for a senior

Describe what is not saved: parsing, inline members still instantiated for inlining, new types instantiating implicitly, and the no-diagnostic failure when the definition is missing.

for a principal

Own the trade-off: profile first, choose header-only for open type sets and explicit instantiation for a closed, heavy set, and budget for the instantiation list, lost cross-file inlining and CI that links every target.

## The problem in numbers A header-only serialization library defines `template <class T> class Serializer` with all members in `serializer.h`. Every one of 2,000 translation units that includes it pays three costs: 1. **Parsing** the header and everything it includes. 2. **Instantiating** each specialization it uses, such as `Serializer<Record>`, producing an in-memory definition for every used member. 3. **Generating and optimizing code** for those members — repeated in every object file, after which the linker discards all but one copy. If 900 files use `Serializer<Record>`, its code is generated 900 times. Explicit instantiation targets the second and third costs; nothing on this leaf removes the first. ## The mechanism ```cpp // serializer.h template <class T> class Serializer { /* members */ }; extern template class Serializer<Record>; // explicit instantiation declaration // serializer_inst.cpp #include "serializer.h" template class Serializer<Record>; // explicit instantiation definition ``` - The **explicit instantiation declaration** (`extern template`) tells every includer that the specialization's members are instantiated elsewhere, so the compiler emits references to them instead of generating them. - The **explicit instantiation definition** generates the class and every member defined at that point, once, in `serializer_inst.o`. Measured with Apple clang 21: with the `extern template` line, `nm` shows the user's object file holding only undefined references (`U Serializer<Record>::encode(Record const&) const`), while `serializer_inst.o` holds the definitions (`T`). Linking without the instantiation file fails with undefined symbols. ## What it does not save - **Inline members.** A member defined inside the class body is implicitly inline. The standard's note says such a function is still implicitly instantiated when used, so the body can be considered for inlining, while the out-of-line copy is not generated. Clang at `-O2` inlined the in-class `width()` and referenced only `encode`; at `-O0` it referenced both. Either way the front-end work for inline members remains. - **Parsing.** Every includer still reads the full template definition. Headers that pull in large dependencies stay expensive; that is the job of a compile firewall, precompiled headers or modules, covered elsewhere. - **Open-ended types.** `extern template` covers the specializations you list. A team that serializes a new `Telemetry` type instantiates it implicitly in every file again until someone adds it to the list. ## The decision | Factor | Favors header-only | Favors explicit instantiation | |---|---|---| | Set of argument types | Open, chosen by clients | Closed, known to the library | | Who instantiates | External users of a published library | Teams inside one codebase | | Profile shows | Parsing dominates | Instantiation and codegen of a few specializations dominate | | Optimization needs | Hot code must inline everywhere | Out-of-line calls are acceptable | | Maintenance appetite | No list to keep | Someone owns the instantiation list | A middle ground keeps the template header-only for flexibility and adds `extern template` only for the handful of heavy specializations the profile names. A stricter option, viable only for a closed set, moves member bodies into a `.inl` included solely by the instantiation file, so includers see declarations alone; then the header parses faster too, but no new type works without editing the library. ## Costs a lead must accept - **Silent failure mode.** Using a specialization declared `extern template` without a matching definition anywhere is ill-formed, no diagnostic required. In practice it shows up as a link error, but only for configurations that build the affected file. - **Lost inlining across the boundary** for members defined out of class, unless link-time optimization is on. - **A list to maintain**, and a convention for where new specializations are registered. - **Measurement before and after.** Use clang's `-ftime-trace` or GCC's `-ftime-report` on the slowest files; if parsing dominates, explicit instantiation buys little and the effort belongs elsewhere. ## A reasonable policy - Profile first and fix the top specializations, not all of them. - Keep one instantiation `.cpp` per library with the `extern template` declarations next to the template. - Add a CI build that links every target, so a missing definition fails before review. - Revisit when the codebase moves to modules, which change the parsing cost but not the need to decide where instantiations live. - Record the decision next to the template, so the next engineer who adds a record type knows whether to touch the instantiation list.

  • What happens if serializer.h declares extern template class Serializer<Record>; but no file defines the instantiation?
    Any file that uses `Serializer<Record>` in a way that would instantiate it is relying on a definition elsewhere; without one the program is ill-formed, no diagnostic required. In practice the linker reports undefined symbols for the members, as clang does for `encode` and, at `-O0`, `width`. Linking every target in CI catches it before release.
  • Why might switching to explicit instantiation make a hot serialization path slower?
    Members defined out of class are now compiled once in the instantiation file, so callers see only a declaration and make an ordinary call instead of inlining the body. In-class members can still be inlined. Link-time optimization restores cross-file inlining at extra link cost, or the hot members can be moved into the class body.

  • extern template stops the compiler from parsing the template's definition.
  • extern template removes inline members from every includer's work.
  • Explicit instantiation lets clients use any new type without touching the library.
  • A missing explicit instantiation definition is always a clear compile error.
  • Header-only templates produce duplicate-symbol link errors at scale.