Upstream tarball 10013
[amule.git] / src / ThreadScheduler.h
blob4fef348978f56004c7c111ea820675a9c710ba5c
1 //
2 // This file is part of the aMule Project.
3 //
4 // Copyright (c) 2006-2008 Mikkel Schubert ( xaignar@amule.org / http://www.amule.org )
5 // Copyright (c) 2006-2008 aMule Team ( admin@amule.org / http://www.amule.org )
6 //
7 // Any parts of this program derived from the xMule, lMule or eMule project,
8 // or contributed by third-party developers are copyrighted by their
9 // respective authors.
11 // This program is free software; you can redistribute it and/or modify
12 // it under the terms of the GNU General Public License as published by
13 // the Free Software Foundation; either version 2 of the License, or
14 // (at your option) any later version.
16 // This program is distributed in the hope that it will be useful,
17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 // GNU General Public License for more details.
20 //
21 // You should have received a copy of the GNU General Public License
22 // along with this program; if not, write to the Free Software
23 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
27 #ifndef THREADSCHEDULER_H
28 #define THREADSCHEDULER_H
30 #include <deque>
31 #include <map>
33 #include "Types.h"
34 #include "MuleThread.h"
37 class CThreadTask;
40 //! The priority values of tasks.
41 enum ETaskPriority
43 ETP_Low = 0,
44 ETP_Normal,
45 ETP_High,
46 //! For tasks such as finding shared files and ipfilter.dat loading only.
47 ETP_Critical
51 /**
52 * This class mananges scheduling of background tasks.
54 * Currently it is assumed that all tasks are IO intensive,
55 * so that only a single task is allowed to proceed at any
56 * one time. All threads are run in lowest priority mode.
58 * Tasks are sorted by priority (see ETaskPriority) and age.
60 * Note that the scheduler starts in suspended mode, in
61 * which tasks are queued but not executed. Call Start()
62 * to begin execution of the tasks.
64 class CThreadScheduler
66 public:
67 /** Starts execution of queued tasks. */
68 static void Start();
70 /**
71 * Terminates task execution and frees the scheduler object.
73 * Tasks added after this are discarded.
75 static void Terminate();
78 /**
79 * Adds a new task to the queue, returning true if the task was queued.
81 * Before the task is queued, it is checked against the
82 * existing tasks based on type and description. If an
83 * matching task already exists, this task-object is
84 * discarded. The task is also discarded if the scheduler
85 * has been terminated. If 'overwrite' is true, any
86 * existing duplicate task is dropped, and if already
87 * running, terminated.
89 * Note: This function takes ownership of the task.
91 * @see Start
92 * @see Terminate
94 static bool AddTask(CThreadTask* task, bool overwrite = false);
96 private:
97 CThreadScheduler();
98 ~CThreadScheduler();
100 /** Returns the number of tasks on the queue. */
101 size_t GetTaskCount() const;
103 /** Tries to add the given task to the queue, returning true on success. */
104 bool DoAddTask(CThreadTask* task, bool overwrite);
106 /** Creates the actual scheduler thread if none exist. */
107 void CreateSchedulerThread();
109 /** Entry function called via internal thread-object. */
110 void* Entry();
112 //! Contains a task and its age.
113 typedef std::pair<CThreadTask*, uint32> CEntryPair;
115 //! List of currently scheduled tasks.
116 std::deque<CEntryPair> m_tasks;
118 //! Specifies if tasks should be resorted by priority.
119 bool m_tasksDirty;
121 typedef std::map<wxString, CThreadTask*> CDescMap;
122 typedef std::map<wxString, CDescMap> CTypeMap;
123 //! Map of current task by type -> desc. Used to avoid duplicate tasks.
124 CTypeMap m_taskDescs;
126 //! The actual worker thread.
127 CMuleThread* m_thread;
128 //! The currently running task, if any.
129 CThreadTask* m_currentTask;
131 friend class CTaskThread;
132 friend struct CTaskSorter;
137 * Base-class of all threaded tasks.
139 * This class acts as a pseudo-thread, and is transparently
140 * executed on a worker thread by the CThreadScheduler
141 * class.
143 * Note that the task type should be an unique description
144 * of the task type, as it is used to detect completion of
145 * all tasks of a given type and in duplicate detection
146 * with the description. The description should be unique
147 * for the given task, such that duplicates can be discovered.
149 class CThreadTask
151 public:
153 * @param type Should be a name constant among tasks of the type (hashing, completion, etc).
154 * @param desc Should be an unique description for this task, for detecting duplicates.
155 * @param priority Decides how soon the task will be carried out.
157 CThreadTask(const wxString& type, const wxString& desc, ETaskPriority priority = ETP_Normal);
159 /** Needed since CThreadScheduler only works with CThreadTask pointers. */
160 virtual ~CThreadTask();
162 /** Returns the task type, used for debugging and duplicate detection. */
163 const wxString& GetType() const;
165 /** Returns the task description, used for debugging and duplicate detection. */
166 const wxString& GetDesc() const;
168 /** Returns the priority of the task. Used when selecting the next task. */
169 ETaskPriority GetPriority() const;
171 protected:
172 //! @see wxThread::Entry
173 virtual void Entry() = 0;
175 /** Called when the last task of a specific type has been completed. */
176 virtual void OnLastTask();
178 /** @see wxThread::OnExit */
179 virtual void OnExit();
181 /** @see wxThread::TestDestroy */
182 bool TestDestroy() const;
184 private:
185 wxString m_type;
186 wxString m_desc;
187 ETaskPriority m_priority;
189 //! The owner (scheduler), used when calling TestDestroy.
190 CMuleThread* m_owner;
191 //! Specifies if the specifc task should be aborted.
192 bool m_abort;
194 friend class CThreadScheduler;
197 #endif
198 // File_checked_for_headers