The C++ Pimpl
by Sobeit Void
06-01-2001

Introduction

Despite the similarity, the C++ Pimpl has nothing to do with sex. The C++ Pimpl is a short form for "Private Implementation" idiom, and its usage is popularized in Herb Sutter's Guru of the Week (www.gotw.ca) column. (Note: The L behind is used to protect the underage)

The Pimpl idiom describes a way for making your header files impervious to change. You often hear advices like "Avoid change your public interface!" So you can modify your private interface, but how can you avoid recompilation when your header file defines the private methods. This is what the Pimpl does – Reduce compilation damages when your private interface changes.

Just like real life, we often judge a Pimpl by what it has to offer, so let's see what it does.

Pimpl in Action

Let's get straight to business. Here is the Pimpl.

Note: I avoid unnecessary things like header inclusion guards for simplicity.

// In MyClass.h

class MyClassImp;                    // forward declaration of Pimpl
 
class MyClass
{
public:
   MyClass ();
   ~MyClass();
 
   MyClass( const MyClass &rhs );   // undefined for simplicity
   MyClass& operator=( MyClass );
 
   void  Public_Method();
 
private:
   MyClassImp *pimpl_;              // the Pimpl
};

Our header defines a forward declaration of the Pimpl and other public interface. It stores a private Pimpl_ member pointer and that is all the client will ever see. There will never be any change unless you change the public interface, which you already know you shouldn't.

The definition file goes as follows

// In MyClass.cpp

#include "MyClass.h"
 
class MyClassImp
{
public:
   void   Private_Method()  {}     // dummy private function
 
   int    private_var_;            // a private variable
};
 
MyClass::MyClass()  :  pimpl_( new MyClassImp() )
{
}
 
MyClass::~MyClass()
{
   delete  pimpl_;
}
 
void   MyClass::Public_Method()
{
   pimpl_->Private_Method();      // do some private work
 
   pimpl_->private_var_  = 3;
}

We define the private implementation class in the class definition file. We access private methods through the member pimpl_ pointer.

We can add, remove, and change the implementation class anyway we like. The client is totally insulated through the forward declaration and pointer declaration of Pimpl;

Being a PRO

If you want to be more of a PRO (professional, that is), here are tips.

1. Private methods calling public methods
Often your private methods need to call public methods. If that is the case, the private implementation class can store a reference to the main class and use the reference to access the main class. Watch out for methods calling each other though, it will lead to infinite recursion.

2. Using a smart container instead of a raw Pimpl pointer.
In the example, I disallowed copying and assignment in the class. Should you want to allow it, you can use a smart pointer class (The STL auto_ptr doesn't cut it) to hold the Pimpl instead. This saves you from having the common shallow/deep copies pointer problems.

3. Defining the private implementation class as a local class instead.
The Pimpl idiom pollutes the namespace with another class. If you want to avoid that, you can implement the private implementation class as a local class instead. However, do note that local classes have many restrictions.

If you need it, get it

At the end of the day, the question you always need to ask is, "Was it worth it?"

The class has to store an additional pointer member. Calling methods require an additional pointer deference call. For small classes (like matrices classes) which are used often, the speed and memory increase may be unacceptable. For other types of classes, the impact is negligible.

Use it appropriately and it should satisfy just right. Remember,

Always practice safe coding. Use an assert.

Discuss this article in the forums

Date this article was posted to GameDev.net: 4/2/2002
(Note that this date does not necessarily correspond to the date the article was written)

See Also:
Code Design
Sweet Snippets