KCGroups

kapplicationscope.h
1 // SPDX-FileCopyrightText: 2020 Henri Chain <[email protected]>
2 // SPDX-FileCopyrightText: 2020 Kevin Ottens <[email protected]>
3 //
4 // SPDX-License-Identifier: LGPL-2.1-or-later
5 
6 #ifndef KAPPLICATIONSCOPE_H
7 #define KAPPLICATIONSCOPE_H
8 #include "kcgroups_export.h"
9 #include "optionalgadget.h"
10 #include <QObject>
11 
12 class KApplicationScopePrivate;
13 
14 OPTIONAL_GADGET(qulonglong, OptionalQULongLong);
15 
16 /**
17  * @brief A desktop application in a systemd transient scope
18  */
19 class KCGROUPS_EXPORT KApplicationScope : public QObject
20 {
21  Q_OBJECT
22 
23  /**
24  * @brief the dbus path of the application. Same as constructor parameter. Read-only, constant
25  * @accessors path()
26  */
27  Q_PROPERTY(QString path READ path CONSTANT)
28 
29  /**
30  * @brief the systemd unit id. Read-only. Will be set asynchronously if not specified in constructor.
31  * @accessors id()
32  * @notifySignal idChanged()
33  */
34  Q_PROPERTY(QString id READ id NOTIFY idChanged)
35 
36  /**
37  * @brief file path of the control group in /sys/fs/cgroup
38  * @accessors cgroup()
39  * @notifySignal cgroupChanged()
40  */
41  Q_PROPERTY(QString cgroup READ cgroup NOTIFY cgroupChanged)
42 
43  /**
44  * @brief the systemd unit description. Read-only.
45  * @accessors description()
46  * @notifySignal descriptionChanged()
47  */
48  Q_PROPERTY(QString description READ description NOTIFY descriptionChanged)
49 
50  /**
51  * @brief the .desktop application name. Read-only.
52  * @accessors desktopName()
53  * @notifySignal desktopNameChanged()
54  */
55  Q_PROPERTY(QString desktopName READ desktopName NOTIFY desktopNameChanged)
56 
57  /**
58  * @brief the application .desktop file if available. Read-only.
59  * @accessors desktopFilePath()
60  * @notifySignal desktopFilePathChanged()
61  */
62  Q_PROPERTY(QString desktopFilePath READ desktopFilePath NOTIFY desktopFilePathChanged)
63 
64  /**
65  * @brief the app instance random identifier. Can be empty if this is a singleton application.
66  * @accessors instance()
67  * @notifySignal instanceChanged()
68  */
69  Q_PROPERTY(QString instance READ instance NOTIFY instanceChanged)
70 
71  /**
72  * @brief code of the last error that occurred (NoError if none)
73  * @accessors lastError()
74  * @notifySignal errorOccurred()
75  */
76  Q_PROPERTY(ErrorCode lastError READ lastError NOTIFY errorOccurred)
77 
78  /**
79  * @brief cpu quota for cpu controller, in microseconds per second (1000000 means 100%). Can be unset
80  * @accessors cpuQuota(), setCpuQuota()
81  * @notifySignal cpuQuotaChanged()
82  */
83  Q_PROPERTY(OptionalQULongLong cpuQuota READ cpuQuota WRITE setCpuQuota NOTIFY cpuQuotaChanged)
84 
85  /**
86  * @brief duration in micoseconds over which the CPU time quota is measured. (default when unset is 100ms)
87  * @accessors cpuQuotaPeriod(), setCpuQuotaPeriod()
88  * @notifySignal cpuQuotaPeriodChanged()
89  */
90  Q_PROPERTY(OptionalQULongLong cpuQuotaPeriod READ cpuQuotaPeriod WRITE setCpuQuotaPeriod NOTIFY cpuQuotaPeriodChanged)
91 
92  /**
93  * @brief cpu time weight. Between 1 and 10000. Defaults to 100.
94  * @accessors cpuQuotaPeriod(), setCpuQuotaPeriod()
95  * @notifySignal cpuQuotaPeriodChanged()
96  */
97  Q_PROPERTY(OptionalQULongLong cpuWeight READ cpuWeight WRITE setCpuWeight NOTIFY cpuWeightChanged)
98 
99  /**
100  * @brief Overall block I/O weight. Between 1 and 10000. Defaults to 100.
101  * @accessors ioWeight(), setIoWeight()
102  * @notifySignal ioWeightChanged()
103  */
104  Q_PROPERTY(OptionalQULongLong ioWeight READ ioWeight WRITE setIoWeight NOTIFY ioWeightChanged)
105 
106  /**
107  * @brief best-effort memory usage protection (in bytes) of all executed processes within the application.
108  * @accessors memoryLow(), setMemoryLow()
109  * @notifySignal memoryLowChanged()
110  */
111  Q_PROPERTY(OptionalQULongLong memoryLow READ memoryLow WRITE setMemoryLow NOTIFY memoryLowChanged)
112 
113  /**
114  * @brief throttling limit on memory usage (in bytes) of all executed processes within the application.
115  * @accessors memoryHigh(), setMemoryHigh()
116  * @notifySignal memoryHighChanged()
117  */
118  Q_PROPERTY(OptionalQULongLong memoryHigh READ memoryHigh WRITE setMemoryHigh NOTIFY memoryHighChanged)
119 
120  /**
121  * @brief memory usage protection (in bytes) of all executed processes within the application.
122  * @accessors memoryMin(), setMemoryMin()
123  * @notifySignal memoryMinChanged()
124  */
125  Q_PROPERTY(OptionalQULongLong memoryMin READ memoryMin WRITE setMemoryMin NOTIFY memoryMinChanged)
126 
127  /**
128  * @brief absolute limit on memory usage (in bytes) of all executed processes within the application.
129  * @accessors memoryMax(), setMemoryMax()
130  * @notifySignal memoryMaxChanged()
131  */
132  Q_PROPERTY(OptionalQULongLong memoryMax READ memoryMax WRITE setMemoryMax NOTIFY memoryMaxChanged)
133 
134  /**
135  * @brief absolute limit on swap usage (in bytes) of all executed processes within the application.
136  * @accessors memorySwapMax(), setMemorySwapMax()
137  * @notifySignal memorySwapMaxChanged()
138  */
139  Q_PROPERTY(OptionalQULongLong memorySwapMax READ memorySwapMax WRITE setMemorySwapMax NOTIFY memorySwapMaxChanged)
140 
141 public:
142  /**
143  * @brief The types of errors that can occur
144  */
145  enum ErrorCode {
146  /**
147  * Default value. No error has occurred
148  */
150 
151  /**
152  * A property set operation failed
153  */
155 
156  /**
157  * Initial loading of property values failed
158  */
160 
161  /**
162  * Error during stop() operation
163  */
164  StopFailedError
165  };
167 
168  /**
169  * @brief Use when only path is known. Incurs an extra DBus call to get unit id.
170  * @param path: dbus path of the application
171  * @param parent: parent QObject
172  */
173  explicit KApplicationScope(const QString &path, QObject *parent = nullptr);
174 
175  /**
176  * @brief Use when unit id is known in advance (such as when using KApplicationScopeLister)
177  * @param path: dbus path of the application
178  * @param id: systemd unit id
179  * @param parent: parent QObject
180  */
181  explicit KApplicationScope(const QString &path, const QString &id, QObject *parent = nullptr);
182 
183  /**
184  * @brief Use when only PID is known
185  * @param pid: process ID
186  * @param parent: parent QObject
187  * @return a new KApplicationScope, or null in case of failure (such as if process is not managed by systemd)
188  */
189  static KApplicationScope *fromPid(uint pid, QObject *parent = nullptr);
190 
191  ~KApplicationScope() override;
192 
193  QString path() const;
194  QString id() const;
195  QString cgroup() const;
196  QString description() const;
197  QString desktopName() const;
198  QString desktopFilePath() const;
199  QString instance() const;
200  ErrorCode lastError() const;
201 
202  OptionalQULongLong cpuQuota() const;
203  OptionalQULongLong cpuQuotaPeriod() const;
204  OptionalQULongLong cpuWeight() const;
205  OptionalQULongLong ioWeight() const;
206  OptionalQULongLong memoryLow() const;
207  OptionalQULongLong memoryHigh() const;
208  OptionalQULongLong memoryMin() const;
209  OptionalQULongLong memoryMax() const;
210  OptionalQULongLong memorySwapMax() const;
211 
212 Q_SIGNALS:
213  /**
214  * @brief emitted after loading when id is not known at constructor time
215  * @param id: the systemd unit id
216  */
217  void idChanged(const QString &id);
218 
219  /**
220  * @brief emitted when cgroup has been loaded asynchronously
221  * @param cgroup: the filesystem cgroup path
222  */
223  void cgroupChanged(const QString &cgroup);
224 
225  /**
226  * @brief emitted when description has been loaded asynchronously
227  * @param description: the systemd unit desciption
228  */
229  void descriptionChanged(const QString &description);
230 
231  /**
232  * @brief emitted when .desktop name has been loaded asynchronously
233  * @param description: the .desktop application name
234  */
235  void desktopNameChanged(const QString &desktopName);
236 
237  /**
238  * @brief emitted when .desktop file path has been loaded asynchronously
239  * @param description: the .desktop file path
240  */
241  void desktopFilePathChanged(const QString &desktopFilePath);
242 
243  /**
244  * @brief emitted when the instance random identifier has been loaded asynchronously
245  * @param description: the instance random identifier
246  */
247  void instanceChanged(const QString &instance);
248 
249  /**
250  * @brief emitted when there is an error setting or getting a value
251  * @param lastError: the error code
252  */
253  void errorOccurred(KApplicationScope::ErrorCode lastError);
254 
255  /**
256  * @brief emitted when any cgroup resource property has changed
257  * @param propertyName: the systemd name of the property
258  */
259  void propertyChanged(const QString &propertyName);
260 
261  /**
262  * @brief emitted when the cpu quota has changed
263  * @param quota: the new quota value
264  */
265  void cpuQuotaChanged(const OptionalQULongLong &quota);
266 
267  /**
268  * @brief emitted when the cpu quota period has changed
269  * @param period: the new period value
270  */
271  void cpuQuotaPeriodChanged(const OptionalQULongLong &period);
272 
273  /**
274  * @brief emitted when the cpu weight has changed
275  * @param weight: the new weight value
276  */
277  void cpuWeightChanged(const OptionalQULongLong &weight);
278 
279  /**
280  * @brief emitted when the io weight has changed
281  * @param weight: the new weight value
282  */
283  void ioWeightChanged(const OptionalQULongLong &weight);
284 
285  /**
286  * @brief emitted when memoryLow has changed
287  * @param memoryLow: the new memoryLow value
288  */
289  void memoryLowChanged(const OptionalQULongLong &memoryLow);
290 
291  /**
292  * @brief emitted when memoryHigh has changed
293  * @param memoryHigh: the new memoryHigh value
294  */
295  void memoryHighChanged(const OptionalQULongLong &memoryHigh);
296 
297  /**
298  * @brief emitted when memoryMin has changed
299  * @param memoryMin: the new memoryMin value
300  */
301  void memoryMinChanged(const OptionalQULongLong &memoryMin);
302 
303  /**
304  * @brief emitted when memoryMax has changed
305  * @param memoryMax: the new memoryMax value
306  */
307  void memoryMaxChanged(const OptionalQULongLong &memoryMax);
308 
309  /**
310  * @brief emitted when memorySwapMax has changed
311  * @param memorySwapMax: the new memorySwapMax value
312  */
313  void memorySwapMaxChanged(const OptionalQULongLong &memorySwapMax);
314 
315 public Q_SLOTS:
316  /**
317  * @brief Stops the application
318  */
319  void stop();
320 
321  /**
322  * @brief set cpuQuota
323  * @param quota: value to set
324  */
325  void setCpuQuota(const OptionalQULongLong &quota);
326 
327  /**
328  * @brief set cpuQuotaPeriod
329  * @param period: value to set
330  */
331  void setCpuQuotaPeriod(const OptionalQULongLong &period);
332 
333  /**
334  * @brief set cpuWeight
335  * @param weight: value to set
336  */
337  void setCpuWeight(const OptionalQULongLong &weight);
338 
339  /**
340  * @brief set ioWeight
341  * @param weight: value to set
342  */
343  void setIoWeight(const OptionalQULongLong &weight);
344 
345  /**
346  * @brief set memoryLow
347  * @param memoryLow: value to set
348  */
349  void setMemoryLow(const OptionalQULongLong &memoryLow);
350 
351  /**
352  * @brief set memoryHigh
353  * @param memoryHigh: value to set
354  */
355  void setMemoryHigh(const OptionalQULongLong &memoryHigh);
356 
357  /**
358  * @brief set memoryMin
359  * @param memoryMin: value to set
360  */
361  void setMemoryMin(const OptionalQULongLong &memoryMin);
362 
363  /**
364  * @brief set memoryMax
365  * @param memoryMax: value to set
366  */
367  void setMemoryMax(const OptionalQULongLong &memoryMax);
368 
369  /**
370  * @brief set memorySwapMax
371  * @param memorySwapMax: value to set
372  */
373  void setMemorySwapMax(const OptionalQULongLong &memorySwapMax);
374 
375 private:
376  KApplicationScopePrivate *const d_ptr;
377 };
378 
379 #endif // KAPPLICATIONSCOPE_H
Initial loading of property values failed.
Q_ENUM(...)
ErrorCode
The types of errors that can occur.
A desktop application in a systemd transient scope.
Q_PROPERTY(...)
A property set operation failed.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Oct 24 2021 23:04:01 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.