PSA: QPointer has a terrible name

12.10.2023 Giuseppe D'Angelo No comments

Today’s blog post is about a small utility class in Qt with a… questionable name: QPointer. If you’re new to Qt, maybe don’t check out QPointer’s documentation just yet, and try to guess what the class does based on its name alone.

I’ve seen countless users being very confused by it. Some end up using it extensively, thinking that it’s the Qt way to store pointers, or a better kind of pointer, or maybe yet another Not Invented Here Qt class solving a non-problem, or something along those lines.

So what is QPointer?

QPointer is a weak pointer for QObjects. What’s a weak pointer, you ask? A weak pointer is a smart pointer that does not participate in the ownership of a given object. Destroying the weak pointer has no effect whatsoever on the pointed-to object. Instead, a weak pointer acts as an observer, and is able to tell us whether the object has been already destroyed (by its owner(s)) or not.

QWidget *w = new QWidget(parent); // create a new object; `parent` owns it

QPointer<QWidget> ptr = obj;      // create a weak pointer, watching over *w
Q_ASSERT(ptr);                    // ptr is valid, *w still exist 

destroyWidget();                  // destroy *w somehow
Q_ASSERT(!ptr);                   // ptr is automatically reset,
                                  //   to signal that *w is gone

In the snippet above it doesn’t matter how exactly we destroy our object (an explicit delete, or through the parent object, etc.).

The interesting part is the last line: ptr knows that the object is destroyed, and automatically resets itself to a null pointer. Compare this with a “raw” C++ pointer, which does not get automatically reset, and would dangle instead.

Therefore, if we compose this a little bit further:

class MyClass {
  QPointer<SomeObject> m_resource;  // pointer to some resource we don't own

  void doSomething() {
    if (m_resource)        // check that the resource is still alive;
      m_resource->use();   // if so, use it
  }
};

This is pretty interesting, because our code now is much safer (and simpler), compared to using raw pointers, or connecting to the QObject::destroyed() signal or some other mechanism.

Here’s a very fancy scenario:

class MyObject : public QObject {
  Q_OBJECT

signals:
  void aSignal(int value);

public:
  void doSomething() {
    int value = calculateValue();

    QPointer<MyObject> guard(this);
    emit aSignal(value);
    if (!guard)
       return;

    // do some other things
  }
};

Here we’re guarding against the fact then, when we emit a signal, slots connected to the signal may end up destroying the sender object. This usually doesn’t have the form of delete sender, but it’s more indirect. For instance, the sender may be a button, connected to a slot that re-arranges the UI of your application, and while doing so, it may end up destroying the button itself.

While deleting a sender object is supported by the signal/slot mechanism, it’s important to realize that once all the slots connected to a signal have been called, the execution will continue in the code that emitted the signal. In there, the sender object (i.e. *this) is now destroyed. In the above snippet the guard lets the execution stop right after we return from the signal emission, in case we detect that *this has indeed been destroyed.

This pattern is used all over the place in widgets code (a place where the chances of deleting a sender are pretty high).

Please note: I’m not saying that you should protect all your signal emissions like the above. Deleting a sender object directly (via operator delete) is, generally speaking, a poor idea; one should use deleteLater() instead. Ideally here I’d like some debug mechanism from Qt telling us that we are indeed deleting an object in the middle of a signal emission, but I fear that the signal-to-noise ratio is going to be pretty close to 0.

QPointer is a weak pointer, std::weak_ptr is a weak pointer, are they different?

The principle behind QPointer and std::weak_ptr (or Qt’s reimplementation, QWeakPointer) is pretty much the same: both are smart pointers classes pointing to object that are not owned through that smart pointer. There’s however some important differences.

1. QPointer only works with QObject subclasses; std::weak_ptr works with any type.

This isn’t an “arbitrary” limitation put in place by QPointer; it has strictly to do with how these weak pointer classes detect that the resource they’re observing has been destroyed.

std::weak_ptr achieves this because it observes the control block that another smart pointer class set up for it: std::shared_ptr. That’s right, std::weak_ptr and std::shared_ptr go hand-in-hand; you must manage a given resource with std::shared_ptr in order to use std::weak_ptr with it. This is because std::weak_ptr observes the strong counter in the control block in order to know if the resource is still alive. This is a (very simplified!) example of how std::shared_ptr and std::weak_ptr work together:

On the other hand, a QObject observed by QPointer doesn’t have to be managed in any specific way. It can be owned using a raw pointer, or by an owning smart pointer class, or through QObject’s parent/child mechanism, or it can be a data member of another class… It doesn’t matter: QPointer simply doesn’t impose a particular owning strategy.

So how does QPointer know when the object it points to has been destroyed? QPointer needs some help from that object. Specifically, that object is going to set up a control block so that QPointer can then use it. This is what happens inside QObject guts (see the sharedRefcount member of QObjectPrivate and its usages).

And this is why QPointer requires the pointed-to type to be a QObject (subclass): it needs some special logic that only QObject implements.

By the way, if you’re curious: the mechanism used behind the scenes by QObject and QPointer is actually exactly the very same one that in Qt is used by QSharedPointer and QWeakPointer: a control block with two counters, the strong counter and a weak counter. The strong counter signals whether the QObject has already been destroyed (it’s not really used as a “counter” in this scenario; it’s actually set to -1, and reset to 0 when the object is destroyed); the weak counter counts how many QPointer objects are tracking a given QObject. Here’s how it looks like:

Again, this is a simplification. I’m deliberately omitting some details such as the fact that the control block also stores the deleter, a pointer back to the object, and especially whether the weak counter only tracks weak pointers or the sum of strong pointers and weak pointers.

From this point of view, QPointer acts as an intrusive pointer, expecting the pointed-to object to obey a certain protocol. This is vaguely similar to the (in)famous std::enable_shared_from_this class template, that allows one to create shared pointers (and weak pointers, as of C++17) out of an arbitrary object, because the object itself keeps a pointer to the control block used to manage it. (It does so by inheriting from std::enable_shared_from_this). However, std::enable_shared_from_this on an object which is not already managed by a shared pointer will not magically start the refcounting process, while instead QPointer does so.

And while at it, here’s another little nugget: the fact that this specific implementation was used by QPointer is also why QWeakPointer supported direct construction from QObjects back in Qt 5, even if they were not managed by a QSharedPointer. This has made a lot of people very angry and been widely regarded as a bad move.

2. QPointer doesn’t use a lock()ing protocol

If you have a weak pointer, how do you use it? The whole purpose of such a smart pointer class is to let you test if the pointed-to object is still alive, and only if it is, use it.

Therefore, one can try a strategy like this one:

WeakPointer<Foo> weakPtr; // declared somewhere

// Here's how one would use it:
if (weakPtr)               // is the object still alive?
  weakPtr->doSomething();  // use it!

This specific snippet looks OK, but actually it doesn’t even compile with std::weak_ptr. The reason is that code written like this could exhibit a TOCTOU bug: even if the check passes, by the time we try to use the object, the object could’ve been destroyed.

How in the world could the object disappear between the if and the usage? But because of multiple threads, of course! std::shared_ptr and std::weak_ptr’s reference counting mechanism is thread safe. (The reference counting is; the objects themselves are merely re-entrant.) So while you execute the above snippet in thread 1, thread 2 could be destroying the last shared pointer owning the object, therefore destroying the object. If thread 2 happens to do this right between the check of the weak pointer by thread 1 and its subsequent access, your program is in trouble.

This is why, when dealing with std::weak_ptr, we ask “is the object still alive?”; but we word the question slightly differently. We ask “can I become a co-owner of the object, if it’s still alive?”

Becoming a co-owner means getting a std::share_ptr pointing to the object; therefore we are going to call a function that will return one. We somehow ask to “upgrade” our status: from mere observer (std::weak_ptr) to co-owner (std::shared_ptr). The returned std::shared_ptr object will be loaded in case the object is still alive, or empty in case the object has already been destroyed. Now, for a number of reasons, this “upgrade request” has a very weird name: it’s called std::weak_ptr::lock() (docs). In my humble opinion, this just gets C++ newcomers very confused, as they immediately think about mutex locking or some other multithreading primitives that have no role in what’s happening here.

Now, being a co-owner is a pretty good thing for us, because it means that we can safely check if the object is still alive (by checking the returned shared pointer). If the object is alive, we can safely access it: no other threads can now lose the last owning pointer to our object and destroy it under our nose. There’s always at least one owner: yourself, through the std::shared_ptr you’ve just obtained. Hence, the code above has to spelled like this when using std::weak_ptr:

std::weak_ptr<Foo> weakPtr; // declared somewhere

// Test and use:
std::shared_ptr<Foo> sharedPtr = weakPtr.lock();
if (sharedPtr)               // sharedPtr, not weakPtr!
  sharedPtr->doSomething();  // object is alive, use it

What about QPointer? Well, QPointer lets you get away with it:

QPointer<MyQObject> ptr;

if (ptr)               // is the object still alive?
  ptr->doSomething();  // use it!

Doesn’t this code suffer from the problem that weak_ptr works so hard to prevent? Well yes, it does. However, in practice it does not constitute a problem, because we are never supposed to touch QObjects from arbitrary threads — and this includes deleting them.

If we stick to a single-thread scenario, the code above works just fine. This is why I keep repeating that, although QObject is technically speaking reentrant, it’s better to treat it as thread-unsafe: only use a QObject from one thread (the thread the object lives into, or has affinity with).

Here’s the full details in case you want to know more:

Conclusions

That’s it for today’s blog. I hope I’ve explained what QPointer does, and when to use it.

There’s only one thing missing, which is the title of the blog post: why is QPointer a pretty bad name?

In my opinion, it should have been called for what it is: a weak pointer for QObject subclasses. So, how about QObjectWeakPointer? It’s not that Qt strives for very short names anyhow (hello, QXmlStreamNotationDeclaration); giving it a more descriptive name would remove confusion and actually ease discoverability.

Thank you for reading, and I’ll see you next time.