Solid

job.h
1/*
2 SPDX-FileCopyrightText: 2014 Alejandro Fiestas Olivares <afiestas@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6
7#ifndef SOLID_JOB_H
8#define SOLID_JOB_H
9
10#include <QObject>
11
12#include "solid_export.h"
13
14namespace Solid
15{
16class JobPrivate;
17/**
18 * This class represents an asynchronous job performed by Solid,
19 * it is usually not used directly but instead it is inherited by some
20 * other class, for example \See AcPluggedJob or \See StatesJob
21 *
22 * There are two ways of using this class, one is via exec() which will block
23 * the thread until a result is fetched, the other is via connecting to the
24 * signal result()
25 *
26 * Please, think twice before using exec(), it should be used only in either
27 * unittest or cli apps.
28 *
29 * @note Job and its subclasses are meant to be used
30 * in a fire-and-forget way. Jobs will delete themselves
31 * when they finish using deleteLater()
32 *
33 * @note Even given their asynchronous nature, Jobs are still executed in the
34 * main thread, so any blocking code executed in it will block the app calling it.
35 */
36class SOLID_EXPORT Job : public QObject
37{
38 Q_OBJECT
39 Q_PROPERTY(int error READ error NOTIFY result)
40 Q_PROPERTY(QString errorText READ errorText NOTIFY result)
41
42public:
43 explicit Job(QObject *parent = nullptr);
44 virtual ~Job();
45
46 enum Error {
47 /** Indicates there is no error */
48 NoError = 0,
49 /** Subclasses should define error codes starting at this value */
50 UserDefinedError = 100,
51 };
52 Q_ENUM(Error)
53
54 /**
55 * Executes the job synchronously.
56 *
57 * This will start a nested QEventLoop internally. Nested event loop can be dangerous and
58 * can have unintended side effects, you should avoid calling exec() whenever you can and use the
59 * asynchronous interface of SolidJob instead.
60 *
61 * Should you indeed call this method, you need to make sure that all callers are reentrant,
62 * so that events delivered by the inner event loop don't cause non-reentrant functions to be
63 * called, which usually wreaks havoc.
64 *
65 * Note that the event loop started by this method does not process user input events, which means
66 * your user interface will effectively be blocked. Other events like paint or network events are
67 * still being processed. The advantage of not processing user input events is that the chance of
68 * accidental reentrancy is greatly reduced. Still you should avoid calling this function.
69 *
70 * @return true if the job has been executed without error, false otherwise
71 */
72 bool exec();
73
74 /**
75 * Returns the error code, if there has been an error.
76 *
77 * Make sure to call this once result() has been emitted
78 *
79 * @return the error code for this job, 0 if no error.
80 */
81 int error() const;
82
83 /**
84 * Returns the error text if there has been an error.
85 *
86 * Only call if error is not 0.
87 *
88 * This is usually some extra data associated with the error,
89 * such as a URL. Use errorString() to get a human-readable,
90 * translated message.
91 *
92 * @return a string to help understand the error
93 */
94 QString errorText() const;
95
96public Q_SLOTS:
97 /**
98 * Starts the job asynchronously.
99 *
100 * This method will schedule doStart() to be executed in the next
101 * loop. This is done so this method returns as soon as possible.
102 *
103 * When the job is finished, result() is emitted.
104 */
105 void start();
106
107private Q_SLOTS:
108 /**
109 * Implementation fo start() that will be executed in next loop
110 *
111 * This slot is always called in the next loop, triggered by start().
112 *
113 * When implementing this method it is important to remember that jobs
114 * are not executed on a different thread (unless done that way), so any
115 * blocking task has to be done in a different thread or process.
116 */
117 virtual void doStart() = 0;
118
119protected:
120 /**
121 * Sets the error code.
122 *
123 * It should be called when an error
124 * is encountered in the job, just before calling emitResult().
125 *
126 * You should define an enum of error codes,
127 * with values starting at KJob::UserDefinedError, and use
128 * those. For example,
129 * @code
130 * enum ExampleErrors{
131 * InvalidFoo = UserDefinedError,
132 * BarNotFound
133 * };
134 * @endcode
135 *
136 * @param errorCode the error code
137 * @see emitResult()
138 */
139 void setError(int errorCode);
140
141 /**
142 * Sets the error text.
143 *
144 * It should be called when an error
145 * is encountered in the job, just before calling emitResult().
146 *
147 * Provides extra information about the error that cannot be
148 * determined directly from the error code. For example, a
149 * URL or filename. This string is not normally translatable.
150 *
151 * @param errorText the error text
152 * @see emitResult(), setError()
153 */
154 void setErrorText(const QString &errorText);
155
156 /**
157 * Utility function to emit the result signal, and suicide this job.
158 * @note Deletes this job using deleteLater().
159 * @see result()
160 */
161 void emitResult();
162
163 JobPrivate *const d_ptr;
164 SOLID_NO_EXPORT Job(JobPrivate &dd, QObject *parent);
165
166private:
167 Q_DECLARE_PRIVATE(Job)
168
169Q_SIGNALS:
170 void result(Solid::Job *job);
171};
172}
173
174#endif // SOLID_JOB_H
This class represents an asynchronous job performed by Solid, it is usually not used directly but ins...
Definition job.h:37
Q_SCRIPTABLE Q_NOREPLY void start()
The single responsibility of this class is to create arguments valid for logind Inhibit call.
Definition fakebattery.h:16
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:08:14 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.