File: job.h

package info (click to toggle)
bluez-qt 5.62.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 1,708 kB
  • sloc: cpp: 14,071; xml: 424; ansic: 318; sh: 22; makefile: 9
file content (245 lines) | stat: -rw-r--r-- 7,341 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
/*
 * BluezQt - Asynchronous BlueZ wrapper library
 *
 * Copyright (C) 2014 Alejandro Fiestas Olivares <afiestas@kde.org>
 *               2014-2015 David Rosca <nowrep@gmail.com>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) version 3, or any
 * later version accepted by the membership of KDE e.V. (or its
 * successor approved by the membership of KDE e.V.), which shall
 * act as a proxy defined in Section 6 of version 3 of the license.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef BLUEZQT_JOB_H
#define BLUEZQT_JOB_H

#include <QObject>

#include "bluezqt_export.h"

namespace BluezQt
{

class JobPrivate;

/**
 * @class BluezQt::Job job.h <BluezQt/Job>
 *
 * This class represents an asynchronous job performed by BluezQt,
 * it is usually not used directly but instead it is inherit by some
 * other class.
 *
 * There are two ways of using this class, one is via exec() which will block
 * the thread until a result is fetched, the other is via connecting to the
 * signal result()
 *
 * Please, think twice before using exec(), it should be used only in either
 * unittest or cli apps.
 *
 * @note Job and its subclasses are meant to be used in a fire-and-forget way.
 * Jobs will delete themselves when they finish using deleteLater().
 *
 * @note Even given their asynchronous nature, Jobs are still executed in the
 * main thread, so any blocking code executed in it will block the app calling it.
 *
 * @see InitManagerJob
 * @see InitObexManagerJob
 */
class BLUEZQT_EXPORT Job : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int error READ error)
    Q_PROPERTY(QString errorText READ errorText)
    Q_PROPERTY(bool running READ isRunning)
    Q_PROPERTY(bool finished READ isFinished)

public:
    /**
     * Creates a new Job object.
     *
     * @param parent
     */
    explicit Job(QObject *parent = nullptr);

    /**
     * Destroys a Job object.
     */
    ~Job();

    /**
     * Error type
     *
     * @see error() const
     */
    enum Error {
        /** Indicates there is no error */
        NoError = 0,
        /** Subclasses should define error codes starting at this value */
        UserDefinedError = 100
    };
    Q_ENUM(Error)

    /**
     * Executes the job synchronously.
     *
     * This will start a nested QEventLoop internally. Nested event loop can be dangerous and
     * can have unintended side effects, you should avoid calling exec() whenever you can and use the
     * asynchronous interface of Job instead.
     *
     * Should you indeed call this method, you need to make sure that all callers are reentrant,
     * so that events delivered by the inner event loop don't cause non-reentrant functions to be
     * called, which usually wreaks havoc.
     *
     * Note that the event loop started by this method does not process user input events, which means
     * your user interface will effectivly be blocked. Other events like paint or network events are
     * still being processed. The advantage of not processing user input events is that the chance of
     * accidental reentrancy is greatly reduced. Still you should avoid calling this function.
     *
     * @warning This method blocks until the job finishes!
     *
     * @return true if the job has been executed without error, false otherwise
     */
    bool exec();

    /**
     * Returns the error code, if there has been an error.
     *
     * Make sure to call this once result() has been emitted
     *
     * @return the error code for this job, 0 if no error.
     */
    int error() const;

    /**
     * Returns the error text if there has been an error.
     *
     * Only call if error is not 0.
     *
     * This is usually some extra data associated with the error,
     * such as a URL.  Use errorString() to get a human-readable,
     * translated message.
     *
     * @return a string to help understand the error
     */
    QString errorText() const;

    /**
     * Returns whether the job is currently running
     *
     * @return true if the job is running
     */
    bool isRunning() const;

    /**
     * Returns whether the job have already finished
     *
     * @return true if the job already finished
     */
    bool isFinished() const;

public Q_SLOTS:
    /**
     * Starts the job asynchronously.
     *
     * This method will schedule doStart() to be executed in the next
     * loop. This is done so this method returns as soon as possible.
     *
     * When the job is finished, result() is emitted.
     */
    void start();

    /**
     * Kills the job.
     *
     * This method will kill the job and then call deleteLater().
     * Only jobs started with start() can be killed.
     *
     * It will not emit result signal.
     */
    void kill();

protected Q_SLOTS:
    /**
     * Implementation for start() that will be executed in next loop
     *
     * This slot is always called in the next loop, triggered by start().
     *
     * When implementing this method is important to remember that jobs
     * are not executed on a different thread (unless done that way), so any
     * blocking task has to be done in a different thread or process.
     */
    virtual void doStart() = 0;

protected:
    /**
     * Sets the error code.
     *
     * It should be called when an error
     * is encountered in the job, just before calling emitResult().
     *
     * You should define an enum of error codes,
     * with values starting at Job::UserDefinedError, and use
     * those. For example:
     * @code
     * enum ExampleErrors{
     *   InvalidFoo = UserDefinedError,
     *   BarNotFound
     * };
     * @endcode
     *
     * @param errorCode the error code
     * @see emitResult()
     */
    void setError(int errorCode);

    /**
     * Sets the error text.
     *
     * It should be called when an error
     * is encountered in the job, just before calling emitResult().
     *
     * Provides extra information about the error that cannot be
     * determined directly from the error code.  For example, a
     * URL or filename.  This string is not normally translatable.
     *
     * @param errorText the error text
     * @see emitResult(), setError()
     */
    void setErrorText(const QString &errorText);

    /**
     * Utility function to emit the result signal, and suicide this job.
     *
     * @note Deletes this job using deleteLater().
     * @see result() const
     */
    void emitResult();

    /**
     * Implementation for emitting the result signal
     *
     * This function is needed to be able to emit result() signal
     * with the job pointer's type being subclass
     */
    virtual void doEmitResult() = 0;

private:
    JobPrivate *const d_ptr;

    Q_DECLARE_PRIVATE(Job)
};

} // namespace BluezQt

#endif //BLUEZQT_JOB_H