ThreadWeaver

queueinterface.h
1 /* -*- C++ -*-
2  This file declares the QueueInterface class.
3 
4  SPDX-FileCopyrightText: 2005-2013 Mirko Boehm <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef QueueInterface_H
10 #define QueueInterface_H
11 
12 #include <QObject>
13 #include <QVector>
14 
15 #include "jobinterface.h"
16 #include "jobpointer.h"
17 #include "threadweaver_export.h"
18 
19 namespace ThreadWeaver
20 {
21 class Job;
22 class State;
23 class WeaverObserver;
24 
25 /** WeaverInterface provides a common interface for weaver implementations.
26 
27 In most cases, it is sufficient for an application to hold exactly one
28 ThreadWeaver job queue. To execute jobs in a specific order, use job
29 dependencies. To limit the number of jobs of a certain type that can
30 be executed at the same time, use resource restrictions. To handle
31 special requirements of the application when it comes to the order of
32 execution of jobs, implement a special queue policy and apply it to
33 the jobs.
34 
35 Users of the ThreadWeaver API are encouraged to program to this
36 interface, instead of the implementation. This way, implementation
37 changes will not affect user programs.
38 
39 This interface can be used for example to implement adapters and
40 decorators. The member documentation is provided in the Weaver and
41 WeaverImpl classes.
42 */
43 
44 class THREADWEAVER_EXPORT QueueInterface
45 {
46 public:
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 QVector<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
We use a State pattern to handle the system state in ThreadWeaver.
Definition: state.h:55
void suspend()
WeaverInterface provides a common interface for weaver implementations.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 22 2023 04:03:25 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.