ThreadWeaver 5.109.0
Public Member Functions | Protected Member Functions | List of all members
ThreadWeaver::Jobabstract

A Job is a simple abstraction of an action that is to be executed in a thread context. More...

#include <job.h>

Public Member Functions

 Job ()
 Construct a Job.
 
 Job (Private::Job_Private *d)
 
 ~Job () override
 Destructor.
 
void aboutToBeDequeued (QueueAPI *api) override
 This Job is about the be dequeued from the weaver's job queue.
 
void aboutToBeDequeued_locked (QueueAPI *api) override
 Called from aboutToBeDequeued() while the mutex is being held.
 
void aboutToBeQueued (QueueAPI *api) override
 The job is about to be added to the weaver's job queue.
 
void aboutToBeQueued_locked (QueueAPI *api) override
 Called from aboutToBeQueued() while the mutex is being held.
 
void assignQueuePolicy (QueuePolicy *) override
 Assign a queue policy.
 
void blockingExecute () override
 Perform the job synchronously in the current thread.
 
void execute (const JobPointer &job, Thread *) override
 Perform the job.
 
Executor * executor () const override
 Returns the executor currently set on the Job.
 
bool isFinished () const override
 Returns true if the jobs's execute method finished.
 
QMutex * mutex () const override
 The mutex used to protect this job.
 
int priority () const override
 The queueing priority of the job.
 
QList< QueuePolicy * > queuePolicies () const override
 Return the queue policies assigned to this Job.
 
void removeQueuePolicy (QueuePolicy *) override
 Remove a queue policy from this job.
 
void requestAbort () override
 Abort the execution of the job.
 
Executor * setExecutor (Executor *executor) override
 Set the Executor object that is supposed to run the job.
 
void setStatus (Status) override
 Set the status of the Job.
 
Status status () const override
 The status of the job.
 
bool success () const override
 Return whether the Job finished successfully or not.
 

Protected Member Functions

Private::Job_Private * d ()
 
const Private::Job_Private * d () const
 
void defaultBegin (const JobPointer &job, Thread *thread) override
 Perform standard tasks before starting the execution of a job.
 
void defaultEnd (const JobPointer &job, Thread *thread) override
 Perform standard task after the execution of a job.
 
virtual void run (JobPointer self, Thread *thread) override=0
 The method that actually performs the job.
 

Detailed Description

A Job is a simple abstraction of an action that is to be executed in a thread context.

It is essential for the ThreadWeaver library that as a kind of convention, the different creators of Job objects do not touch the protected data members of the Job until somehow notified by the Job.

Jobs may not be executed twice. Create two different objects to perform two consecutive or parallel runs. (Note: this rule is being reconsidered.)

Jobs may declare dependencies. If Job B depends on Job A, B may not be executed before A is finished. To learn about dependencies, see DependencyPolicy.

Job objects do not inherit QObject. To connect to signals when jobs are started or finished, see QObjectDecorator.

Constructor & Destructor Documentation

◆ Job()

ThreadWeaver::Job::Job ( )

Construct a Job.

◆ ~Job()

ThreadWeaver::Job::~Job ( )
override

Destructor.

Member Function Documentation

◆ aboutToBeDequeued()

void ThreadWeaver::Job::aboutToBeDequeued ( QueueAPI *  api)
override

This Job is about the be dequeued from the weaver's job queue.

The job will be removed from the queue right after this method returns. Use this method to dequeue, if necessary, sub-operations (jobs) that this job has enqueued.

Note: When this method is called, the associated Weaver object's thread does hold a lock on the weaver's queue. Note: The default implementation does nothing.

Parameters
weaverthe Weaver object from which the job will be dequeued

◆ aboutToBeDequeued_locked()

void ThreadWeaver::Job::aboutToBeDequeued_locked ( QueueAPI *  api)
override

Called from aboutToBeDequeued() while the mutex is being held.

◆ aboutToBeQueued()

void ThreadWeaver::Job::aboutToBeQueued ( QueueAPI *  api)
override

The job is about to be added to the weaver's job queue.

The job will be added right after this method finished. The default implementation does nothing. Use this method to, for example, queue sub-operations as jobs before the job itself is queued.

Note: When this method is called, the associated Weaver object's thread holds a lock on the weaver's queue. Therefore, it is save to assume that recursive queueing is atomic from the queues perspective.

Parameters
apithe QueueAPI object the job will be queued in

◆ aboutToBeQueued_locked()

void ThreadWeaver::Job::aboutToBeQueued_locked ( QueueAPI *  api)
override

Called from aboutToBeQueued() while the mutex is being held.

◆ assignQueuePolicy()

void ThreadWeaver::Job::assignQueuePolicy ( QueuePolicy )
override

Assign a queue policy.

Queue Policies customize the queueing (running) behaviour of sets of jobs. Examples for queue policies are dependencies and resource restrictions. Every queue policy object can only be assigned once to a job, multiple assignments will be IGNORED.

◆ blockingExecute()

void ThreadWeaver::Job::blockingExecute ( )
override

Perform the job synchronously in the current thread.

◆ defaultBegin()

void ThreadWeaver::Job::defaultBegin ( const JobPointer &  job,
Thread thread 
)
overrideprotected

Perform standard tasks before starting the execution of a job.

The default implementation is empty. job is the Job that the queue is executing. It is not necessarily equal to this. For example, Jobs that are decorated expose the decorator's address, not the address of the decorated object.

◆ defaultEnd()

void ThreadWeaver::Job::defaultEnd ( const JobPointer &  job,
Thread thread 
)
overrideprotected

Perform standard task after the execution of a job.

The default implementation is empty. job is the Job that the queue is executing. It is not necessarily equal to this. For example, Jobs that are decorated expose the decorator's address, not the address of the decorated object.

◆ execute()

void ThreadWeaver::Job::execute ( const JobPointer &  job,
Thread  
)
override

Perform the job.

The thread in which this job is executed is given as a parameter.

Do not overload this method to create your own Job implementation, overload run(). Whenever the currently executed job is communicated to the outside world, use the supplied job pointer to keep the reference count correct.

job is the Job that the queue is executing. It is not necessarily equal to this. For example, Jobs that are decorated expose the decorator's address, not the address of the decorated object.

◆ executor()

Executor * ThreadWeaver::Job::executor ( ) const
override

Returns the executor currently set on the Job.

◆ isFinished()

bool ThreadWeaver::Job::isFinished ( ) const
override

Returns true if the jobs's execute method finished.

◆ mutex()

QMutex * ThreadWeaver::Job::mutex ( ) const
override

The mutex used to protect this job.

◆ priority()

int ThreadWeaver::Job::priority ( ) const
override

The queueing priority of the job.

Jobs will be sorted by their queueing priority when enqueued. A higher queueing priority will place the job in front of all lower-priority jobs in the queue.

Note: A higher or lower priority does not influence queue policies. For example, a high-priority job that has an unresolved dependency will not be executed, which means an available lower-priority job will take precedence.

The default implementation returns zero. Only if this method is overloaded for some job classes, priorities will influence the execution order of jobs.

◆ queuePolicies()

QList< QueuePolicy * > ThreadWeaver::Job::queuePolicies ( ) const
override

Return the queue policies assigned to this Job.

◆ removeQueuePolicy()

void ThreadWeaver::Job::removeQueuePolicy ( QueuePolicy )
override

Remove a queue policy from this job.

◆ requestAbort()

void ThreadWeaver::Job::requestAbort ( )
inlineoverride

Abort the execution of the job.

Call this method to ask the Job to abort if it is currently executed. Please note that the default implementation of the method does nothing (!). This is due to the fact that there is no generic method to abort a processing Job. Not even a default boolean flag makes sense, as Job could, for example, be in an event loop and will need to create an exit event. You have to reimplement the method to actually initiate an abort action.

The method is not pure virtual because users are not supposed to be forced to always implement requestAbort(). Also, this method is supposed to return immediately, not after the abort has completed. It requests the abort, the Job has to act on the request.

◆ run()

virtual void ThreadWeaver::Job::run ( JobPointer  self,
Thread thread 
)
overrideprotectedpure virtual

The method that actually performs the job.

It is called from execute(). This method is the one to overload it with the job's task.

The Job will be executed in the specified thread. thread may be zero, indicating that the job is being executed some other way (for example, synchronously by some other job). self specifies the job as the queue sees it. Whenever publishing information about the job to the outside world, for example by emitting signals, use self, not this. self is the reference counted object handled by the queue. Using it as signal parameters will amongst other things prevent thejob from being memory managed and deleted.

Implemented in ThreadWeaver::Collection, and ThreadWeaver::Lambda< T >.

◆ setExecutor()

Executor * ThreadWeaver::Job::setExecutor ( Executor *  executor)
override

Set the Executor object that is supposed to run the job.

Returns the previously set executor. The executor can never be unset. If zero is passed in as the new executor, the Job will internally reset to a default executor that only invokes run().

◆ setStatus()

void ThreadWeaver::Job::setStatus ( Status  )
override

Set the status of the Job.

Do not call this method unless you know what you are doing, please :-)

◆ status()

Status ThreadWeaver::Job::status ( ) const
override

The status of the job.

The status will be changed to Status_Success if the run() method exits normally.

◆ success()

bool ThreadWeaver::Job::success ( ) const
override

Return whether the Job finished successfully or not.

The default implementation simply returns true. Overload in derived classes if the derived Job class can fail.

If a job fails (success() returns false), it will NOT resolve its dependencies when it finishes. This will make sure that Jobs that depend on the failed job will not be started.

There is an important gotcha: When a Job object it deleted, it will always resolve its dependencies. If dependent jobs should not be executed after a failure, it is important to dequeue those before deleting the failed Job. A Sequence may be helpful for that purpose.