UiWatchDog: a keepalive monitor for the GUI thread Part of the KDToolBox series

20.12.2019 Giuseppe D'Angelo No comments

Continuing our blog series about KDToolBox, this time we will discuss UiWatchDog, a keepalive monitor for the GUI thread.

Alive?

A fundamental rule when writing applications in event-driven UI frameworks such as Qt is: do not ever block the GUI thread!

The GUI thread is also usually called the main thread of the application — that is, the thread that runs main(). In Qt the GUI thread is somehow special, because it’s the only thread from which we can perform operations in our UI; these include creating, showing, modifying our controls; updating their contents on the screen; playing visual animations; handling keyboard and mouse events; and so on.

Doing any blocking I/O (such as disk access, networking, IPC), as well as running any computationally intensive operation from within the GUI thread is going to block it for a certain period of time.

If this period is too long, our GUI will become non-responsive, and there’s nothing more frustrating for the user to have an application that feels sluggish or worse doesn’t respond at all.

The definition of “too long” depends on the requirements we have. Of course, a few seconds is completely unacceptable — most operating systems will show that our application has frozen, and potentially will ask the user to terminate it. Below that limit, it really depends: while we could have some leeway for applications using Qt Widgets, a Qt Quick application that has animations all over the place would look terrible if those animations stutter. In other words, “too long” can be as small as a few milliseconds!

Using UiWatchDog

UiWatchDog is, by design, a header only utility to help detect when the GUI thread gets stuck. The usage is straightforward, just create an instance of it in your GUI thread and then call start():

#include "uiwatchdog.h"

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    UiWatchdog dog;
    dog.start();

    ~~~
}

If the GUI thread ever hangs for longer than a configurable time period, UiWatchDog will print debug messages to notify you of the fact. Under the hood, UiWatchDog simply spawns a separate thread that will keep checking that the GUI thread is not blocked, by “poking” it at regular intervals.

Note that you are supposed to modify the code in order to customize what should happen in case the GUI thread gets stuck; a self-explanatory comment in the source code will tell you exactly where. On Windows you can also make UiWatchDog request a debugger to be started; on other platforms it’s necessary to have a debugger already running and to install a breakpoint in the right place.

UIWatchDog is part of KDToolBox, KDAB’s collection of miscellaneous useful C++ classes and stuff. You can download it from our GitHub repository here. Have fun!