#include <kis_updater_context.h>

Inheritance diagram for KisUpdaterContext:

Public Member Functions
void	addMergeJob (KisBaseRectsWalkerSP walker)

void	addSpontaneousJob (KisSpontaneousJob *spontaneousJob)

void	addStrokeJob (KisStrokeJob *strokeJob)

void	continueUpdate (const QRect &rc)

int	currentLevelOfDetail () const

void	doSomeUsefulWork ()

KisUpdaterContextSnapshotEx	getContextSnapshotEx () const

void	getJobsSnapshot (qint32 &numMergeJobs, qint32 &numStrokeJobs)

bool	hasSpareThread ()

bool	isJobAllowed (KisBaseRectsWalkerSP walker)

void	jobFinished ()

void	jobThreadExited ()

	KisUpdaterContext (qint32 threadCount=useIdealThreadCountTag, KisUpdateScheduler *parent=0)

void	lock ()

void	setTestingMode (bool value)

void	setThreadsLimit (int value)

int	threadsLimit () const

void	unlock ()

void	waitForDone ()

	~KisUpdaterContext ()

Static Public Attributes
static const int	useIdealThreadCountTag = -1

Protected Member Functions
qint32	findSpareThread ()

Static Protected Member Functions
static bool	walkerIntersectsJob (KisBaseRectsWalkerSP walker, const KisUpdateJobItem *job)

Protected Attributes
QReadWriteLock	m_exclusiveJobLock

QVector< KisUpdateJobItem * >	m_jobs

QMutex	m_lock

KisLockFreeLodCounter	m_lodCounter

int	m_numRunningThreads = 0

QMutex	m_runningThreadsMutex

KisUpdateScheduler *	m_scheduler

bool	m_testingMode = false

QThreadPool	m_threadPool

QWaitCondition	m_waitForDoneCondition

Private Member Functions
void	clear ()

const QVector< KisUpdateJobItem * >	getJobs ()

void	startThread (int index)

Friends
class	KisSimpleUpdateQueueTest

class	KisStrokesQueueTest

class	KisUpdateJobItem

class	KisUpdaterContextTest

class	KisUpdateSchedulerTest

Detailed Description

Definition at line 27 of file kis_updater_context.h.

Constructor & Destructor Documentation

◆ KisUpdaterContext()

KisUpdaterContext::KisUpdaterContext	(	qint32	threadCount = useIdealThreadCountTag,
		KisUpdateScheduler *	parent = 0 )

Definition at line 18 of file kis_updater_context.cpp.

    : m_scheduler(parent)
{
    if(threadCount <= 0) {
        threadCount = QThread::idealThreadCount();
        threadCount = threadCount > 0 ? threadCount : 1;
    }
 
    setThreadsLimit(threadCount);
}

References setThreadsLimit().

◆ ~KisUpdaterContext()

KisUpdaterContext::~KisUpdaterContext ( )

Definition at line 29 of file kis_updater_context.cpp.

{
    m_threadPool.waitForDone();
 
    if (m_testingMode) {
        clear();
    }
 
    qDeleteAll(m_jobs);
}

References clear(), m_jobs, m_testingMode, and m_threadPool.

Member Function Documentation

◆ addMergeJob()

void KisUpdaterContext::addMergeJob ( KisBaseRectsWalkerSP walker )

Registers the job and starts executing it. The caller must ensure that the context is locked with lock(), job is allowed with isWalkerAllowed() and there is a spare thread for running it with hasSpareThread()

See also: lock(); isWalkerAllowed(); hasSpareThread()

NOTE: In theory, isJobAllowed() and addMergeJob() should be merged into one atomic method like bool push(), because this implementation of KisUpdaterContext will not work in case of multiple producers. But currently we have only one producer (one thread in a time), that is guaranteed by the lock()/unlock() pair in KisAbstractUpdateQueue::processQueue.

Definition at line 164 of file kis_updater_context.cpp.

{
    m_lodCounter.addLod(walker->levelOfDetail());
    qint32 jobIndex = findSpareThread();
    Q_ASSERT(jobIndex >= 0);
 
    const bool shouldStartThread = m_jobs[jobIndex]->setWalker(walker);
 
    // it might happen that we call this function from within
    // the thread itself, right when it finished its work
    if (shouldStartThread && !m_testingMode) {
        startThread(jobIndex);
    }
}

References KisLockFreeLodCounter::addLod(), findSpareThread(), KisBaseRectsWalker::levelOfDetail(), m_jobs, m_lodCounter, m_testingMode, and startThread().

◆ addSpontaneousJob()

void KisUpdaterContext::addSpontaneousJob ( KisSpontaneousJob * spontaneousJob )

Adds a spontaneous job to the context. The prerequisites are the same as for addMergeJob()

See also: addMergeJob()

Definition at line 194 of file kis_updater_context.cpp.

{
    m_lodCounter.addLod(spontaneousJob->levelOfDetail());
    qint32 jobIndex = findSpareThread();
    Q_ASSERT(jobIndex >= 0);
 
    const bool shouldStartThread = m_jobs[jobIndex]->setSpontaneousJob(spontaneousJob);
 
    // it might happen that we call this function from within
    // the thread itself, right when it finished its work
    if (shouldStartThread && !m_testingMode) {
        startThread(jobIndex);
    }
}

References KisLockFreeLodCounter::addLod(), findSpareThread(), KisSpontaneousJob::levelOfDetail(), m_jobs, m_lodCounter, m_testingMode, and startThread().

◆ addStrokeJob()

void KisUpdaterContext::addStrokeJob ( KisStrokeJob * strokeJob )

Adds a stroke job to the context. The prerequisites are the same as for addMergeJob()

See also: addMergeJob()

Definition at line 179 of file kis_updater_context.cpp.

{
    m_lodCounter.addLod(strokeJob->levelOfDetail());
    qint32 jobIndex = findSpareThread();
    Q_ASSERT(jobIndex >= 0);
 
    const bool shouldStartThread = m_jobs[jobIndex]->setStrokeJob(strokeJob);
 
    // it might happen that we call this function from within
    // the thread itself, right when it finished its work
    if (shouldStartThread && !m_testingMode) {
        startThread(jobIndex);
    }
}

References KisLockFreeLodCounter::addLod(), findSpareThread(), KisStrokeJob::levelOfDetail(), m_jobs, m_lodCounter, m_testingMode, and startThread().

◆ clear()

void KisUpdaterContext::clear ( )

private

Definition at line 312 of file kis_updater_context.cpp.

{
    Q_FOREACH (KisUpdateJobItem *item, m_jobs) {
        item->testingSetDone();
    }
 
    m_lodCounter.testingClear();
}

References m_jobs, m_lodCounter, KisLockFreeLodCounter::testingClear(), and KisUpdateJobItem::testingSetDone().

◆ continueUpdate()

void KisUpdaterContext::continueUpdate ( const QRect & rc )

Definition at line 275 of file kis_updater_context.cpp.

{
    if (m_scheduler) m_scheduler->continueUpdate(rc);
}

References KisUpdateScheduler::continueUpdate(), and m_scheduler.

◆ currentLevelOfDetail()

int KisUpdaterContext::currentLevelOfDetail ( ) const

Returns the current level of detail of all the running jobs in the context. If there are no jobs, returns -1.

Definition at line 99 of file kis_updater_context.cpp.

{
    return m_lodCounter.readLod();
}

References m_lodCounter, and KisLockFreeLodCounter::readLod().

◆ doSomeUsefulWork()

void KisUpdaterContext::doSomeUsefulWork ( )

Definition at line 280 of file kis_updater_context.cpp.

{
    if (m_scheduler) m_scheduler->doSomeUsefulWork();
}

References KisUpdateScheduler::doSomeUsefulWork(), and m_scheduler.

◆ findSpareThread()

qint32 KisUpdaterContext::findSpareThread ( )

protected

Definition at line 230 of file kis_updater_context.cpp.

{
    for(qint32 i=0; i < m_jobs.size(); i++)
        if(!m_jobs[i]->isRunning())
            return i;
 
    return -1;
}

References m_jobs.

◆ getContextSnapshotEx()

KisUpdaterContextSnapshotEx KisUpdaterContext::getContextSnapshotEx ( ) const

We cannot use Q_FOREACH here since the function may be called concurrently without any locks, causing detaching of the vector and causing a crash. Only read-only accesses are allowed in such environment

Definition at line 64 of file kis_updater_context.cpp.

{
    KisUpdaterContextSnapshotEx state = ContextEmpty;
 
    for (const KisUpdateJobItem *item : std::as_const(m_jobs)) {
        if (item->type() == KisUpdateJobItem::Type::MERGE ||
            item->type() == KisUpdateJobItem::Type::SPONTANEOUS) {
            state |= HasMergeJob;
        } else if(item->type() == KisUpdateJobItem::Type::STROKE) {
            switch (item->strokeJobSequentiality()) {
            case KisStrokeJobData::SEQUENTIAL:
                state |= HasSequentialJob;
                break;
            case KisStrokeJobData::CONCURRENT:
                state |= HasConcurrentJob;
                break;
            case KisStrokeJobData::BARRIER:
                state |= HasBarrierJob;
                break;
            case KisStrokeJobData::UNIQUELY_CONCURRENT:
                state |= HasUniquelyConcurrentJob;
                break;
            }
        }
    }
 
    return state;
}

References KisStrokeJobData::BARRIER, KisStrokeJobData::CONCURRENT, ContextEmpty, HasBarrierJob, HasConcurrentJob, HasMergeJob, HasSequentialJob, HasUniquelyConcurrentJob, m_jobs, KisUpdateJobItem::MERGE, KisStrokeJobData::SEQUENTIAL, KisUpdateJobItem::SPONTANEOUS, KisUpdateJobItem::STROKE, and KisStrokeJobData::UNIQUELY_CONCURRENT.

◆ getJobs()

const QVector< KisUpdateJobItem * > KisUpdaterContext::getJobs ( )

private

Definition at line 307 of file kis_updater_context.cpp.

{
    return m_jobs;
}

References m_jobs.

◆ getJobsSnapshot()

void KisUpdaterContext::getJobsSnapshot	(	qint32 &	numMergeJobs,
		qint32 &	numStrokeJobs )

Returns the number of currently running jobs of each type. To use this information you should lock the context beforehand.

See also: lock()

We cannot use Q_FOREACH here since the function may be called concurrently without any locks, causing detaching of the vector and causing a crash. Only read-only accesses are allowed in such environment

Definition at line 40 of file kis_updater_context.cpp.

{
    numMergeJobs = 0;
    numStrokeJobs = 0;
 
    for (const KisUpdateJobItem *item : std::as_const(m_jobs)) {
 
        if(item->type() == KisUpdateJobItem::Type::MERGE ||
           item->type() == KisUpdateJobItem::Type::SPONTANEOUS) {
            numMergeJobs++;
        }
        else if(item->type() == KisUpdateJobItem::Type::STROKE) {
            numStrokeJobs++;
        }
    }
}

References m_jobs, KisUpdateJobItem::MERGE, KisUpdateJobItem::SPONTANEOUS, and KisUpdateJobItem::STROKE.

◆ hasSpareThread()

bool KisUpdaterContext::hasSpareThread ( )

Check whether there is a spare thread for running one more job

We cannot use Q_FOREACH here since the function may be called concurrently without any locks, causing detaching of the vector and causing a crash. Only read-only accesses are allowed in such environment

Definition at line 104 of file kis_updater_context.cpp.

{
    bool found = false;
 
    for (const KisUpdateJobItem *item : std::as_const(m_jobs)) {
        if(!item->isRunning()) {
            found = true;
            break;
        }
    }
    return found;
}

References m_jobs.

◆ isJobAllowed()

bool KisUpdaterContext::isJobAllowed ( KisBaseRectsWalkerSP walker )

Checks whether the walker intersects with any of currently executing walkers. If it does, it is not allowed to go in. It should be called with the lock held.

See also: lock()

We cannot use Q_FOREACH here since the function may be called concurrently without any locks, causing detaching of the vector and causing a crash. Only read-only accesses are allowed in such environment

Definition at line 123 of file kis_updater_context.cpp.

{
    int lod = this->currentLevelOfDetail();
    if (lod >= 0 && walker->levelOfDetail() != lod) return false;
 
    bool intersects = false;
 
    for (const KisUpdateJobItem *item : std::as_const(m_jobs)) {
        if(item->isRunning() && walkerIntersectsJob(walker, item)) {
            intersects = true;
            break;
        }
    }
 
    return !intersects;
}

References currentLevelOfDetail(), KisBaseRectsWalker::levelOfDetail(), m_jobs, and walkerIntersectsJob().

◆ jobFinished()

void KisUpdaterContext::jobFinished ( )

Definition at line 285 of file kis_updater_context.cpp.

{
    m_lodCounter.removeLod();
    if (m_scheduler) m_scheduler->spareThreadAppeared();
}

References m_lodCounter, m_scheduler, KisLockFreeLodCounter::removeLod(), and KisUpdateScheduler::spareThreadAppeared().

◆ jobThreadExited()

void KisUpdaterContext::jobThreadExited ( )

Definition at line 291 of file kis_updater_context.cpp.

{
    QMutexLocker l(&m_runningThreadsMutex);
    m_numRunningThreads--;
    KIS_SAFE_ASSERT_RECOVER_NOOP(m_numRunningThreads >= 0);
 
    if (m_numRunningThreads <= 0) {
        m_waitForDoneCondition.wakeAll();
    }
}

References KIS_SAFE_ASSERT_RECOVER_NOOP, m_numRunningThreads, m_runningThreadsMutex, and m_waitForDoneCondition.

◆ lock()

void KisUpdaterContext::lock ( )

Locks the context to guarantee an exclusive access to the context

Definition at line 239 of file kis_updater_context.cpp.

{
    m_lock.lock();
}

References m_lock.

◆ setTestingMode()

void KisUpdaterContext::setTestingMode ( bool value )

Definition at line 302 of file kis_updater_context.cpp.

{
    m_testingMode = value;
}

References m_testingMode, and value().

◆ setThreadsLimit()

void KisUpdaterContext::setThreadsLimit ( int value )

Set the number of threads available for this updater context WARNING: one cannot change the number of threads if there is at least one job running in the context! So before calling this method make sure you do two things: 1) barrierLock() the update scheduler 2) lock() the context

Definition at line 249 of file kis_updater_context.cpp.

{
    m_threadPool.setMaxThreadCount(value);
 
    for (int i = 0; i < m_jobs.size(); i++) {
        KIS_SAFE_ASSERT_RECOVER_RETURN(!m_jobs[i]->isRunning());
        // don't delete the jobs until all of them are checked!
    }
 
    for (int i = 0; i < m_jobs.size(); i++) {
        delete m_jobs[i];
    }
 
    m_jobs.resize(value);
 
    for(qint32 i = 0; i < m_jobs.size(); i++) {
        m_jobs[i] = new KisUpdateJobItem(this);
    }
}

References KIS_SAFE_ASSERT_RECOVER_RETURN, KisUpdateJobItem, m_jobs, m_threadPool, and value().

◆ startThread()

void KisUpdaterContext::startThread ( int index )

private

Definition at line 146 of file kis_updater_context.cpp.

{
    {
        QMutexLocker l(&m_runningThreadsMutex);
        m_numRunningThreads++;
    }
 
    m_threadPool.start(m_jobs[index]);
}

References m_jobs, m_numRunningThreads, m_runningThreadsMutex, and m_threadPool.

◆ threadsLimit()

int KisUpdaterContext::threadsLimit ( ) const

Return the number of available threads in the context. Make sure you lock the context before calling this function!

Definition at line 269 of file kis_updater_context.cpp.

{
    KIS_SAFE_ASSERT_RECOVER_NOOP(m_jobs.size() == m_threadPool.maxThreadCount());
    return m_jobs.size();
}

References KIS_SAFE_ASSERT_RECOVER_NOOP, m_jobs, and m_threadPool.

◆ unlock()

void KisUpdaterContext::unlock ( )

Unlocks the context

See also: lock()

Definition at line 244 of file kis_updater_context.cpp.

{
    m_lock.unlock();
}

References m_lock.

◆ waitForDone()

void KisUpdaterContext::waitForDone ( )

Block execution of the caller until all the jobs are finished

Definition at line 209 of file kis_updater_context.cpp.

{
    QMutexLocker l(&m_runningThreadsMutex);
 
    while(m_numRunningThreads > 0) {
        m_waitForDoneCondition.wait(l.mutex());
    }
}

References m_numRunningThreads, m_runningThreadsMutex, and m_waitForDoneCondition.

◆ walkerIntersectsJob()

bool KisUpdaterContext::walkerIntersectsJob	(	KisBaseRectsWalkerSP	walker,
		const KisUpdateJobItem *	job )

staticprotected

TODO: theoretically, we should compare rects intersection on a per-layer basis. The current solution is too rough and basically makes updates single-threaded in some cases (e.g. when a transform mask is present in the stack)

Definition at line 218 of file kis_updater_context.cpp.

{
    return walker->accessRect().intersects(job->accessRect());
}

References KisBaseRectsWalker::accessRect(), and KisUpdateJobItem::accessRect().

Friends And Related Symbol Documentation

◆ KisSimpleUpdateQueueTest

friend class KisSimpleUpdateQueueTest

friend

Definition at line 166 of file kis_updater_context.h.

◆ KisStrokesQueueTest

friend class KisStrokesQueueTest

friend

Definition at line 165 of file kis_updater_context.h.

◆ KisUpdateJobItem

friend class KisUpdateJobItem

friend

Definition at line 167 of file kis_updater_context.h.

◆ KisUpdaterContextTest

friend class KisUpdaterContextTest

friend

Definition at line 163 of file kis_updater_context.h.

◆ KisUpdateSchedulerTest

friend class KisUpdateSchedulerTest

friend

Definition at line 164 of file kis_updater_context.h.

Member Data Documentation

◆ m_exclusiveJobLock

QReadWriteLock KisUpdaterContext::m_exclusiveJobLock

protected

The lock is shared by all the child update job items. When an item wants to run a usual (non-exclusive) job, it locks the lock for read access. When an exclusive access is requested, it locks it for write

Definition at line 149 of file kis_updater_context.h.

◆ m_jobs

QVector<KisUpdateJobItem*> KisUpdaterContext::m_jobs

protected

Definition at line 155 of file kis_updater_context.h.

◆ m_lock

QMutex KisUpdaterContext::m_lock

protected

Definition at line 151 of file kis_updater_context.h.

◆ m_lodCounter

KisLockFreeLodCounter KisUpdaterContext::m_lodCounter

protected

Definition at line 157 of file kis_updater_context.h.

◆ m_numRunningThreads

int KisUpdaterContext::m_numRunningThreads = 0

protected

Definition at line 153 of file kis_updater_context.h.

◆ m_runningThreadsMutex

QMutex KisUpdaterContext::m_runningThreadsMutex

protected

Definition at line 152 of file kis_updater_context.h.

◆ m_scheduler

KisUpdateScheduler* KisUpdaterContext::m_scheduler

protected

Definition at line 158 of file kis_updater_context.h.

◆ m_testingMode

bool KisUpdaterContext::m_testingMode = false

protected

Definition at line 159 of file kis_updater_context.h.

◆ m_threadPool

QThreadPool KisUpdaterContext::m_threadPool

protected

Definition at line 156 of file kis_updater_context.h.

◆ m_waitForDoneCondition

QWaitCondition KisUpdaterContext::m_waitForDoneCondition

protected

Definition at line 154 of file kis_updater_context.h.

◆ useIdealThreadCountTag

const int KisUpdaterContext::useIdealThreadCountTag = -1

static

Definition at line 30 of file kis_updater_context.h.

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

libs/image/kis_updater_context.h
libs/image/kis_updater_context.cpp

Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Private Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ KisUpdaterContext()

◆ ~KisUpdaterContext()

Member Function Documentation

◆ addMergeJob()

◆ addSpontaneousJob()

◆ addStrokeJob()

◆ clear()

◆ continueUpdate()

◆ currentLevelOfDetail()

◆ doSomeUsefulWork()

◆ findSpareThread()

◆ getContextSnapshotEx()

◆ getJobs()

◆ getJobsSnapshot()

◆ hasSpareThread()

◆ isJobAllowed()

◆ jobFinished()

◆ jobThreadExited()

◆ lock()

◆ setTestingMode()

◆ setThreadsLimit()

◆ startThread()

◆ threadsLimit()

◆ unlock()

◆ waitForDone()

◆ walkerIntersectsJob()

Friends And Related Symbol Documentation

◆ KisSimpleUpdateQueueTest

◆ KisStrokesQueueTest

◆ KisUpdateJobItem

◆ KisUpdaterContextTest

◆ KisUpdateSchedulerTest

Member Data Documentation

◆ m_exclusiveJobLock

◆ m_jobs

◆ m_lock

◆ m_lodCounter

◆ m_numRunningThreads

◆ m_runningThreadsMutex

◆ m_scheduler

◆ m_testingMode

◆ m_threadPool

◆ m_waitForDoneCondition

◆ useIdealThreadCountTag