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

source code of threadweaver/src/queueinterface.h