MeVisLabToolboxReference
mlBackgroundTask.h
Go to the documentation of this file.
1 // **InsertLicense** code
2 //----------------------------------------------------------------------------------
9 //----------------------------------------------------------------------------------
10 
11 
12 #ifndef __mlBackgroundTask_H
13 #define __mlBackgroundTask_H
14 
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 
27 ML_START_NAMESPACE
28 
29 //-----------------------------------------------------------------------
30 class BackgroundTask;
31 class BackgroundTaskMessage;
32 class BackgroundTaskStatusInformation;
33 
34 typedef void BackgroundTaskFinishedCB(void *data, BackgroundTask *task);
35 
36 //-----------------------------------------------------------------------
41 {
43 
44 public:
46  enum Status {
52  Suspended
53  };
54 
57  BackgroundTask(void* owner);
58  virtual ~BackgroundTask();
59 
60  //------------------------------------------------------
62 
63  //------------------------------------------------------
64 
66  virtual void run() = 0;
67 
69 
70  //------------------------------------------------------
72 
73  //------------------------------------------------------
74 
76  bool isSynchronous() const { return _synchronous; }
78  void setSynchronous(bool flag) {
79  _synchronous = flag;
80  }
81 
83  void setSynchronousCancelField(NotifyField* field) { _synchronousCancelField = field; }
84 
86 
87  //------------------------------------------------------
89 
90  //------------------------------------------------------
91 
93  Status status() const;
94 
96  void cancel();
97 
99  bool isCanceled() const;
100 
107  bool shouldStop();
108 
110  void resume();
111 
114  void suspend();
115 
117  std::string statusString() const;
118 
120  virtual void setStatusString(const std::string& status);
121 
123  float progress() const;
124 
126  virtual void setProgress(float progress);
127 
129 
130  //------------------------------------------------------
132 
133  //------------------------------------------------------
134 
136  void setOwnerWasDeleted();
137 
139  bool hasOwner() const;
140 
142  void* owner() const;
143 
145 
146  //------------------------------------------------------
148 
149  //------------------------------------------------------
150 
153  void waitAndExecuteNextMessage();
154 
158  bool executeNextMessage();
159 
163  void sendMessageToGUI(BackgroundTaskMessage* message);
164 
166 
167  //------------------------------------------------------
169 
170  //------------------------------------------------------
171 
173  void logMessage(const std::string& message);
174 
176  bool isVerbose() const { return _verbose; }
178  void setVerbose(bool flag) {
179  _verbose = flag;
180  }
181 
183 
184  //------------------------------------------------------
186 
187  //------------------------------------------------------
189  double runningTime() const { return _runningTime; }
190 
192  double idleTime() const { return _idleTime; }
193 
195  void getStatusInformation(BackgroundTaskStatusInformation& info);
196 
198  MLuint32 taskId() const { return _taskId; }
199 
201 
202  //------------------------------------------------------
204 
205  //------------------------------------------------------
206 
209  void setTaskFinishedCB(BackgroundTaskFinishedCB* callback, void* userdata);
210 
212 
217  class Observer
218  {
219  public:
221  virtual ~Observer() { }
222 
224  virtual void statusChanged(BackgroundTask* task, double elapsedSeconds, BackgroundTask::Status status) = 0;
225 
227  virtual void statusStringChanged(BackgroundTask* task, double elapsedSeconds, const std::string& status) = 0;
228 
230  virtual void logMessage(BackgroundTask* task, double elapsedSeconds, const std::string& message) = 0;
231  };
232 
234  void addObserver(Observer* observer);
236  void removeObserver(Observer* observer);
237 
239 
240 protected:
241 
243  void sendStatusChangedToObservers();
245  void sendStatusStringChangedToObservers();
247  void sendLogMessageToObservers(const std::string& msg);
248 
250  void addIdleTime(double timeInSecs) { _idleTime += timeInSecs; }
251 
252 private:
253  friend class BackgroundTaskManager;
254  friend struct BackgroundTaskManagerWorkerFunc;
255 
257  void runTask();
258 
260  void aboutToRun();
261 
263  void aboutToFinish();
264 
267  BackgroundTaskMessage* waitForMessage();
268 
270  void putMessageIntoQueue(BackgroundTaskMessage* message);
271 
273  void setStatus(Status status);
274 
276  void setStatusIfNotCanceledOrSuspended(Status status);
277 
279  void setStatusNoLock(Status status);
280 
282  void runTaskFinishedCallback();
283 
284  Status _status;
285  std::string _statusString;
286  float _progress;
287  mutable boost::mutex _statusMonitor;
288  boost::condition _statusNoLongerSuspended;
289 
290  void* _owner;
291 
293  TimeCounter _performanceTimer;
294  double _runningTime;
295  double _idleTime;
296 
298  BackgroundTaskFinishedCB* _taskFinishedCB;
299  void* _taskFinishedCBUserData;
300 
302  BackgroundTaskMessageQueue _messageQueue;
303 
305  MLuint32 _taskId;
306 
308  std::vector<Observer*> _observers;
309 
311  bool _verbose;
312 
314  bool _synchronous;
315 
317  NotifyField* _synchronousCancelField;
318 
319 };
320 
321 
322 ML_END_NAMESPACE
323 
324 #endif
325 
326 
Abstract interface to observe the BackgroundTask.
Base class for a task that is started in an extra thread.
void setSynchronousCancelField(NotifyField *field)
set a cancel field that is used in synchronous mode to check if cancel was pressed ...
DCMTREE_EXPORT void logMessage(std::string message, int errorCode=0)
Log a message using the provided callback, if any.
Class to measure precise time intervals in seconds.
Project global and OS specific declarations.
#define MLBACKGROUNDTASKS_EXPORT
#define ML_DISALLOW_COPY_AND_ASSIGN(className)
Macro to make a copy constructor and assignment private, to avoid copying and assigning of macros...
Definition: mlMacros.h:17
bool isVerbose() const
check if task uses verbose logging
MLuint32 taskId() const
get the unique id of this task, the id of a task never changes
bool isSynchronous() const
check if task is synchronous (which means it is NOT run in an extra thread)
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 BackgroundTaskFinishedCB(void *data, BackgroundTask *task)
Status
Defines current status of the task.
virtual ~Observer()
virtual destructor
double idleTime() const
returns the idle time (in seconds) of the task (which it e.g. waited for getTile to complete)...
Class to measure precise time intervals.
Definition: mlTimeCounter.h:20
BackgroundTaskStatusInformation creates a snapshot of the status of a given BackgroundTask, to allow later read access without races or even destruction of the background task (copyable).
double runningTime() const
returns the running time (in seconds) of the task (after it has finished or canceled, only call from GUI thread)
the BackgroundTaskManager is the central singleton that manages running background tasks ...
unsigned int MLuint32
Definition: mlTypeDefs.h:213
The base class of all background messages.
void setVerbose(bool flag)
set if task uses verbose logging (call this ONLY on setup of the task, not while it is already runnin...
Field without value for notifications.
Definition: mlFields.h:1040
void addIdleTime(double timeInSecs)
add given timeInSecs as spent idle time