Signal/Slot Connection Throttlers

07.04.2021 Giuseppe D'Angelo 2 comments

Another day, another blog post about KDToolBox, KDAB’s collection of miscellaneous useful C++ classes and stuff.

Today, we’ll talk about ways to throttle your signal/slots connections — in other words, how to activate a slot less often than the emission rate of the signal it’s connected to. The usual reason why you may want something like this is performance. Invoking a slot at a high frequency may be too expensive for your application, so you need to rate-limit the slot’s activation.

That sounds very simple to achieve. All you need is love a timer and a little logic to (re)start the timer when a signal is received, then actually trigger the slot when the timer fires. However, as for many things, the devil is in the details.

In the industry, these rate-limiting behaviors have well-established names and behaviors: throttlers and debouncers (see here for some excellent examples).

• A throttler calls the slot only once every X milliseconds, no matter the input frequency of the signal. Use case: filtering out input events which may occur at a very high frequency (example: mouse events). An expensive operation triggered by these events (like scrolling and repainting) can be performed less often.
• A debouncer activates the slot only once, after a timeout / grace period calculated since the last signal emission. In other words, if a signal keeps coming, the slot is not activated. Use case: a search box that actually starts searching only after the user stops typing (that is, after a short timeout since the last user input).

Furthermore, throttlers and debouncers can be trailing or leading.

• Trailing means that the throttler/debouncer does not activate the slot immediately, but waits until its own timeout occurs before activating.
• Leading means to activate the slot as soon as the throttler/debouncer itself is activated, and does not trigger again until the timeout occurs (and only if another signal is received in the meanwhile).

You’ll be glad to know that we have pushed an implementation of throttlers and debouncers into KDToolBox.

Throttlers and Debouncers Usage

Their usage is very simple. First and foremost, create an object of the right kind and set it up:

// trailing throttler, rate limiting at 1 emission every 100ms
KDSignalThrottler *throttler = new KDSignalThrottler(parent);
throttler->setTimeout(100ms);

Then, place the throttler as an “intermediary” object between the signal that should be rate-limited and the slot that needs to be activated. You need to connect your signal to the throttle() slot of the throttler and the throttler’s own triggered() signal to the actual slot:

connect(sender, &Sender::signal, throttler, &KDSignalThrottler::throttle);
connect(throttler, &KDSignalThrottler::triggered, receiver, &Receiver::slot);

And voilà! Now, your slot activations will be rate-limited at a frequency of 10Hz, or less.

KDToolBox is freely available here. Thanks for reading, and have a great day!