1/* -*- C++ -*-
2 This file declares the QueueInterface class.
3
4 SPDX-FileCopyrightText: 2005-2013 Mirko Boehm <mirko@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef QueueInterface_H
10#define QueueInterface_H
11
12#include <QList>
13#include <QObject>
14
15#include "jobinterface.h"
16#include "jobpointer.h"
17#include "threadweaver_export.h"
18
19namespace ThreadWeaver
20{
21class Job;
22class State;
23class WeaverObserver;
24
25/** WeaverInterface provides a common interface for weaver implementations.
26
27In most cases, it is sufficient for an application to hold exactly one
28ThreadWeaver job queue. To execute jobs in a specific order, use job
29dependencies. To limit the number of jobs of a certain type that can
30be executed at the same time, use resource restrictions. To handle
31special requirements of the application when it comes to the order of
32execution of jobs, implement a special queue policy and apply it to
33the jobs.
34
35Users of the ThreadWeaver API are encouraged to program to this
36interface, instead of the implementation. This way, implementation
37changes will not affect user programs.
38
39This interface can be used for example to implement adapters and
40decorators. The member documentation is provided in the Weaver and
41WeaverImpl classes.
42*/
43
44class THREADWEAVER_EXPORT QueueInterface
45{
46public:
47 virtual ~QueueInterface()
48 {
49 }
50 /** Return the state of the weaver object. */
51 virtual const State *state() const = 0;
52
53 /** Shut down the queue.
54 * Tells all threads to exit, and changes to Destructed state.
55 * It is safe to destroy the queue once this method returns.
56 */
57 virtual void shutDown() = 0;
58
59 /** Set the maximum number of threads this Weaver object may start. */
60 virtual void setMaximumNumberOfThreads(int cap) = 0;
61
62 /** Get the maximum number of threads this Weaver may start. */
63 virtual int maximumNumberOfThreads() const = 0;
64
65 /** Returns the current number of threads in the inventory. */
66 virtual int currentNumberOfThreads() const = 0;
67
68 /** Queue a vector of jobs.
69
70 It depends on the state if execution of the job will be attempted
71 immediately. In suspended state, jobs can be added to the queue,
72 but the threads remain suspended. In WorkongHard state, an idle
73 thread may immediately execute the job, or it might be queued if
74 all threads are busy.
75
76 JobPointer is a shared pointer. This means the object pointed to will be deleted if this object
77 is the last remaining reference to it. Keep a JobPointer to the job to avoid automatic deletion.
78 */
79 virtual void enqueue(const QList<JobPointer> &jobs) = 0;
80
81 /** Remove a job from the queue.
82 *
83 * If the job was queued but not started so far, it is removed from the queue.
84 *
85 * You can always call dequeue, it will return true if the job was dequeued. However if the job is not in the queue anymore,
86 * it is already being executed, it is too late to dequeue, and dequeue will return false. The return value is thread-safe - if
87 * true is returned, the job was still waiting, and has been dequeued. If not, the job was not waiting in the queue.
88 *
89 * Modifying queued jobs is best done on a suspended queue. Often, for example at the end of an application, it is sufficient
90 * to dequeue all jobs (which leaves only the ones mid-air in threads), call finish (that will wait for all the mid air jobs to
91 * complete), and then exit. Without dequeue(), all jobs in the queue would be executed during finish().
92 * @see requestAbort for aborting jobs during execution
93 * @return true if the job was waiting and has been dequeued
94 * @return false if the job was not found waiting in the queue
95 */
96 virtual bool dequeue(const JobPointer &job) = 0;
97
98 /** Remove all queued jobs.
99 *
100 * All waiting jobs will be dequeued. The semantics are the same as for dequeue(JobInterface).
101 *
102 * @see dequeue(JobInterface)
103 */
104 virtual void dequeue() = 0;
105 /** Finish all queued operations, then return.
106
107 This method is used in imperative (not event driven) programs that
108 cannot react on events to have the controlling (main) thread wait
109 wait for the jobs to finish. The call will block the calling
110 thread and return when all queued jobs have been processed.
111
112 Warning: This will suspend your thread!
113 Warning: If one of your jobs enters an infinite loop, this
114 will never return! */
115 virtual void finish() = 0;
116 /** Suspend job execution.
117 When suspending, all threads are allowed to finish the
118 currently assigned job but will not receive a new
119 assignment.
120 When all threads are done processing the assigned job, the
121 signal suspended will() be emitted.
122 If you call suspend() and there are no jobs left to
123 be done, you will immediately receive the suspended()
124 signal. */
125 virtual void suspend() = 0;
126 /** Resume job queueing.
127 @see suspend
128 */
129 virtual void resume() = 0;
130 /** Is the queue empty?
131 The queue is empty if no more jobs are queued. */
132 virtual bool isEmpty() const = 0;
133 /** Is the weaver idle?
134 The weaver is idle if no jobs are queued and no jobs are processed
135 by the threads. */
136 virtual bool isIdle() const = 0;
137 /** Returns the number of pending jobs.
138 This will return the number of queued jobs. Jobs that are
139 currently being executed are not part of the queue. All jobs in
140 the queue are waiting to be executed.
141 */
142 virtual int queueLength() const = 0;
143
144 /** Request aborts of the currently executed jobs.
145 It is important to understand that aborts are requested, but
146 cannot be guaranteed, as not all Job classes support it. It is up
147 to the application to decide if and how job aborts are
148 necessary. */
149 virtual void requestAbort() = 0;
150
151 /** @brief Reschedule the jobs in the queue.
152 * This method triggers a scheduling attempt to perform jobs. It will schedule enqueued jobs to be executed by idle threads.
153 * It should only be necessary to call it if the canRun() status of a job changed spontaneously due to external reasons. */
154 virtual void reschedule() = 0;
155};
156
157}
158
159#endif
160

source code of threadweaver/src/queueinterface.h