MeVisLab Toolbox Reference
mlBackgroundTask.h
Go to the documentation of this file.
1/*************************************************************************************
2**
3** Copyright 2009, MeVis Medical Solutions AG
4**
5** The user may use this file in accordance with the license agreement provided with
6** the Software or, alternatively, in accordance with the terms contained in a
7** written agreement between the user and MeVis Medical Solutions AG.
8**
9** For further information use the contact form at https://www.mevislab.de/contact
10**
11**************************************************************************************/
12
13#ifndef ML_BACKGROUND_TASK_H
14#define ML_BACKGROUND_TASK_H
15
16// Local includes
18
20#include <mlTimeCounter.h>
21
22#include <ThirdPartyWarningsDisable.h>
23#include <boost/thread/mutex.hpp>
24#include <boost/thread/condition.hpp>
25#include <ThirdPartyWarningsRestore.h>
26
27ML_START_NAMESPACE
28
29//-----------------------------------------------------------------------
30class NotifyField;
31class BackgroundTask;
32class BackgroundTaskMessage;
33class BackgroundTaskStatusInformation;
34
35typedef void BackgroundTaskFinishedCB(void *data, BackgroundTask *task);
36
37//-----------------------------------------------------------------------
42{
44
45public:
47 enum Status {
53 Suspended
54 };
55
58 BackgroundTask(void* owner);
59 virtual ~BackgroundTask();
60
61 //------------------------------------------------------
63
64 //------------------------------------------------------
65
67 virtual void run() = 0;
68
70
71 //------------------------------------------------------
73
74 //------------------------------------------------------
75
77 bool isSynchronous() const { return _synchronous; }
79 void setSynchronous(bool flag) {
80 _synchronous = flag;
81 }
82
84 void setSynchronousCancelField(NotifyField* field) { _synchronousCancelField = field; }
85
87
88 //------------------------------------------------------
90
91 //------------------------------------------------------
92
94 Status status() const;
95
97 void cancel();
98
100 bool isCanceled() const;
101
109
111 void resume();
112
115 void suspend();
116
118 std::string statusString() const;
119
121 virtual void setStatusString(const std::string& status);
122
124 float progress() const;
125
127 virtual void setProgress(float progress);
128
130
131 //------------------------------------------------------
133
134 //------------------------------------------------------
135
138
140 bool hasOwner() const;
141
143 void* owner() const;
144
146
147 //------------------------------------------------------
149
150 //------------------------------------------------------
151
155
160
165
167
168 //------------------------------------------------------
170
171 //------------------------------------------------------
172
174 void logMessage(const std::string& message);
175
177 bool isVerbose() const { return _verbose; }
179 void setVerbose(bool flag) {
180 _verbose = flag;
181 }
182
184
185 //------------------------------------------------------
187
188 //------------------------------------------------------
190 double runningTime() const { return _runningTime; }
191
193 double idleTime() const { return _idleTime; }
194
197
199 MLuint32 taskId() const { return _taskId; }
200
202
203 //------------------------------------------------------
205
206 //------------------------------------------------------
207
210 void setTaskFinishedCB(BackgroundTaskFinishedCB* callback, void* userdata);
211
213
219 {
220 public:
222 virtual ~Observer() { }
223
225 virtual void statusChanged(BackgroundTask* task, double elapsedSeconds, BackgroundTask::Status status) = 0;
226
228 virtual void statusStringChanged(BackgroundTask* task, double elapsedSeconds, const std::string& status) = 0;
229
231 virtual void logMessage(BackgroundTask* task, double elapsedSeconds, const std::string& message) = 0;
232 };
233
235 void addObserver(Observer* observer);
237 void removeObserver(Observer* observer);
238
240
241protected:
242
248 void sendLogMessageToObservers(const std::string& msg);
249
251 void addIdleTime(double timeInSecs) { _idleTime += timeInSecs; }
252
253private:
255 friend struct BackgroundTaskManagerWorkerFunc;
256
258 void runTask();
259
261 void aboutToRun();
262
264 void aboutToFinish();
265
268 BackgroundTaskMessage* waitForMessage();
269
271 void putMessageIntoQueue(BackgroundTaskMessage* message);
272
274 void setStatus(Status status);
275
277 void setStatusIfNotCanceledOrSuspended(Status status);
278
280 void setStatusNoLock(Status status);
281
283 void runTaskFinishedCallback();
284
285 Status _status;
286 std::string _statusString;
287 float _progress;
288 mutable boost::mutex _statusMonitor;
289 boost::condition _statusNoLongerSuspended;
290
291 void* _owner;
292
294 TimeCounter _performanceTimer;
295 double _runningTime;
296 double _idleTime;
297
299 BackgroundTaskFinishedCB* _taskFinishedCB;
300 void* _taskFinishedCBUserData;
301
303 BackgroundTaskMessageQueue _messageQueue;
304
306 MLuint32 _taskId;
307
309 std::vector<Observer*> _observers;
310
312 bool _verbose;
313
315 bool _synchronous;
316
318 NotifyField* _synchronousCancelField;
319
320};
321
322
323ML_END_NAMESPACE
324
325#endif
326
327
#define MLBACKGROUNDTASKS_EXPORT
Project global and OS specific declarations.
the BackgroundTaskManager is the central singleton that manages running background tasks
The base class of all background messages.
BackgroundTaskStatusInformation creates a snapshot of the status of a given BackgroundTask,...
Abstract interface to observe the BackgroundTask.
virtual void logMessage(BackgroundTask *task, double elapsedSeconds, const std::string &message)=0
called when a task logs additional messages (for verbose logging)
virtual ~Observer()
virtual destructor
virtual void statusStringChanged(BackgroundTask *task, double elapsedSeconds, const std::string &status)=0
called when the status string has changed
virtual void statusChanged(BackgroundTask *task, double elapsedSeconds, BackgroundTask::Status status)=0
called when the status has changed
Base class for a task that is started in an extra thread.
void setTaskFinishedCB(BackgroundTaskFinishedCB *callback, void *userdata)
set this directly after initialization of the task (from the GUI thread) this callback will be called...
void suspend()
suspend task, so that it will wait until resume() is called (threadsafe).
void sendStatusStringChangedToObservers()
send the status string change to all observers
void cancel()
cancel the task (sets status to canceled) (threadsafe, typically called from GUI)
void setSynchronousCancelField(NotifyField *field)
set a cancel field that is used in synchronous mode to check if cancel was pressed
void removeObserver(Observer *observer)
remove the given observer (threadsafe) (ownership stays with caller)
void resume()
resume task after it was suspended (will only do something if current status() is Suspended) (threads...
virtual ~BackgroundTask()
void sendMessageToGUI(BackgroundTaskMessage *message)
send the message to the GUI (ownership of message is passed to the method) and it sets the sender of ...
BackgroundTask(void *owner)
Create a new task with given owner (the owner can be used to associate the task with a given class in...
void waitAndExecuteNextMessage()
execute the next message (waits if no messages are available and processes the first message that is ...
void * owner() const
get the owner of the task (only call from GUI thread!)
void addObserver(Observer *observer)
add the given observer (threadsafe) (ownership stays with caller)
void setVerbose(bool flag)
set if task uses verbose logging (call this ONLY on setup of the task, not while it is already runnin...
void getStatusInformation(BackgroundTaskStatusInformation &info)
get the complete status information (threadsafe)
bool shouldStop()
returns if the task should stop its work because it has been canceled.
std::string statusString() const
get current status string (threadsafe)
MLuint32 taskId() const
get the unique id of this task, the id of a task never changes
void setSynchronous(bool flag)
set if task is handled synchronous (call this ONLY on setup of the task, not while it is already runn...
void sendStatusChangedToObservers()
send the status change to all observers
bool hasOwner() const
check if owner was deleted (only call from GUI thread!)
virtual void setProgress(float progress)
update the progress while processing (from run() method only)
void sendLogMessageToObservers(const std::string &msg)
send the status string change to all observers
bool isVerbose() const
check if task uses verbose logging
bool isCanceled() const
check if the task was canceled (threadsafe, typically called from GUI)
float progress() const
get current progress (threadsafe)
Status status() const
returns the status of the task (threadsafe)
double idleTime() const
returns the idle time (in seconds) of the task (which it e.g. waited for getTile to complete),...
bool isSynchronous() const
check if task is synchronous (which means it is NOT run in an extra thread)
void setOwnerWasDeleted()
tell the task that it's owner was deleted (only call from GUI thread!), this also cancels the task
Status
Defines current status of the task.
void logMessage(const std::string &message)
log a message (only logged if verbose logging is turned on) (threadsafe)
virtual void setStatusString(const std::string &status)
update the status string while processing (from run() method only)
virtual void run()=0
run method that needs to be reimplemented (called from worker thread)
void addIdleTime(double timeInSecs)
add given timeInSecs as spent idle time
bool executeNextMessage()
execute the next message (does not block if no message is available) It returns true if there was a m...
double runningTime() const
returns the running time (in seconds) of the task (after it has finished or canceled,...
Field without value for notifications.
Definition: mlFields.h:1049
Class to measure precise time intervals.
Definition: mlTimeCounter.h:26
#define ML_DISALLOW_COPY_AND_ASSIGN(className)
Defines basic macros.
Definition: mlMacros.h:23
unsigned int MLuint32
Definition: mlTypeDefs.h:191
void BackgroundTaskFinishedCB(void *data, BackgroundTask *task)