Giuseppe D’Angelo
20 December 2019
Continuing our blog series about KDToolBox, this time we will discuss UiWatchDog, a keepalive monitor for the GUI thread.
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!
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!
About KDAB
The KDAB Group is a globally recognized provider for software consulting, development and training, specializing in embedded devices and complex cross-platform desktop applications. In addition to being leading experts in Qt, C++ and 3D technologies for over two decades, KDAB provides deep expertise across the stack, including Linux, Rust and modern UI frameworks. With 100+ employees from 20 countries and offices in Sweden, Germany, USA, France and UK, we serve clients around the world.
Choose between learning advanced QML programming, Modern C++, integrating Rust and Qt or 3d rendering with Vulkan. The KDAB Training Day 2025 will take place in Munich on the 8th of May, right after the Qt World Summit on 6th to 7th of May.
Learn more
Stay on top of the latest news, publications, events and more.
Go to Sign-up
Learn Modern C++
Our hands-on Modern C++ training courses are designed to quickly familiarize newcomers with the language. They also update professional C++ developers on the latest changes in the language and standard library introduced in recent C++ editions.
Learn more