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.
| 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
-
| weaver | the Weaver object from which the job will be dequeued |
Definition at line 144 of file job.cpp.
| 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
-
| api | the QueueAPI object the job will be queued in |
Definition at line 133 of file job.cpp.
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.
| 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 97 of file job.cpp.
| void ThreadWeaver::Job::requestAbort |
( |
| ) |
|
|
override |
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.
|
|
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 >.
| 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 113 of file job.cpp.
