summaryrefslogtreecommitdiffstats
path: root/kmail/jobscheduler.h
blob: c35121ddd163c37c47b3ca28d02e1d9d70d34e55 (plain)
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
/*
 * Copyright (c) 2004 David Faure <faure@kde.org>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; version 2 of the License
 *
 *  This program 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 General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 *  In addition, as a special exception, the copyright holders give
 *  permission to link the code of this program with any edition of
 *  the TQt library by Trolltech AS, Norway (or with modified versions
 *  of TQt that use the same license as TQt), and distribute linked
 *  combinations including the two.  You must obey the GNU General
 *  Public License in all respects for all of the code used other than
 *  TQt.  If you modify this file, you may extend this exception to
 *  your version of the file, but you are not obligated to do so.  If
 *  you do not wish to do so, delete this exception statement from
 *  your version.
 */

#ifndef KMAIL_JOBSCHEDULER_H
#define KMAIL_JOBSCHEDULER_H

#include <tqobject.h>
#include <tqvaluelist.h>
#include <tqguardedptr.h>
#include <tqtimer.h>

#include "folderjob.h"

// If this define is set, JobScheduler will show debug output, and related kmkernel timers will be shortened
// This is for debugging purposes only, don't commit with it.
//#define DEBUG_SCHEDULER

class KMFolder;
namespace KMail {

class FolderJob;
class ScheduledJob;

/**
 * A scheduled task is some information about a folder job that should be run later.
 * As long as it's not running, it's called a "task", i.e. something that needs to be done.
 * Tasks are held in the JobScheduler.
 */
class ScheduledTask {
public:
  /// Create a scheduled task for a given folder
  /// If @p immediate is true, the scheduler will run this task as soon
  /// as possible (but won't interrupt a currently running job for it)
  ScheduledTask( KMFolder* folder, bool immediate )
    : mCurrentFolder( folder ), mImmediate( immediate ) {}
  virtual ~ScheduledTask() {}

  /// Run this task, i.e. create a job for it.
  /// Important: the job's execute() method must either call open() on the
  /// folder or storage immediately, or abort (deleting itself).
  /// Usually, that job should also be cancellable.
  /// Otherwise (if the open() is delayed) an unrelated open() could happen first
  /// and mess things up.
  /// If for some reason (e.g. folder deleted) nothing should be done, return 0.
  virtual ScheduledJob* run() = 0;

  /// An identifier for the type of task (a bit like TQListViewItem::rtti)
  /// This allows to automatically prevent two identical tasks from being scheduled
  /// for the same folder. To circumvent this feature and make every task
  /// unique, return 0 here.
  virtual int taskTypeId() const = 0;

  /// The folder which this task is about, 0 if it was deleted meanwhile.
  KMFolder* folder() const { return mCurrentFolder; }

  bool isImmediate() const { return mImmediate; }

private:
  TQGuardedPtr<KMFolder> mCurrentFolder;
  bool mImmediate;
};

/**
 * The unique JobScheduler instance (owned by kmkernel) implements "background processing"
 * of folder operations (like expiration and compaction). Tasks (things to be done)
 * are registered with the JobScheduler, and it will execute them one at a time,
 * separated with a 1-minute timer. The jobs themselves should use timers to avoid
 * using too much CPU for too long. Tasks for opened folders are not executed until
 * the folder is closed.
 */
class JobScheduler : public TQObject
{
  Q_OBJECT
  TQ_OBJECT
public:
  JobScheduler( TQObject* tqparent, const char* name = 0 );
  ~JobScheduler();

  /// Register a task to be done for a given folder
  /// The ownership of the task is transferred to the JobScheduler
  void registerTask( ScheduledTask* task );

  /// Called by [implementations of] FolderStorage::open()
  /// Interrupt any running job for this folder and re-schedule it for later
  void notifyOpeningFolder( KMFolder* folder );

  // DCOP calls
  void pause();
  void resume();

private slots:
  /// Called by a timer to run the next job
  void slotRunNextJob();

  /// Called when the current job terminates
  void slotJobFinished();

private:
  void restartTimer();
  void interruptCurrentTask();
  void runTaskNow( ScheduledTask* task );
  typedef TQValueList<ScheduledTask *> TaskList;
  void removeTask( TaskList::Iterator& it );
private:
  TaskList mTaskList; // FIFO of tasks to be run

  TQTimer mTimer;
  int mPendingImmediateTasks;

  /// Information about the currently running job, if any
  ScheduledTask* mCurrentTask;
  ScheduledJob* mCurrentJob;
};

/**
 * Base class for scheduled jobs
 */
class ScheduledJob : public FolderJob
{
public:
  ScheduledJob( KMFolder* folder, bool immediate );

  bool isOpeningFolder() const { return mOpeningFolder; }

protected:
  bool mImmediate;
  bool mOpeningFolder;
};

} // namespace

#endif /* KMAIL_JOBSCHEDULER_H */