KisUpdaterContext Class Reference

#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	isIdle () const
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 320 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 283 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 288 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 238 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 315 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.

isIdle()

bool KisUpdaterContext::isIdle

(

)

const

Returns true if there are no jobs running in the context

If there is any contestion on the context's mutex, the function will simply return false, whatever context's state really is. Obviously, if there is a contention, the object is not "idle" :)

Definition at line 218 of file kis_updater_context.cpp.

{
    std::unique_lock<QMutex> locker(m_runningThreadsMutex, std::try_to_lock);
    if (!locker.owns_lock()) return false;
 
    return m_numRunningThreads == 0;
}

References m_numRunningThreads, and m_runningThreadsMutex.

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 293 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 299 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 247 of file kis_updater_context.cpp.

{
    m_lock.lock();
}

References m_lock.

setTestingMode()

void KisUpdaterContext::setTestingMode

(

bool

value

)

Definition at line 310 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 257 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 277 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 252 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 226 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 175 of file kis_updater_context.h.

KisStrokesQueueTest

friend class KisStrokesQueueTest

friend

Definition at line 174 of file kis_updater_context.h.

KisUpdateJobItem

friend class KisUpdateJobItem

friend

Definition at line 176 of file kis_updater_context.h.

KisUpdaterContextTest

friend class KisUpdaterContextTest

friend

Definition at line 172 of file kis_updater_context.h.

KisUpdateSchedulerTest

friend class KisUpdateSchedulerTest

friend

Definition at line 173 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 158 of file kis_updater_context.h.

m_jobs

QVector<KisUpdateJobItem*> KisUpdaterContext::m_jobs

protected

Definition at line 164 of file kis_updater_context.h.

m_lock

QMutex KisUpdaterContext::m_lock

protected

Definition at line 160 of file kis_updater_context.h.

m_lodCounter

KisLockFreeLodCounter KisUpdaterContext::m_lodCounter

protected

Definition at line 166 of file kis_updater_context.h.

m_numRunningThreads

int KisUpdaterContext::m_numRunningThreads = 0

protected

Definition at line 162 of file kis_updater_context.h.

m_runningThreadsMutex

QMutex KisUpdaterContext::m_runningThreadsMutex

mutableprotected

Definition at line 161 of file kis_updater_context.h.

m_scheduler

KisUpdateScheduler* KisUpdaterContext::m_scheduler

protected

Definition at line 167 of file kis_updater_context.h.

m_testingMode

bool KisUpdaterContext::m_testingMode = false

protected

Definition at line 168 of file kis_updater_context.h.

m_threadPool

QThreadPool KisUpdaterContext::m_threadPool

protected

Definition at line 165 of file kis_updater_context.h.

m_waitForDoneCondition

QWaitCondition KisUpdaterContext::m_waitForDoneCondition

protected

Definition at line 163 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