ThreadWeaver::Job

Search for usage in LXR

ThreadWeaver::Job Class Referenceabstract

#include <job.h>

Inheritance diagram for ThreadWeaver::Job:

Public Member Functions

 Job ()
 
 Job (Private::Job_Private *d)
 
 ~Job () override
 
void aboutToBeDequeued (QueueAPI *api) override
 
void aboutToBeDequeued_locked (QueueAPI *api) override
 
void aboutToBeQueued (QueueAPI *api) override
 
void aboutToBeQueued_locked (QueueAPI *api) override
 
void assignQueuePolicy (QueuePolicy *) override
 
void blockingExecute () override
 
void execute (const JobPointer &job, Thread *) override
 
Executor * executor () const override
 
bool isFinished () const override
 
QMutexmutex () const override
 
int priority () const override
 
QList< QueuePolicy * > queuePolicies () const override
 
void removeQueuePolicy (QueuePolicy *) override
 
void requestAbort () override
 
Executor * setExecutor (Executor *executor) override
 
void setStatus (Status) override
 
Status status () const override
 
bool success () const override
 

Protected Member Functions

Private::Job_Private * d ()
 
const Private::Job_Private * d () const
 
void defaultBegin (const JobPointer &job, Thread *thread) override
 
void defaultEnd (const JobPointer &job, Thread *thread) override
 
virtual void run (JobPointer self, Thread *thread) override=0
 

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.

Definition at line 46 of file job.h.

Constructor & Destructor Documentation

◆ Job()

ThreadWeaver::Job::Job ( )

Construct a Job.

Definition at line 30 of file job.cpp.

◆ ~Job()

ThreadWeaver::Job::~Job ( )
override

Destructor.

Definition at line 48 of file job.cpp.

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

Definition at line 139 of file job.cpp.

◆ aboutToBeDequeued_locked()

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

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

Definition at line 146 of file job.cpp.

◆ 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

Definition at line 128 of file job.cpp.

◆ aboutToBeQueued_locked()

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

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

Definition at line 135 of file job.cpp.

◆ assignQueuePolicy()

void ThreadWeaver::Job::assignQueuePolicy ( QueuePolicy policy)
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.

Definition at line 150 of file job.cpp.

◆ blockingExecute()

void ThreadWeaver::Job::blockingExecute ( )
override

Perform the job synchronously in the current thread.

Definition at line 83 of file job.cpp.

◆ 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.

Definition at line 119 of file job.cpp.

◆ 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.

Definition at line 123 of file job.cpp.

◆ execute()

void ThreadWeaver::Job::execute ( const JobPointer job,
Thread th 
)
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.

Definition at line 56 of file job.cpp.

◆ executor()

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

Returns the executor currently set on the Job.

Definition at line 93 of file job.cpp.

◆ isFinished()

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

Returns true if the jobs's execute method finished.

Definition at line 183 of file job.cpp.

◆ mutex()

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

The mutex used to protect this job.

Definition at line 189 of file job.cpp.

◆ 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.

Definition at line 98 of file job.cpp.

◆ queuePolicies()

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

Return the queue policies assigned to this Job.

Definition at line 167 of file job.cpp.

◆ removeQueuePolicy()

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

Remove a queue policy from this job.

Definition at line 158 of file job.cpp.

◆ 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.

Definition at line 124 of file job.h.

◆ 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::Lambda< T >, and ThreadWeaver::Collection.

◆ 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().

Definition at line 88 of file job.cpp.

◆ setStatus()

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

Set the status of the Job.

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

Definition at line 103 of file job.cpp.

◆ status()

JobInterface::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.

Definition at line 108 of file job.cpp.

◆ 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.

Definition at line 114 of file job.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Dec 4 2022 04:06:48 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.