KisSignalCompressor Class Reference

#include <kis_signal_compressor.h>

Inheritance diagram for KisSignalCompressor:

Public Types
enum	Mode {   POSTPONE , FIRST_ACTIVE_POSTPONE_NEXT , FIRST_ACTIVE , FIRST_INACTIVE ,   UNDEFINED }
enum	SlowHandlerMode { PRECISE_INTERVAL , ADDITIVE_INTERVAL }

Public Slots
void	setDelay (int delay)
void	start ()
void	stop ()

Signals
void	timeout ()

Public Member Functions
int	delay () const
bool	isActive () const
	KisSignalCompressor ()
	KisSignalCompressor (int delay, Mode mode, QObject *parent=0)
	KisSignalCompressor (int delay, Mode mode, SlowHandlerMode slowHandlerMode, QObject *parent=0)
void	setDelay (std::function< bool()> idleCallback, int idleDelay, int timeout)
void	setMode (Mode mode)

Private Slots
void	slotTimerExpired ()

Private Member Functions
void	setDelayImpl (int delay)
bool	tryEmitOnTick (bool isFromTimer)
bool	tryEmitSignalSafely ()

Private Attributes
std::function< bool()>	m_idleCallback
int	m_isEmitting = 0
QElapsedTimer	m_lastEmittedTimer
Mode	m_mode = UNDEFINED
int	m_sanityIsStarting = 0
bool	m_signalsPending = false
SlowHandlerMode	m_slowHandlerMode = PRECISE_INTERVAL
int	m_timeout = 0
QTimer *	m_timer = 0

Detailed Description

Sets a timer to delay or throttle activation of a Qt slot. One example of where this is used is to limit the amount of expensive redraw activity on the canvas.

There are four behaviors to choose from.

POSTPONE resets the timer after each call. Therefore if the calls are made quickly enough, the timer will never be activated.

FIRST_ACTIVE_POSTPONE_NEXT emits the first signal and postpones all the other actions like in POSTPONE. This mode is used e.g. in move/remove layer functionality. If you remove a single layer, you'll see the result immediately. But if you want to remove multiple layers, you should wait until all the actions are finished.

FIRST_ACTIVE emits the timeout() event immediately and sets a timer of duration delay. If the compressor is triggered during this time, it will wait until the end of the delay period to fire the signal. Further events are ignored until the timer elapses. Think of it as a queue with size 1, and where the leading element is popped every delay ms.

FIRST_INACTIVE emits the timeout() event at the end of a timer of duration delay ms. The compressor becomes inactive and all events are ignored until the timer has elapsed.

The current implementation allows the timeout() to be delayed by up to 2 times delay in certain situations (for details see cpp file).

Definition at line 48 of file kis_signal_compressor.h.

Member Enumeration Documentation

Mode

enum KisSignalCompressor::Mode

Enumerator
POSTPONE
FIRST_ACTIVE_POSTPONE_NEXT
FIRST_ACTIVE
FIRST_INACTIVE
UNDEFINED

Definition at line 53 of file kis_signal_compressor.h.

              {
        POSTPONE, /* Calling start() resets the timer to \p delay ms */
        FIRST_ACTIVE_POSTPONE_NEXT, /* emits the first signal and postpones all the next ones */
        FIRST_ACTIVE, /* Emit timeout() signal immediately. Throttle further timeout() to rate of one per \p delay ms */
        FIRST_INACTIVE, /* Set a timer \p delay ms, Q_EMIT timeout() when it elapses. Ignore all events meanwhile. */
        UNDEFINED /* KisSignalCompressor is created without an explicit mode */
    };

SlowHandlerMode

enum KisSignalCompressor::SlowHandlerMode

Enumerator
PRECISE_INTERVAL
ADDITIVE_INTERVAL

Definition at line 61 of file kis_signal_compressor.h.

                         {
        PRECISE_INTERVAL, /* Interval of timeout is forced to \p delay ms, whatever time the handler of timeout() takes */
        ADDITIVE_INTERVAL /* When the handler of timeout() is slow, the timeout delay is increased to the (delay + handler_time) */
    };

Constructor & Destructor Documentation

KisSignalCompressor() [1/3]

KisSignalCompressor::KisSignalCompressor

(

)

KisSignalCompressor will never trigger timeout more often than every delay ms, i.e. delay ms is a given lower limit defining the highest frequency.

The current implementation uses a long-running monitor timer to eliminate the overhead incurred by restarting and stopping timers with each signal. The consequence of this is that the given delay ms is not always exactly followed.

KisSignalCompressor makes the following callback guarantees (0 < err <= 1, with err == 0 if this is the first signal after a while):

POSTPONE:

• timeout after = [0.5 ... 1.0] * delay ms. FIRST_ACTIVE_POSTPONE_NEXT:
• first timeout immediately
• postponed timeout after [0.5 ... 1.0] * delay ms FIRST_ACTIVE:
• first timeout immediately
• after that [0.5 ... 1.5] * delay ms FIRST_INACTIVE:
• timeout after [0.5 ... 1.5] * delay ms

Definition at line 37 of file kis_signal_compressor.cpp.

    : QObject(0)
    , m_timer(new QTimer(this))
{
    m_timer->setSingleShot(false);
    connect(m_timer, SIGNAL(timeout()), SLOT(slotTimerExpired()));
}

References connect(), m_timer, slotTimerExpired(), and timeout().

KisSignalCompressor() [2/3]

KisSignalCompressor::KisSignalCompressor	(	int	delay,
		Mode	mode,
		QObject *	parent = 0 )

Definition at line 45 of file kis_signal_compressor.cpp.

    : KisSignalCompressor(delay, mode, PRECISE_INTERVAL, parent)
{
}

KisSignalCompressor() [3/3]

KisSignalCompressor::KisSignalCompressor	(	int	delay,
		Mode	mode,
		SlowHandlerMode	slowHandlerMode,
		QObject *	parent = 0 )

Definition at line 50 of file kis_signal_compressor.cpp.

    : QObject(parent),
      m_timer(new QTimer(this)),
      m_mode(mode),
      m_slowHandlerMode(slowHandlerMode),
      m_timeout(delay)
{
    m_timer->setSingleShot(false);
    m_timer->setInterval(delay);
    connect(m_timer, SIGNAL(timeout()), SLOT(slotTimerExpired()));
}

References connect(), delay(), m_timer, slotTimerExpired(), and timeout().

Member Function Documentation

delay()

int KisSignalCompressor::delay

(

)

const

Definition at line 240 of file kis_signal_compressor.cpp.

{
    return m_timeout;
}

References m_timeout.

isActive()

bool KisSignalCompressor::isActive

(

)

const

Definition at line 230 of file kis_signal_compressor.cpp.

{
    return m_signalsPending && m_timer->isActive();
}

References m_signalsPending, and m_timer.

setDelay [1/2]

void KisSignalCompressor::setDelay ( int delay )

slot

Definition at line 77 of file kis_signal_compressor.cpp.

{
    m_timeout = delay;
    m_idleCallback = {};
    setDelayImpl(delay);
}

References delay(), m_idleCallback, m_timeout, and setDelayImpl().

setDelay() [2/2]

void KisSignalCompressor::setDelay	(	std::function< bool()>	idleCallback,
		int	idleDelay,
		int	timeout )

Definition at line 84 of file kis_signal_compressor.cpp.

{
    m_timeout = timeout;
    m_idleCallback = idleCallback;
    setDelayImpl(idleDelay);
}

References m_idleCallback, m_timeout, setDelayImpl(), and timeout().

setDelayImpl()

void KisSignalCompressor::setDelayImpl ( int delay )

private

Definition at line 62 of file kis_signal_compressor.cpp.

{
    const bool wasActive = m_timer->isActive();
 
    if (wasActive) {
        m_timer->stop();
    }
 
    m_timer->setInterval(delay);
 
    if (wasActive) {
        m_timer->start();
    }
}

References delay(), and m_timer.

setMode()

void KisSignalCompressor::setMode

(

KisSignalCompressor::Mode

mode

)

Definition at line 235 of file kis_signal_compressor.cpp.

{
    m_mode = mode;
}

References m_mode.

slotTimerExpired

void KisSignalCompressor::slotTimerExpired ( )

privateslot

Definition at line 208 of file kis_signal_compressor.cpp.

{
    KIS_SAFE_ASSERT_RECOVER_NOOP(!m_sanityIsStarting);
    KIS_ASSERT_RECOVER_NOOP(m_mode != UNDEFINED);
    if (!tryEmitOnTick(true)) {
        const int calmDownInterval = 5 * m_timeout;
 
        if (!m_lastEmittedTimer.isValid() ||
            m_lastEmittedTimer.elapsed() > calmDownInterval) {
 
            m_timer->stop();
        }
    }
}

References KIS_ASSERT_RECOVER_NOOP, KIS_SAFE_ASSERT_RECOVER_NOOP, m_lastEmittedTimer, m_mode, m_sanityIsStarting, m_timeout, m_timer, tryEmitOnTick(), and UNDEFINED.

start

void KisSignalCompressor::start ( )

slot

Definition at line 91 of file kis_signal_compressor.cpp.

{
    KIS_SAFE_ASSERT_RECOVER_RETURN(m_mode != UNDEFINED);
 
    const bool isFirstStart = !m_timer->isActive();
 
    KIS_SAFE_ASSERT_RECOVER_NOOP(!isFirstStart || !m_signalsPending);
    m_sanityIsStarting++;
 
 
    switch (m_mode) {
    case POSTPONE:
        if (isFirstStart) {
            m_timer->start();
        }
        m_lastEmittedTimer.restart();
        m_signalsPending = true;
        break;
    case FIRST_ACTIVE_POSTPONE_NEXT:
    case FIRST_ACTIVE:
        if (isFirstStart) {
            m_timer->start();
            if (m_slowHandlerMode == PRECISE_INTERVAL) {
                m_lastEmittedTimer.restart();
            }
            m_signalsPending = false;
            if (!tryEmitSignalSafely()) {
                m_signalsPending = true;
            }
            if (m_slowHandlerMode == ADDITIVE_INTERVAL) {
                m_lastEmittedTimer.restart();
            }
        } else {
            if (m_mode == FIRST_ACTIVE) {
                m_signalsPending = true;
                tryEmitOnTick(false);
            } else {
                m_lastEmittedTimer.restart();
                m_signalsPending = true;
            }
        }
        break;
    case FIRST_INACTIVE:
        if (isFirstStart) {
            m_timer->start();
            m_lastEmittedTimer.restart();
            m_signalsPending = true;
        } else {
            m_signalsPending = true;
            tryEmitOnTick(false);
        }
    case UNDEFINED:
        ; // Should never happen, but do nothing
    };
 
    m_sanityIsStarting--;
 
    KIS_SAFE_ASSERT_RECOVER(m_timer->isActive()) {
        m_timer->start();
    }
}

References ADDITIVE_INTERVAL, FIRST_ACTIVE, FIRST_ACTIVE_POSTPONE_NEXT, FIRST_INACTIVE, KIS_SAFE_ASSERT_RECOVER, KIS_SAFE_ASSERT_RECOVER_NOOP, KIS_SAFE_ASSERT_RECOVER_RETURN, m_lastEmittedTimer, m_mode, m_sanityIsStarting, m_signalsPending, m_slowHandlerMode, m_timer, POSTPONE, PRECISE_INTERVAL, tryEmitOnTick(), tryEmitSignalSafely(), and UNDEFINED.

stop

void KisSignalCompressor::stop ( )

slot

Definition at line 223 of file kis_signal_compressor.cpp.

{
    m_timer->stop();
    m_signalsPending = false;
    m_lastEmittedTimer.invalidate();
}

References m_lastEmittedTimer, m_signalsPending, and m_timer.

timeout

void KisSignalCompressor::timeout ( )

signal

tryEmitOnTick()

bool KisSignalCompressor::tryEmitOnTick ( bool isFromTimer )

private

Definition at line 153 of file kis_signal_compressor.cpp.

{
    bool wasEmitted = false;
 
    // we have different requirements for hi-frequency events (the mean
    // of the events rate must be min(compressorRate, eventsRate)
    const int realInterval = m_timeout;
    const int minInterval = realInterval < 100 ? 0.5 * realInterval : realInterval;
 
    // Enable for debugging:
    // ENTER_FUNCTION() << ppVar(isFromTimer) << ppVar(m_signalsPending) << m_lastEmittedTimer.elapsed() << ppVar((m_idleCallback && m_idleCallback()));
 
    if (m_signalsPending &&
            (m_lastEmittedTimer.elapsed() >= minInterval ||
             (m_idleCallback && m_idleCallback()))) {
 
        KIS_SAFE_ASSERT_RECOVER_NOOP(!isFromTimer || !m_isEmitting);
 
        if (m_slowHandlerMode == PRECISE_INTERVAL) {
            m_lastEmittedTimer.start();
        }
 
        m_signalsPending = false;
        if (!tryEmitSignalSafely()) {
            m_signalsPending = true;
        }
 
        if (m_slowHandlerMode == ADDITIVE_INTERVAL) {
            m_lastEmittedTimer.start();
        }
 
        wasEmitted = true;
    } else if (!isFromTimer) {
        m_signalsPending = true;
    }
 
    return wasEmitted;
}

References ADDITIVE_INTERVAL, KIS_SAFE_ASSERT_RECOVER_NOOP, m_idleCallback, m_isEmitting, m_lastEmittedTimer, m_signalsPending, m_slowHandlerMode, m_timeout, PRECISE_INTERVAL, and tryEmitSignalSafely().

tryEmitSignalSafely()

bool KisSignalCompressor::tryEmitSignalSafely ( )

private

Definition at line 192 of file kis_signal_compressor.cpp.

{
    bool wasEmitted = false;
 
    m_isEmitting++;
 
    if (m_isEmitting == 1) {
        Q_EMIT timeout();
        wasEmitted = true;
    }
 
    m_isEmitting--;
 
    return wasEmitted;
}

References m_isEmitting, and timeout().

Member Data Documentation

m_idleCallback

std::function<bool()> KisSignalCompressor::m_idleCallback

private

Definition at line 101 of file kis_signal_compressor.h.

m_isEmitting

int KisSignalCompressor::m_isEmitting = 0

private

Definition at line 99 of file kis_signal_compressor.h.

m_lastEmittedTimer

QElapsedTimer KisSignalCompressor::m_lastEmittedTimer

private

Definition at line 98 of file kis_signal_compressor.h.

m_mode

Mode KisSignalCompressor::m_mode = UNDEFINED

private

Definition at line 95 of file kis_signal_compressor.h.

m_sanityIsStarting

int KisSignalCompressor::m_sanityIsStarting = 0

private

Definition at line 102 of file kis_signal_compressor.h.

m_signalsPending

bool KisSignalCompressor::m_signalsPending = false

private

Definition at line 97 of file kis_signal_compressor.h.

m_slowHandlerMode

SlowHandlerMode KisSignalCompressor::m_slowHandlerMode = PRECISE_INTERVAL

private

Definition at line 96 of file kis_signal_compressor.h.

m_timeout

int KisSignalCompressor::m_timeout = 0

private

Definition at line 100 of file kis_signal_compressor.h.

m_timer

QTimer* KisSignalCompressor::m_timer = 0

private

Definition at line 94 of file kis_signal_compressor.h.

---

The documentation for this class was generated from the following files:

• libs/global/kis_signal_compressor.h
• libs/global/kis_signal_compressor.cpp