4 SPDX-FileCopyrightText: 2004-2013 Mirko Boehm <[email protected]>
18 class QMutex;
19 class QWaitCondition;
33 /** @brief A Job is a simple abstraction of an action that is to be executed in a thread context.
35 * It is essential for the ThreadWeaver library that as a kind of convention, the different creators of Job objects do not touch
38 * Jobs may not be executed twice. Create two different objects to perform two consecutive or parallel runs.
41 * Jobs may declare dependencies. If Job B depends on Job A, B may not be executed before A is finished. To learn about
44 * Job objects do not inherit QObject. To connect to signals when jobs are started or finished, see QObjectDecorator.
51 Job(Private::Job_Private *d);
54 ~Job() override;
59 * Whenever the currently executed job is communicated to the outside world, use the supplied job pointer
62 * job is the Job that the queue is executing. It is not necessarily equal to this. For example, Jobs that are
72 * Returns the previously set executor. The executor can never be unset. If zero is passed in as the new executor, the Job
81 * Jobs will be sorted by their queueing priority when enqueued. A higher queueing priority will place the job in front of all
84 * Note: A higher or lower priority does not influence queue policies. For example, a high-priority job that has an unresolved
85 * dependency will not be executed, which means an available lower-priority job will take precedence.
87 * The default implementation returns zero. Only if this method is overloaded for some job classes, priorities will influence
100 Status status() const override;
103 * The default implementation simply returns true. Overload in derived classes if the derived Job class can fail.
105 * If a job fails (success() returns false), it will *NOT* resolve its dependencies when it finishes. This will make sure that
108 * There is an important gotcha: When a Job object it deleted, it will always resolve its dependencies. If dependent jobs should
109 * not be executed after a failure, it is important to dequeue those before deleting the failed Job. A Sequence may be
116 * Call this method to ask the Job to abort if it is currently executed. Please note that the default implementation of
117 * the method does nothing (!). This is due to the fact that there is no generic method to abort a processing Job. Not even a
118 * default boolean flag makes sense, as Job could, for example, be in an event loop and will need to create an exit event. You
121 * The method is not pure virtual because users are not supposed to be forced to always implement requestAbort(). Also, this
122 * method is supposed to return immediately, not after the abort has completed. It requests the abort, the Job has to act on
130 * The job will be added right after this method finished. The default implementation does nothing. Use this method to, for
133 * Note: When this method is called, the associated Weaver object's thread holds a lock on the weaver's queue. Therefore, it
144 * The job will be removed from the queue right after this method returns. Use this method to dequeue, if necessary,
147 * Note: When this method is called, the associated Weaver object's thread does hold a lock on the weaver's queue.
161 * Queue Policies customize the queueing (running) behaviour of sets of jobs. Examples for queue policies are dependencies
162 * and resource restrictions. Every queue policy object can only be assigned once to a job, multiple assignments will be
164 void assignQueuePolicy(QueuePolicy *) override;
167 void removeQueuePolicy(QueuePolicy *) override;
170 QList<QueuePolicy *> queuePolicies() const override;
173 QMutex *mutex() const override;
187 * The Job will be executed in the specified thread. thread may be zero, indicating that the job is being executed some
188 * other way (for example, synchronously by some other job). self specifies the job as the queue sees it. Whenever publishing
189 * information about the job to the outside world, for example by emitting signals, use self, not this. self is the reference
190 * counted object handled by the queue. Using it as signal parameters will amongst other things prevent thejob from being
198 * job is the Job that the queue is executing. It is not necessarily equal to this. For example, Jobs that are
205 * job is the Job that the queue is executing. It is not necessarily equal to this. For example, Jobs that are
Q_SCRIPTABLE CaptureState status()
void requestAbort() override
Abort the execution of the job.
A Job is a simple abstraction of an action that is to be executed in a thread context.
QueuePolicy is an interface for customizations of the queueing behaviour of jobs.
Thread represents a worker thread in a Queue's inventory.