Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Types and Language Concepts

The pimpl idiom

Concept page on the C++ pimpl idiom: hide private members behind a std::unique_ptr, keep headers stable, reduce build times, and handle special members.

The pimpl idiom ("pointer to implementation", also called the compiler firewall or opaque pointer) moves a class's private data and helper functions into a separate struct that is only declared in the header. The public class holds one pointer to that struct. Users of the header see just the public interface and a pointer; the definition of the implementation lives in a single .cpp file.

The benefits are practical. Changing private members does not force every includer to recompile. Heavy headers (operating system APIs, third-party libraries) stay out of your public header. The class layout is only one pointer, so you can keep the binary interface (ABI) stable across library versions. The costs are an extra heap allocation, one level of indirection, and boilerplate for the special member functions.

C++
class Widget {
public:
    Widget();
    ~Widget();                 // must be defined where Impl is complete
    void draw();
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

Try it

Our runner compiles one file, so the header and source parts appear together; the comments mark where each would live.

C++ A pimpl class in one file

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.

C++ Value semantics: adding a deep copy

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.

Rules for getting it right

  • Declare the special members in the header, define them in the .cpp. std::unique_ptr<Impl> needs Impl to be complete when its destructor is instantiated. If you rely on the implicitly generated destructor, the compiler tries to destroy an incomplete type and reports an error such as "invalid application of sizeof to incomplete type". Writing ~Widget() = default; in the .cpp fixes it.
  • Moves: the defaulted move operations (also defined in the .cpp) just transfer the pointer. A moved-from object has a null impl_; calling its methods dereferences null, so document that it may only be destroyed or assigned.
  • Copies: std::unique_ptr is not copyable, so the class is move-only unless you write a deep copy (as the second example does). std::shared_ptr<const Impl> gives cheap copying with shared immutable state.
  • Constructors that need Impl also go in the .cpp; use std::make_unique<Impl>() there.
  • const correctness does not propagate: a const method can still modify *impl_, because constness applies to the pointer, not the pointee. Mark the method const only if it behaves so, or wrap the pointer in std::experimental::propagate_const (a library fundamentals extension, not available everywhere).
  • Cost: one allocation per object and one extra indirection per call; avoid it on small hot types. Inlining across the boundary is lost unless you use link-time optimization.
  • Alternatives: an abstract base class with a factory function (virtual interface) also hides the implementation; modules and export hide names but not layout. Pimpl is best for stable library APIs and for isolating heavy dependencies.