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
void onFinish (const std::function< void(const JobInterface &job)> &lambda)
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
bool shouldAbort () const
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() [1/2]

ThreadWeaver::Job::Job ( )

Construct a Job.

Definition at line 30 of file job.cpp.

◆ Job() [2/2]

ThreadWeaver::Job::Job ( Private::Job_Private * d)

Definition at line 39 of file job.cpp.

◆ ~Job()

ThreadWeaver::Job::~Job ( )


Definition at line 48 of file job.cpp.

Member Function Documentation

◆ aboutToBeDequeued()

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

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.

weaverthe Weaver object from which the job will be dequeued

Definition at line 144 of file job.cpp.

◆ aboutToBeDequeued_locked()

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

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

Definition at line 151 of file job.cpp.

◆ aboutToBeQueued()

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

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.

apithe QueueAPI object the job will be queued in

Definition at line 133 of file job.cpp.

◆ aboutToBeQueued_locked()

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

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

Definition at line 140 of file job.cpp.

◆ assignQueuePolicy()

void ThreadWeaver::Job::assignQueuePolicy ( QueuePolicy * policy)

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 155 of file job.cpp.

◆ blockingExecute()

void ThreadWeaver::Job::blockingExecute ( )

Perform the job synchronously in the current thread.

Definition at line 82 of file job.cpp.

◆ d() [1/2]

Private::Job_Private * ThreadWeaver::Job::d ( )

Definition at line 178 of file job.cpp.

◆ d() [2/2]

const Private::Job_Private * ThreadWeaver::Job::d ( ) const

Definition at line 183 of file job.cpp.

◆ defaultBegin()

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

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 123 of file job.cpp.

◆ defaultEnd()

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

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 127 of file job.cpp.

◆ execute()

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

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

Returns the executor currently set on the Job.

Definition at line 92 of file job.cpp.

◆ isFinished()

bool ThreadWeaver::Job::isFinished ( ) const

Returns true if the jobs's execute method finished.

Definition at line 188 of file job.cpp.

◆ mutex()

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

The mutex used to protect this job.

Definition at line 194 of file job.cpp.

◆ onFinish()

void ThreadWeaver::Job::onFinish ( const std::function< void(const JobInterface &job)> & lambda)

Add handler that will be invoked once job has finished.


Definition at line 204 of file job.cpp.

◆ priority()

int ThreadWeaver::Job::priority ( ) const

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 97 of file job.cpp.

◆ queuePolicies()

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

Return the queue policies assigned to this Job.

Definition at line 172 of file job.cpp.

◆ removeQueuePolicy()

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

Remove a queue policy from this job.

Definition at line 163 of file job.cpp.

◆ requestAbort()

void ThreadWeaver::Job::requestAbort ( )

Abort the execution of the job.

Call this method to ask the Job to abort if it is currently executed. Default implementation of the method sets a flag causing shouldAbort() return true. You can reimplement this method to actually initiate an abort action.

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 118 of file job.cpp.

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

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 87 of file job.cpp.

◆ setStatus()

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

Set the status of the Job.

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

Definition at line 102 of file job.cpp.

◆ shouldAbort()

bool ThreadWeaver::Job::shouldAbort ( ) const

Whether Job should abort itself.

It will return true if requestAbort() was invoked before but it's up to the job implementation itself to honor it and some implementations might not actually abort (ie. unabortable job).


Definition at line 199 of file job.cpp.

◆ status()

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

The status of the job.

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

Definition at line 107 of file job.cpp.

◆ success()

bool ThreadWeaver::Job::success ( ) const

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 113 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-2024 The KDE developers.
Generated on Fri Jun 14 2024 12:00:23 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.