Mailcommon

jobscheduler.h
1/*
2 * SPDX-FileCopyrightText: 2004 David Faure <faure@kde.org>
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 <QList>
14#include <QTimer>
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
23namespace MailCommon
24{
25class FolderJob;
26class 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 */
33class MAILCOMMON_EXPORT ScheduledTask
34{
35public:
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 [[nodiscard]] Akonadi::Collection folder() const;
67
68 [[nodiscard]] bool isImmediate() const;
69
70private:
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 */
83class MAILCOMMON_EXPORT JobScheduler : public QObject
84{
85 Q_OBJECT
86public:
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
100private:
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
112private:
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 */
126class MAILCOMMON_EXPORT ScheduledJob : public FolderJob
127{
128public:
129 ScheduledJob(const Akonadi::Collection &folder, bool immediate);
130 ~ScheduledJob() override;
131
132protected:
133 bool mImmediate;
134};
135}
The FolderJob class.
Definition folderjob.h:19
The unique JobScheduler instance (owned by kmkernel) implements "background processing" of folder ope...
Base class for scheduled jobs.
A scheduled task is some information about a folder job that should be run later.
virtual int taskTypeId() const =0
An identifier for the type of task (a bit like QListViewItem::rtti).
virtual ScheduledJob * run()=0
Run this task, i.e.
Q_SCRIPTABLE Q_NOREPLY void pause()
The filter dialog.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:39:23 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.