ThreadWeaver::Weaver Class Reference

#include <weaver.h>

Inherits ThreadWeaver::QueueAPI.

Signals
void	threadExited (ThreadWeaver::Thread *)
void	threadStarted (ThreadWeaver::Thread *)
void	threadSuspended (ThreadWeaver::Thread *)

Public Member Functions
	Weaver (QObject *parent=nullptr)
	~Weaver () override
int	activeThreadCount ()
JobPointer	applyForWork (Thread *thread, bool wasBusy) override
void	blockThreadUntilJobsAreBeingAssigned (Thread *th)
void	blockThreadUntilJobsAreBeingAssigned_locked (Thread *th)
int	currentNumberOfThreads () const override
int	currentNumberOfThreads_p () const override
void	decActiveThreadCount ()
void	dequeue () override
bool	dequeue (const JobPointer &job) override
void	dequeue_p () override
bool	dequeue_p (JobPointer job) override
void	enqueue (const QList< JobPointer > &jobs) override
void	enqueue_p (const QList< JobPointer > &jobs)
void	finish () override
void	finish_p () override
void	incActiveThreadCount ()
bool	isEmpty () const override
bool	isEmpty_p () const override
bool	isIdle () const override
bool	isIdle_p () const override
int	maximumNumberOfThreads () const override
int	maximumNumberOfThreads_p () const override
int	queueLength () const override
int	queueLength_p () const override
void	requestAbort () override
void	requestAbort_p () override
void	reschedule () override
void	resume () override
void	resume_p () override
void	setMaximumNumberOfThreads (int cap) override
void	setMaximumNumberOfThreads_p (int cap) override
void	setState (StateId)
void	setState_p (StateId)
void	shutDown () override
void	shutDown_p () override
const State *	state () const override
State *	state () override
void	suspend () override
void	suspend_p () override
JobPointer	takeFirstAvailableJobOrSuspendOrWait (Thread *th, bool threadWasBusy, bool suspendIfAllThreadsInactive, bool justReturning)
void	threadEnteredRun (Thread *thread)
void	waitForAvailableJob (Thread *th) override

Protected Member Functions
void	adjustActiveThreadCount (int diff)
void	adjustInventory (int noOfNewJobs)
virtual Thread *	createThread ()

Detailed Description

A Weaver manages worker threads.

It creates an inventory of Thread objects to which it assigns jobs from its queue. It extends the API of Queue, hiding methods that need to be public to implement state handling, but should not be exposed in general.

Definition at line 34 of file weaver.h.

Constructor & Destructor Documentation

Weaver()

Weaver::Weaver ( QObject * parent = nullptr )

explicit

Constructs a Weaver object.

Definition at line 36 of file weaver.cpp.

~Weaver()

Weaver::~Weaver ( )

override

Destructs a Weaver object.

Definition at line 55 of file weaver.cpp.

Member Function Documentation

activeThreadCount()

int Weaver::activeThreadCount

(

)

Returns the number of active threads.

Threads are active if they process a job. Requires that the mutex is being held when called.

Definition at line 482 of file weaver.cpp.

adjustActiveThreadCount()

void Weaver::adjustActiveThreadCount ( int diff )

protected

Adjust active thread count.

This is a helper function for incActiveThreadCount and decActiveThreadCount.

Definition at line 462 of file weaver.cpp.

adjustInventory()

void Weaver::adjustInventory ( int numberOfNewJobs )

protected

Adjust the inventory size.

Requires that the mutex is being held when called.

This method creates threads on demand. Threads in the inventory are not created upon construction of the WeaverImpl object, but when jobs are queued. This avoids costly delays on the application startup time. Threads are created when the inventory size is under inventoryMin and new jobs are queued.

Definition at line 403 of file weaver.cpp.

applyForWork()

JobPointer Weaver::applyForWork ( Thread * th, bool wasBusy )

override

Assign a job to the calling thread.

This is supposed to be called from the Thread objects in the inventory. Do not call this method from your code. Returns 0 if the weaver is shutting down, telling the calling thread to finish and exit. If no jobs are available and shut down is not in progress, the calling thread is suspended until either condition is met.

Parameters

wasBusy

True if the thread is returning from processing a job

Definition at line 573 of file weaver.cpp.

blockThreadUntilJobsAreBeingAssigned()

void Weaver::blockThreadUntilJobsAreBeingAssigned

(

Thread *

th

)

Blocks the calling thread until jobs can be assigned.

Definition at line 585 of file weaver.cpp.

blockThreadUntilJobsAreBeingAssigned_locked()

void Weaver::blockThreadUntilJobsAreBeingAssigned_locked

(

Thread *

th

)

Blocks the calling thread until jobs can be assigned.

The mutex must be held when calling this method.

Definition at line 596 of file weaver.cpp.

createThread()

Thread * Weaver::createThread ( )

protectedvirtual

Factory method to create the threads.

Overload in adapted Weaver implementations.

Definition at line 438 of file weaver.cpp.

currentNumberOfThreads()

int Weaver::currentNumberOfThreads ( ) const

overridevirtual

Returns the current number of threads in the inventory.

Implements ThreadWeaver::QueueInterface.

Definition at line 190 of file weaver.cpp.

currentNumberOfThreads_p()

int Weaver::currentNumberOfThreads_p ( ) const

override

Definition at line 197 of file weaver.cpp.

decActiveThreadCount()

void Weaver::decActiveThreadCount

(

)

brief Decrement the count of active threads.

Definition at line 450 of file weaver.cpp.

dequeue() [1/2]

void Weaver::dequeue ( )

overridevirtual

Remove all queued jobs.

All waiting jobs will be dequeued. The semantics are the same as for dequeue(JobInterface).

See also

dequeue(JobInterface)

Implements ThreadWeaver::QueueInterface.

Definition at line 266 of file weaver.cpp.

dequeue() [2/2]

bool Weaver::dequeue ( const JobPointer & job )

overridevirtual

Remove a job from the queue.

If the job was queued but not started so far, it is removed from the queue.

You can always call dequeue, it will return true if the job was dequeued. However if the job is not in the queue anymore, it is already being executed, it is too late to dequeue, and dequeue will return false. The return value is thread-safe - if true is returned, the job was still waiting, and has been dequeued. If not, the job was not waiting in the queue.

Modifying queued jobs is best done on a suspended queue. Often, for example at the end of an application, it is sufficient to dequeue all jobs (which leaves only the ones mid-air in threads), call finish (that will wait for all the mid air jobs to complete), and then exit. Without dequeue(), all jobs in the queue would be executed during finish().

See also

requestAbort for aborting jobs during execution

Returns

true if the job was waiting and has been dequeued

false if the job was not found waiting in the queue

Implements ThreadWeaver::QueueInterface.

Definition at line 238 of file weaver.cpp.

dequeue_p() [1/2]

void Weaver::dequeue_p ( )

override

Definition at line 273 of file weaver.cpp.

dequeue_p() [2/2]

bool Weaver::dequeue_p ( JobPointer job )

override

Definition at line 245 of file weaver.cpp.

enqueue()

void Weaver::enqueue ( const QList< JobPointer > & jobs )

overridevirtual

Queue a vector of jobs.

It depends on the state if execution of the job will be attempted immediately. In suspended state, jobs can be added to the queue, but the threads remain suspended. In WorkongHard state, an idle thread may immediately execute the job, or it might be queued if all threads are busy.

JobPointer is a shared pointer. This means the object pointed to will be deleted if this object is the last remaining reference to it. Keep a JobPointer to the job to avoid automatic deletion.

Implements ThreadWeaver::QueueInterface.

Definition at line 203 of file weaver.cpp.

enqueue_p()

void Weaver::enqueue_p

(

const QList< JobPointer > &

jobs

)

Definition at line 210 of file weaver.cpp.

finish()

void Weaver::finish ( )

overridevirtual

Finish all queued operations, then return.

This method is used in imperative (not event driven) programs that cannot react on events to have the controlling (main) thread wait wait for the jobs to finish. The call will block the calling thread and return when all queued jobs have been processed.

Warning: This will suspend your thread! Warning: If one of your jobs enters an infinite loop, this will never return!

Implements ThreadWeaver::QueueInterface.

Definition at line 284 of file weaver.cpp.

finish_p()

void Weaver::finish_p ( )

override

Definition at line 291 of file weaver.cpp.

incActiveThreadCount()

void Weaver::incActiveThreadCount

(

)

Increment the count of active threads.

Definition at line 444 of file weaver.cpp.

isEmpty()

bool Weaver::isEmpty ( ) const

overridevirtual

Is the queue empty? The queue is empty if no more jobs are queued.

Implements ThreadWeaver::QueueInterface.

Definition at line 334 of file weaver.cpp.

isEmpty_p()

bool Weaver::isEmpty_p ( ) const

override

Definition at line 341 of file weaver.cpp.

isIdle()

bool Weaver::isIdle ( ) const

overridevirtual

Is the weaver idle? The weaver is idle if no jobs are queued and no jobs are processed by the threads.

Implements ThreadWeaver::QueueInterface.

Definition at line 347 of file weaver.cpp.

isIdle_p()

bool Weaver::isIdle_p ( ) const

override

Definition at line 354 of file weaver.cpp.

maximumNumberOfThreads()

int Weaver::maximumNumberOfThreads ( ) const

overridevirtual

Get the maximum number of threads this Weaver may start.

Implements ThreadWeaver::QueueInterface.

Definition at line 177 of file weaver.cpp.

maximumNumberOfThreads_p()

int Weaver::maximumNumberOfThreads_p ( ) const

override

Definition at line 184 of file weaver.cpp.

queueLength()

int Weaver::queueLength ( ) const

overridevirtual

Returns the number of pending jobs.

This will return the number of queued jobs. Jobs that are currently being executed are not part of the queue. All jobs in the queue are waiting to be executed.

Implements ThreadWeaver::QueueInterface.

Definition at line 360 of file weaver.cpp.

queueLength_p()

int Weaver::queueLength_p ( ) const

override

Definition at line 367 of file weaver.cpp.

requestAbort()

void Weaver::requestAbort ( )

overridevirtual

Request aborts of the currently executed jobs.

It is important to understand that aborts are requested, but cannot be guaranteed, as not all Job classes support it. It is up to the application to decide if and how job aborts are necessary.

Implements ThreadWeaver::QueueInterface.

Definition at line 373 of file weaver.cpp.

requestAbort_p()

void Weaver::requestAbort_p ( )

override

Definition at line 385 of file weaver.cpp.

reschedule()

void Weaver::reschedule ( )

overridevirtual

Reschedule the jobs in the queue.

This method triggers a scheduling attempt to perform jobs. It will schedule enqueued jobs to be executed by idle threads. It should only be necessary to call it if the canRun() status of a job changed spontaneously due to external reasons.

Implements ThreadWeaver::QueueInterface.

Definition at line 380 of file weaver.cpp.

resume()

void Weaver::resume ( )

overridevirtual

Resume job queueing.

See also

suspend

Implements ThreadWeaver::QueueInterface.

Definition at line 322 of file weaver.cpp.

resume_p()

void Weaver::resume_p ( )

override

Definition at line 329 of file weaver.cpp.

setMaximumNumberOfThreads()

void Weaver::setMaximumNumberOfThreads ( int cap )

overridevirtual

Set the maximum number of threads this Weaver object may start.

Implements ThreadWeaver::QueueInterface.

Definition at line 158 of file weaver.cpp.

setMaximumNumberOfThreads_p()

void Weaver::setMaximumNumberOfThreads_p ( int cap )

override

Definition at line 167 of file weaver.cpp.

setState()

void Weaver::setState

(

StateId

id

)

Set the Weaver state.

See also

StateId

WeaverImplState

State

Definition at line 126 of file weaver.cpp.

setState_p()

void Weaver::setState_p

(

StateId

id

)

Definition at line 133 of file weaver.cpp.

shutDown()

void Weaver::shutDown ( )

overridevirtual

Enter Destructed state.

Once this method returns, it is save to delete this object.

Implements ThreadWeaver::QueueInterface.

Definition at line 64 of file weaver.cpp.

shutDown_p()

void Weaver::shutDown_p ( )

override

Definition at line 69 of file weaver.cpp.

state() [1/2]

const State * Weaver::state ( ) const

overridevirtual

Return the state of the weaver object.

Implements ThreadWeaver::QueueInterface.

Definition at line 148 of file weaver.cpp.

state() [2/2]

State * Weaver::state ( )

override

Definition at line 153 of file weaver.cpp.

suspend()

void Weaver::suspend ( )

overridevirtual

Suspend job execution.

When suspending, all threads are allowed to finish the currently assigned job but will not receive a new assignment. When all threads are done processing the assigned job, the signal suspended will() be emitted. If you call suspend() and there are no jobs left to be done, you will immediately receive the suspended() signal.

Implements ThreadWeaver::QueueInterface.

Definition at line 310 of file weaver.cpp.

suspend_p()

void Weaver::suspend_p ( )

override

Definition at line 317 of file weaver.cpp.

takeFirstAvailableJobOrSuspendOrWait()

JobPointer Weaver::takeFirstAvailableJobOrSuspendOrWait	(	Thread *	th,
		bool	threadWasBusy,
		bool	suspendIfInactive,
		bool	justReturning )

Take the first available job out of the queue and return it.

The job will be removed from the queue (therefore, take). Only jobs that have no unresolved dependencies are considered available. If only jobs that depend on other unfinished jobs are in the queue, this method blocks on m_jobAvailable.

This method will enter suspended state if the active thread count is now zero and suspendIfAllThreadsInactive is true. If justReturning is true, do not assign a new job, just process the completed previous one.

Definition at line 505 of file weaver.cpp.

threadEnteredRun()

void Weaver::threadEnteredRun

(

Thread *

thread

)

Called from a new thread when entering the run method.

Definition at line 489 of file weaver.cpp.

threadExited

void ThreadWeaver::Weaver::threadExited ( ThreadWeaver::Thread * )

signal

A thread has exited.

threadStarted

void ThreadWeaver::Weaver::threadStarted ( ThreadWeaver::Thread * )

signal

A Thread has been created.

threadSuspended

void ThreadWeaver::Weaver::threadSuspended ( ThreadWeaver::Thread * )

signal

A thread has been suspended.

waitForAvailableJob()

void Weaver::waitForAvailableJob ( Thread * th )

override

Wait for a job to become available.

Definition at line 579 of file weaver.cpp.

---

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

• weaver.h
• weaver.cpp