Skip to content
Tutorials Center
My learning

Topics

Lesson 85 of 171 ยท Object-Oriented Programming

PIMPL and API/ABI Stability

Learn the PIMPL idiom in C++ to hide private members, cut compile times and keep a library's binary interface stable. Covers unique_ptr pimpl, copying, ABI rules and C handles.

A C++ class has a problem that most other languages avoid: its private members are visible in the header. Anyone who includes widget.h sees every private field and helper, and, worse, depends on them. Add one int to a class, and every source file that includes the header must be recompiled. If the class is part of a library you ship as a compiled .so or .dll, programs built against the old header can crash when they run against the new library, because they disagree about the object's size and layout.

The PIMPL idiom ("pointer to implementation", also called the compiler firewall or opaque pointer) fixes both. The header declares the public interface and holds a single pointer to a hidden Impl class. All private data and helpers move into the .cpp file. In this lesson you will build a pimpl class with std::unique_ptr, make it copyable and movable, measure the effect on sizeof, learn the difference between API and ABI stability, and see the C-style handle pattern that libraries use for the strongest guarantee. It builds on Header Files and Multiple Source Files, Classes and Objects and unique_ptr.

API versus ABI

Two kinds of compatibility are easy to mix up:

  • API (application programming interface) is the source-level contract: function names, parameter types, class members that your code can name. An API change breaks compilation.
  • ABI (application binary interface) is the machine-level contract: object sizes and layouts, which member is at which offset, how names are mangled, how arguments are passed, the virtual table layout. An ABI change breaks already compiled programs, even when no source line needs changing.

All of these are ABI-breaking for a class that a compiled library exposes by value in its header:

  • Adding, removing or reordering a non-static data member (changes sizeof and offsets).
  • Adding or reordering virtual functions (changes the vtable).
  • Changing a base class list.
  • Making an inline function do something different. The old program contains a copy of the old body.
  • Changing a function's parameter types or const-ness (the mangled name changes).
  • Switching the compiler or standard library in ways that change std::string, as happened with the C++11 std::string change in libstdc++.

Header-only libraries and applications that rebuild everything together do not care about ABI. Shared libraries, plugin systems and operating-system APIs care a great deal.

flowchart LR
    subgraph app["Program (already compiled)"]
        A["Widget w;<br/>reserves 16 bytes"]
    end
    subgraph lib["libwidget v2"]
        B["Widget now needs<br/>24 bytes"]
    end
    A -- "calls into" --> B
    B -. "writes past the end" .-> A

An ABI break: the program still allocates the old size, and the new library writes beyond it.

The idiom in one file

A real project puts the interface in a header and the implementation in a source file. The online editor has a single file, so the next example marks the boundary with comments. Read it as two files:

C++ A pimpl class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Look at the three parts. The header exposes only struct Impl;, a forward declaration of an incomplete type, and a std::unique_ptr<Impl>. Users of Account never see std::vector or std::string members, so the header does not even need to include them for the private part. In account.cpp, Impl is a complete type with all the data.

The special member functions must be defined in the source file

std::unique_ptr<Impl> needs to know how to delete an Impl, and that requires the complete type. If you rely on the compiler-generated destructor in the header, it is generated where Impl is still incomplete, and you get an error such as "invalid application of sizeof to incomplete type". The fix, as shown, is to declare the destructor, move operations and copy operations in the header and define them in the .cpp (= default is fine there). This follows the same logic as the Rule of Zero, Three and Five.

The copy constructor performs a deep copy of Impl, so b and a do not share state. If you do not want copies, declare them = delete in the header and skip their definitions. Move operations are noexcept, which lets containers move objects instead of copying them (see Move Semantics).

What pimpl buys you

  1. Compile-time firewall. Changing private members or helper functions recompiles one .cpp file, not every file that includes the header. On large projects this saves minutes per build.
  2. Fewer includes in the header. The header does not need <vector>, a database library or a platform API. Users compile faster and do not inherit your dependencies.
  3. Information hiding. Private data does not leak into the public header.
  4. Binary compatibility. sizeof(Account) is the size of one pointer forever, so adding fields to Impl does not change the layout users compiled against.
  5. Stable exception safety. Swapping the pointer gives a cheap, non-throwing swap (see Exception Safety).

What it costs

  • One heap allocation per object, and one extra pointer hop on each call. This matters for tiny objects in hot loops; it does not matter for a database connection or a window.
  • Boilerplate: every public function forwards to impl_->....
  • const is shallow. A const member function can still modify the Impl, because const applies to the pointer, not the pointee. Take care, or wrap the pointer in a class that propagates const (the std::experimental::propagate_const wrapper does).
  • Not for templates or inline-critical code. Templates need their bodies in headers, and tiny getters you want inlined become real calls.

Measuring the layout

You can see the ABI effect directly with sizeof. The same logical class, version 1 and version 2 with an extra field, written two ways:

C++ How sizeof reveals ABI breaks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

The direct version grows from 16 to 24 bytes. A program compiled against v1 reserves 16 bytes for each Sensor; calling into a library built with v2 would touch memory beyond that. The pimpl version stays at 8 bytes on a 64-bit machine, however many fields Impl gets. For more on why structs have the sizes they do, see Memory Layout.

Other rules for a stable ABI

Pimpl handles data members. A library author should also:

  • Avoid exposing standard-library types in a public ABI, especially across compilers or standard-library versions. std::string and std::vector have changed layout or mangled names over the years. Pass const char* plus length, or std::string_view (a pointer and a length, which has been stable), across the boundary.
  • Do not add or reorder virtual functions in a published class. Add new ones at the end of the most-derived class, or introduce a new interface (see Abstract Classes).
  • Mark exports explicitly (__attribute__((visibility("default"))) or __declspec(dllexport)), so only your API appears in the binary's symbol table.
  • Do not throw exceptions across a C boundary or a plugin boundary where compilers or runtimes differ.
  • Use inline namespace versioning (namespace mylib::v2) when you must change something incompatibly, so old and new symbols have different names.
  • Keep inline functions boring. An inline body is copied into each caller; changing it later does not update programs already built.

The ultimate stable boundary: a C handle

If a library must work with many compilers and languages, expose a C interface. The header declares an opaque struct that callers only hold by pointer, plus plain functions:

C++
/* counter.h */
#ifdef __cplusplus
extern "C" {
#endif

typedef struct Counter Counter;          /* opaque: definition is private */

Counter* counter_create(int start);
void     counter_add(Counter* c, int amount);
int      counter_value(const Counter* c);
void     counter_destroy(Counter* c);

#ifdef __cplusplus
}
#endif

This is pimpl in its purest form, and it is how many real libraries (including most operating-system APIs) hide their internals. extern "C" turns off C++ name mangling, so any language can link to it. Inside the .cpp you can freely use C++:

C++ An opaque C handle over a C++ implementation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

The price of this style is that the caller must remember to call counter_destroy. A C++ wrapper class (a RAII type holding a std::unique_ptr<Counter, decltype(&counter_destroy)>) removes that risk for C++ callers.

When to use pimpl

Use it for classes in library public headers, for classes that wrap a platform or third-party API you do not want to leak (a socket, a window, a database handle), and for big classes that change often in large projects. Do not use it for small value types such as a Point or Money, for performance-critical objects created by the million, or for classes in a code base where everything is always rebuilt together. Sometimes a plain abstract interface with a factory function gives the same hiding with less code, and also allows several implementations (Design Patterns).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A program compiled against v1 of a shared library crashes after you install v2, though no source line needs to change. What kind of compatibility broke?

    The binary contract (for example the size or layout of a class) changed. Source compatibility is not enough for already compiled programs.
  2. 2. Why must the destructor of a class holding std::unique_ptr<Impl> be defined in the .cpp file?

    With only a forward declaration, Impl is incomplete in the header. Deleting through unique_ptr needs the full type, so define (or default) the destructor where Impl is complete.
  3. 3. Which change to a published class with only a pimpl pointer in the header is safe for binary compatibility?

    The visible object stays one pointer. Impl is private to the library, so adding fields to it changes nothing callers compiled.
  4. 4. What is a real drawback of the pimpl idiom?

    The implementation lives on the heap behind a pointer. That is cheap for most classes, but significant for tiny objects created in hot loops.
  5. 5. Inside a const member function of a pimpl class, can you modify data through impl_->?

    A const member makes impl_ itself const, which is a unique_ptr<Impl> const. The pointee stays non-const, so you must be careful or use a propagate_const wrapper.

Summary

  • API stability keeps source code compiling; ABI stability keeps already compiled programs working. Changing a class's data members, virtual functions or bases breaks the ABI.
  • PIMPL hides private members behind a pointer to a forward-declared Impl defined in the .cpp. The header then has fewer includes, builds faster and keeps sizeof constant.
  • With std::unique_ptr<Impl>, declare the destructor and the copy and move operations in the header and define them in the source file.
  • Pimpl costs a heap allocation, an indirection and some forwarding code, and const is shallow.
  • For the strongest boundary, expose a C API with extern "C" and an opaque struct handle, and wrap it in RAII for C++ callers.
  • Avoid exposing standard-library types, inline function bodies and virtual layout changes in a binary interface you must keep stable.

Next: Function Templates, where the compiler writes functions for you.