Introduction.

You can find Pimpl declaration in Qt documentation, while serfing in Assistent or qt doc site. Also those, Who looked inside in source code of Qt libraries, can found some strange macros: Q_DECLARE_PRIVATE, Q_D, and strange header files with names, ended with “_p.h”. Do you want to know something about this Qt’s Magic ?
In this post I am going to light this magic, and show you that it’s raser simple and useful (And why Qt hide this from us? ).
Also this post may be useful for hacking or reversing Qt source code. This information helps you better understand of structure and relaying of Qt classes.
Русская версия

Pimpl, what is it?

Pimpl – Pointer to implementation. It’s one of the programming patterns. The other name is “opaque pointer”, “handle classes”, “”Compiler firewall idiom”" and my favourite – “Cheshire Cat”. You can find more on Wikipedia.The main Idea of this pattern is to hide all private members and internal implementation from “main” class’s declaration. You can see only smile ,like Cheshire Cat’s smile. The cat is exists, he can speak, but you can see only his smile (Do you remember Alice ? – “Alice’s Adventures in Wonderland” ).
What it get for us?

1. If class hierarchy is wide and deep, then it get us more complex class hierarchy, increasing code reusing and making separate implementation of internal functionality and external class interface.
2. It makes ability to hide platform depended implementation from end-user.
3. One of the most useful features is binary compatibility of library while changing it’s realization.More about binary compatibility and Application Binary Interface (ABI) you can find here (Itanium C++ ABI) and here (an article about calling conversion).And the main rules about making library binary compatibility is described on KDE techbase Binary Compatibility Issues With C++ with the list of rules what you may to do and what not, while making library binary compatibility-enabled.
4. Next plus Is that there are less export symbols (depending on compiler and target platform), this decrease library loading time and emmory footprint.
5. Very useful feature is less time for project building.
6. All private implementation is hided from end-user, as private declaration makes it only unusable.
7. Implicitly sharing mechanism is based on Shared d-pointer pattern, which is the advanced implementation of d-pointers. The benefit of sharing is that a program does not need to duplicate data unnecessarily, which results in lower memory use and less copying of data. (This topic is for separate post )

And what about lacks? Yes! Here they are:

1. Every Constructor/Destructor increase execution time by allocation and releasing memory, in this pattern it’s making twice on each class.
2. Method of public class needs one extra instruction for accessing to private class implementation variable.

There are some situation when using Pimpl pattern adds unnecessary overhead. For example, when a lot of classes’s implementations created and released for storing some kind of simple data. In this case This classes have to be as simple as possible. And changing of interface of this kind of class is means changing of data exchange protocol. In this case It’s better to use plugins to have flexibility. You can find a lot of such examples. The main rule for all patterns is to use it in right place and in right situation.
As for my own opinion, Pimpl is useful only in library implementation or if you plan to move this code in library later.

How did Qt implement Pimpl in Qt library?

Qt uses “d-pointer” way. The main idea in making private class for base class with XXXXPrivate name. The main class has protected variable that point on this class’s instance. This private class declared in separate header or in .cpp file (I’ll explain what better to do). There are exists two class hierarchy – first is public and second is private. The private hierarchy is situated in _p.h (private headers )files. Private headers are used only for building library. They are absent in “include” folder and you aren’t able to use them in common way.

What the main benefits of using d-pointer by Qt’s way.

D-pointers way might to be some difficult to understand for first look. But it is rather simple and evident. Also code become more readable while using D-pointers, because the code is separated for public and private functionality.
Benefits:

1. Simple and evident.
2. Direct access to whole private class hierarchy (Actually the are not private, the are protected ^-))
3. Ability to access to public class from private.
4. Ability to make slots for private class (also if it not QObject) and hide it from public access by using Q_PRIVATE_SLOT(topic for separate discussion).

Yes, I want it. Give me one please!

Now, if you are ready to use this pattern and wanted to know how to make it I’ll show you right way – Qt way !(I really hope so !).
Here are steps for implementing d-pointer powered class or let’s make cheshire cat’s:
1. Forward declare private class for our main class MyClass:

class MyClassPrivate;
class MyClassPrivate: public QObject
{ ..............

2. Next, declare protected pointer variable of private class in first class of hierarchy:

protected:
    MyClassPrivate * const d_ptr;

Pay attention, that d_ptr is constant pointer. Actually we are unable to change this pointer.
3. Declare protected constructor, with firs parameter of reference to private class. This constructor makes ability to send inherited implementation of private class to all base classes as Pimpl object.

protected:
    MyClass(MyClassPrivate &dd, QObject *parent);

4. Declare macros Q_DECLARE_PRIVATE in private section:

Q_DECLARE_PRIVATE(MyClass);

Lat’s look inside this macros:

#define Q_DECLARE_PRIVATE(Class) \
    inline Class##Private* d_func() { return reinterpret_cast(d_ptr); } \
    inline const Class##Private* d_func() const { return reinterpret_cast(d_ptr); } \
    friend class Class##Private;

We can find there declaration and implementation of “d_func()” and “d_func() const” methods. They are using to retrieve private class instance and cast it to class’s Private class’s type. Also declare Private class as friend of our public class.
There are exists similar macros Q_DECLARE_PRIVATE_D. The difference is that _D macros accept’s two parameters. First is class name too, and the second is name of d-pointer variable. It’s make ability to use some another name for d-pointer instead of “d_ptr”. But name of function d_func() is same. Here is implementation of Q_DECLARE_PRIVATE_D macros:

#define Q_DECLARE_PRIVATE_D(Dptr, Class) \
    inline Class##Private* d_func() { return reinterpret_cast(Dptr); } \
    inline const Class##Private* d_func() const { return reinterpret_cast(Dptr); } \
    friend class Class##Private;

5. Then you need to declare Private class in _p.h or .cpp file. If you plan to inherit this class then you need _p.h file, in other case declare private class inside of .cpp file. Pay attention, that header file have to be declared before private header in project file. And I’ts better to have right ordered headers in project files. Headers that include other headers have to be declared after headers they are include. It’s important when you are include moc file right in your .cpp file when using Q_PRIVATE_SLOT macro (a’ll discuss it in other post, just keep this rule).

class MyClassPrivate
{
    MyClassPrivate();
    virtual ~MyClassPrivate();

    int i;
}

Also you need to make destructor virtual. Why? It’s subject for separate post. But believe me it’s important. Please use C++ documentation to make it clear for you. You can find this topic in Bjarne Stroustrup’s book.
7. Realization of protected constructor is:

MyClass::MyClass(MyClassPrivate &dd, QObject* parent)
              :QObject(parent)
              ,d_ptr(&dd)
{ .....

And the public constructor’s realization (Pay attention on “explicit” keyword, please make it’s clear for you, you have to understand what is it ):

MyClass::MyClass(QObject * parent)
         :QObject(parent)
         ,d_ptr(new MyClassPrivate())
{........

Derived Class’s realization of such constructor is:

MyClassDerived::MyClassDerived(QObject * parent)
         :MyClass(*new MyClassDerivedPrivate(),parent)
{........

As you can see Derived class creates private class instance and send it to base class as it’s private class’s instance.Private class of derived class is derived from private class of base class. And it’s sends to whole hierarchy.
8. To access to private classes’s instance from public class you can use Q_D macros.

#define Q_D(Class) Class##Private * const d = d_func()

As you can see, this macros get pointer to private class and cast it to our Private class type. As result we got variable d that points to our Private class instance (here you are: D-pointer !!! ).

int MyClass::foo() const
{
    Q_D(const MyClass);
    return d->i;
}

Pay attention that you have to declare add “const” to class name when you use it from const method. We got const d-pointer to const private class (if it’s not clear about “consts”, you have to make it clear for your about “const”, it’s very important).
9. Let’s go deeper. Let me introduce new character Q-pointer. Q-pointer is similar to d-pointer, only difference that it points to public(main) class from private class. You can use it from private class’es methods to access to public class (to emit signal, for example).
To implement it you have to declare pointer variable to public class’s instance in your first class of private hierarchy.

class MyClassPrivate
{
public:
    MyClassPrivate();
    virtual ~MyClassPrivate();

    int i;
    MyClass *q_ptr;
}

And declare macros Q_DECLARE_PUBLIC in all private classes, where you going to use q-pointer.

class MyClassPrivate
{
    Q_DECLARE_PUBLIC(MyClass);
public:
    MyClassPrivate();
    virtual ~MyClassPrivate();

    int i;
    MyClass *q_ptr;
}

Here are Q_DECLARE_PUBLIC macro:

#define Q_DECLARE_PUBLIC(Class)                                    \
    inline Class* q_func() { return static_cast(q_ptr); } \
    inline const Class* q_func() const { return static_cast(q_ptr); } \
    friend class Class;

As you can see it’s similar to Q_DECLARE_PRIVATE. but instead of d_ptr there is q_ptr and instead of d_func() is q_func(). And also there are no analog of Q_DECLARE_PRIVATE_D for Q_DECLARE_PUBLIC.
Warning: don’t forget to initialize q_ptr variable in all constructors of base class of your first class of hierarchy:

MyClass::MyClass(QObject * parent)
         :QObject(parent)
         ,d_ptr(new MyClassPrivate())
{
    Q_D(MyClass);
    d->q_ptr = this;
.......
}

10. To access to public class from private one use macros Q_Q.

#define Q_Q(Class) Class * const q = q_func()

Behavior and rules are the same as for d-pointer (don’t forget add “const” when use it from const method).

void MyClassPrivate::foo()
{
    Q_Q(MyClass);
    q->foo();
    emit(q->signal(i));
}

Conclusion.

Keep in mind that all macros are part of non-public Qt API, and might change in any time. But I can console you. These macros are basement of all Qt libs, and in worst way they can change only in Qt5. In any case you have to port application from Qt4 to Qt5. Another consolation is KDE use’s this macros in own source code. But if you paranoiac, you can rename this macros and fit it in your source code.
Also keep in mind that the class My class is derived from QObject. And QObject has it’s own private class hierarchy. QObjectData is most base class in it.It keeps pointer to parent, object state and other base properties. But Qt’s private class hierarchy is isolated from mine, because I close QObject’s d_ptr variable by mine. And when my classes use d_ptr, they use my private classes, but QObject still use it’s own private class.
Why not use Qt’s private hierarchy and make our MyClassPrivate derived from QObjectPrivate class. It is possible but it is bad decision. First of all We lose Qt lib’s binary compatibility and have to recompile our lib for every change of Qt’s private implementation, in this case. The second reason why to not to do so is private headers of Qt classes are unavailable by common way, we need Qt sources to compile our library. And what you’ll get doing it ? It’s unnecessary at all(Maybe I’m wrong, please let me know if it’s true).

Later I’ll tell you about some other interesting things:
What is QFlag and why to use it.
Qt’s code style.
How to implement implicit sharing in your classes and how it works.
Qt’s useful macros.
Qt Creator inside and outside (tips and tricks).
How to create application and easy port it to 7 platforms, using Qt.
And more interesting things.

Don’t lose it, subscribe to RSS on top of this page.
PS: Excuse me for my English, I’ll be glad to receive corrections and remarks about my publications. English is not my native language, be patient, because it’s rather difficult to write on English for me.

Source code examples.

I wrote a lot of text, to help you understand better there are code examples:
this post
I’m unable to put it in this post because WordPress doesn’t show it

Unique visitors to post: 252