Mailcommon

jobscheduler.h
1 /*
2  * SPDX-FileCopyrightText: 2004 David Faure <[email protected]>
3  *
4  * SPDX-License-Identifier: GPL-2.0-or-later
5  */
6 
7 #pragma once
8 
9 #include "mailcommon_export.h"
10 
11 #include <QObject>
12 
13 #include <QTimer>
14 #include <QVector>
15 
16 #include "folderjob.h"
17 #include <Akonadi/Collection>
18 // If this define is set, JobScheduler will show debug output, and related kmkernel
19 // timers will be shortened.
20 // This is for debugging purposes only, don't commit with it.
21 //#define DEBUG_SCHEDULER
22 
23 namespace MailCommon
24 {
25 class FolderJob;
26 class ScheduledJob;
27 
28 /**
29  * A scheduled task is some information about a folder job that should be run later.
30  * As long as it's not running, it's called a "task", i.e. something that needs to be done.
31  * Tasks are managed by the JobScheduler.
32  */
33 class MAILCOMMON_EXPORT ScheduledTask
34 {
35 public:
36  /**
37  * Creates a scheduled task for a given folder.
38  * If @p immediate is true, the scheduler will run this task as soon
39  * as possible (but won't interrupt a currently running job for it).
40  */
41  ScheduledTask(const Akonadi::Collection &folder, bool immediate);
42  virtual ~ScheduledTask();
43 
44  /**
45  * Run this task, i.e. create a job for it.
46  * Important: the job's execute() method must either call open() on the folder
47  * or storage immediately, or abort (deleting itself).
48  * Usually, that job should also be cancellable.
49  * Otherwise (if the open() is delayed) an unrelated open() could happen first
50  * and mess things up.
51  * If for some reason (e.g. a folder is deleted) nothing should be done, return 0.
52  */
53  virtual ScheduledJob *run() = 0;
54 
55  /**
56  * An identifier for the type of task (a bit like QListViewItem::rtti).
57  * This allows to automatically prevent two identical tasks from being scheduled
58  * for the same folder. To circumvent this feature and make every task unique,
59  * return 0 here.
60  */
61  virtual int taskTypeId() const = 0;
62 
63  /**
64  * The folder which this task is supposed to handle, 0 if it was deleted meanwhile.
65  */
66  Q_REQUIRED_RESULT Akonadi::Collection folder() const;
67 
68  Q_REQUIRED_RESULT bool isImmediate() const;
69 
70 private:
71  const Akonadi::Collection mCurrentFolder;
72  const bool mImmediate;
73 };
74 
75 /**
76  * The unique JobScheduler instance (owned by kmkernel) implements "background processing"
77  * of folder operations (like expiration and compaction). Tasks (things to be done)
78  * are registered with the JobScheduler, and it will execute them one at a time,
79  * separated by a 1-minute timer. The jobs themselves should use timers to avoid
80  * using too much CPU for too long. Tasks for opened folders are not executed until
81  * the folder is closed.
82  */
83 class MAILCOMMON_EXPORT JobScheduler : public QObject
84 {
85  Q_OBJECT
86 public:
87  explicit JobScheduler(QObject *parent);
88  ~JobScheduler() override;
89 
90  /**
91  * Register a task to be done for a given folder. The ownership of the task is transferred
92  * to the JobScheduler.
93  */
94  void registerTask(ScheduledTask *task);
95 
96  // D-Bus calls, called from KMKernel
97  void pause();
98  void resume();
99 
100 private:
101  // Called by a timer to run the next job
102  MAILCOMMON_NO_EXPORT void slotRunNextJob();
103 
104  // Called when the current job terminates
105  MAILCOMMON_NO_EXPORT void slotJobFinished();
106  MAILCOMMON_NO_EXPORT void restartTimer();
107  MAILCOMMON_NO_EXPORT void interruptCurrentTask();
108  MAILCOMMON_NO_EXPORT void runTaskNow(ScheduledTask *task);
110  MAILCOMMON_NO_EXPORT void removeTask(TaskList::Iterator &it);
111 
112 private:
113  TaskList mTaskList; // FIFO of tasks to be run
114 
115  QTimer mTimer;
116  int mPendingImmediateTasks = 0;
117 
118  /// Information about the currently running job, if any
119  ScheduledTask *mCurrentTask = nullptr;
120  ScheduledJob *mCurrentJob = nullptr;
121 };
122 
123 /**
124  * Base class for scheduled jobs.
125  */
126 class MAILCOMMON_EXPORT ScheduledJob : public FolderJob
127 {
128 public:
129  ScheduledJob(const Akonadi::Collection &folder, bool immediate);
130  ~ScheduledJob() override;
131 
132 protected:
133  bool mImmediate;
134 };
135 }
A scheduled task is some information about a folder job that should be run later.
Definition: jobscheduler.h:33
The FolderJob class.
Definition: folderjob.h:18
Q_SCRIPTABLE Q_NOREPLY void pause()
The unique JobScheduler instance (owned by kmkernel) implements "background processing" of folder ope...
Definition: jobscheduler.h:83
Base class for scheduled jobs.
Definition: jobscheduler.h:126
The filter dialog.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jun 4 2023 03:58:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.