Pimpl for Small Classes

The familiar solution for thick value classes that want to preserve binary compatibility is to use the pimpl pattern (private implementation), also known as d-pointer (pointer to data). In future versions of our class, we can freely change the contents of the pimpl (i.e. adding, removing, and/or modifying data members) but the binary compatibility of the public class gets preserved.

There's a minor variation of the pimpl pattern that can enable some performance improvements by not allocating the private data in all cases. The idea is pretty simple: move (some of) the data members in the public class, while still keeping a d-pointer data member.

This optimization makes a lot of sense, if the class that we're pimpling does not hold a lot of state. In general, there are multiple reasons why one may want to conditionally allocate the private data:

1. maybe we don't need it at all at the moment (again, class with a small state). We want to have room for it "just in case" we need to "grow" our class sometime in the future and want to keep binary compatibility (so we can't just add new data members to it) and/or
2. because the pimpl stores data that it's only seldom needed. In the "common case," we can spare the allocation for that data.

The second scenario isn't really interesting; it's a normal lazy allocation.

Let's, instead, assume we're in scenario number 1, in which the d-pointer is unused right now but there as room for future growth. Let's further assume that we are not also using implicit sharing or any other complications of that nature.

In this scenario, a pimpled class will look something like this:

In the above snippet, I am highlighting which members are exported and out of line and which ones are inline. We must be extra careful with inline functions, as, generally speaking, their code will get compiled into the calling code. The consequence of this is that we can't change their semantics while keeping binary compatibility.

Let's now compare the implementation of the special member functions in the current version of the class ("right now") with the implementation "in the future," when the class will need to make use of the d-pointer because it needs to grow.

There is one very important thing to stress in the above table: "right now" the inline move constructor must move the d-pointer over and reset other.d to nullptr, even if we're not using them at all. In other words, the post-condition of the inline move constructor must be this->d is the old value of other.d and other.d is nullptr. This means that the move constructor cannot be defaulted, even if "right now" defaulting it would do the correct thing.

But why is this? The explaination is a bit tricky, so stay with me.

This postcondition is necessary in order to allow the future version of the class to correctly handle destruction/assignment of moved-from instances while keeping the BC promise.

The point is that a move operation that happens in code compiled against the today version of the class will correctly handle an object produced by the future version of the class (remember, in the future the d-pointer is actually being used). Since the move operation is fully inline, it does not get recompiled when we upgrade to the future version of the class. So we must already prepare todayfor an ownership transfer of the d-pointer!

We're at now, now.

So far, so good.

There's a further optimization possible. In the current design, each instance has to pay for the storage space of a d-pointer even if it's not using it all. Is it OK to have a class that consumes more space (in the example above it could be twice the size of a pointer, due to padding), just for the sake of binary compatibility? What if this is a super-popular class and you may realistically create thousands or millions of such objects? Are you even sure you're going to use the d-pointer "in the future"?

We can trade size for a small refactoring: "in the future," should we decide to pimpl the class, we'll then fold inside the pimpl the contents of the state currently stored directly in the public class itself. This refactoring lets us change the implementation from a record type (store both inline state and d-pointer) to an alternative type (store either inline state or the d-pointer).

In C++, the alternative type is, of course, std::variant<InlineState, Private *>. Here, it would be the easiest choice but not the ideal type to use, as it would waste space for the index of the current active alternative, where we "statically" know which alternative is active: "right now" it's the inline state, "in the future" the pimpl.

So, a union it is, and no extra space required:

Let's do the exercise again. What do we do in each special member function now?

Now we have a problem: we can no longer meaningfully implement an inline move constructor and we cannot implement swap. (And therefore we can't implement move and swap -- that uses both). Why is that?

Remember: the move constructor must carry the d-pointer from the source object (other) onto *this and reset other.d to nullptr, if we want to preserve binary compatibility. (other may come from "the future." The move constructor is inlined "right now").

With this necessary post-condition, the straightforward implementation doesn't work:

This move constructor is reading from other.d "right now", but that union field is not active! That's completely illegal in C++ (file under "UB that works in pratice").

The same problem applies to an inline swap -- which member of the union do we swap? Right now we're supposed to swap s, but that makes it binary incompatible with an object from the future, where d is in use.

A workaround here is possible, but only if the inline state is trivial (so an enum is fine, an int is fine, a struct containing enum+int is fine; but a QString is not fine). The workaround simply consists of making the union not anonymous and moving/swapping the entire union.

The move constructor and swap function then become:

The trick here is that, by moving/swapping the union (as opposed as a union's member), we make C++ responsible for making correct that the active field is the one actually moved. It's no longer our problem!

This is also the reason for imposing triviality for the inline state; otherwise, the union's special member functions are not necessarily generated (whoops!) and we cannot switch the active member of the union (in the move constructor, we enable other.u.d) without first of calling an explicit destructor on the currently active union member; and we don't know which one is enabled.

You'll find this pattern soon deployed in a Qt version near you, for instance, in the new QPermission datatypes. Many thanks to Marc Mutz for implementing the above design in many commits to Qt (e.g. here, here).