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
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
//
// Task.h
//
// Library: Foundation
// Package: Tasks
// Module: Tasks
//
// Definition of the Task class.
//
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// SPDX-License-Identifier: BSL-1.0
//
#ifndef Foundation_Task_INCLUDED
#define Foundation_Task_INCLUDED
#include "Poco/Foundation.h"
#include "Poco/Runnable.h"
#include "Poco/RefCountedObject.h"
#include "Poco/Mutex.h"
#include "Poco/Event.h"
namespace Poco {
class TaskManager;
class Notification;
class NotificationCenter;
class Foundation_API Task: public Runnable, public RefCountedObject
/// A Task is a subclass of Runnable that has a name
/// and supports progress reporting and cancellation.
///
/// A TaskManager object can be used to take care of the
/// lifecycle of a Task.
{
public:
enum TaskState
{
TASK_IDLE,
TASK_STARTING,
TASK_RUNNING,
TASK_CANCELLING,
TASK_FINISHED
};
Task(const std::string& name);
/// Creates the Task.
const std::string& name() const;
/// Returns the task's name.
float progress() const;
/// Returns the task's progress.
/// The value will be between 0.0 (just started)
/// and 1.0 (completed).
virtual void cancel();
/// Requests the task to cancel itself. For cancellation
/// to work, the task's runTask() method must periodically
/// call isCancelled() and react accordingly.
///
/// Can be overridden to implement custom behavior,
/// but the base class implementation of cancel() should
/// be called to ensure proper behavior.
bool isCancelled() const;
/// Returns true if cancellation of the task has been
/// requested.
///
/// A Task's runTask() method should periodically
/// call this method and stop whatever it is doing in an
/// orderly way when this method returns true.
/// If task is cancelled before it had a chance to run,
/// runTask() will never be called.
TaskState state() const;
/// Returns the task's current state.
void reset();
/// Sets the task's progress to zero and clears the
/// cancel flag.
virtual void runTask() = 0;
/// Do whatever the task needs to do. Must
/// be overridden by subclasses.
void run();
/// If task has not been cancelled prior to this call, it
/// calls the task's runTask() method and notifies the owner of
/// the task's start and completion.
/// If task has been cancelled prior to this call, it only sets
/// the state to TASK_FINISHED and notifies the owner.
bool hasOwner() const;
/// Returns true iff the task has an owner.
protected:
bool sleep(long milliseconds);
/// Suspends the current thread for the specified
/// amount of time.
///
/// If the task is cancelled while it is sleeping,
/// sleep() will return immediately and the return
/// value will be true. If the time interval
/// passes without the task being cancelled, the
/// return value is false.
///
/// A Task should use this method in favor of Thread::sleep().
bool yield();
/// Yields cpu to other threads
///
/// If the task is cancelled while it is suspended,
/// yield() will return true. If the tasks resumes
/// without being cancelled, the
/// return value is false.
///
/// A Task should use this method in favor of Thread::yield().
void setProgress(float progress);
/// Sets the task's progress.
/// The value should be between 0.0 (just started)
/// and 1.0 (completed).
virtual void postNotification(Notification* pNf);
/// Posts a notification to the task manager's
/// notification center.
///
/// A task can use this method to post custom
/// notifications about its progress.
void setOwner(TaskManager* pOwner);
/// Sets the (optional) owner of the task.
TaskManager* getOwner() const;
/// Returns the owner of the task, which may be NULL.
TaskState setState(TaskState state);
/// Sets the task's state.
virtual ~Task();
/// Destroys the Task.
private:
Task();
Task(const Task&);
Task& operator = (const Task&);
std::string _name;
std::atomic<TaskManager*> _pOwner;
std::atomic<float> _progress;
std::atomic<TaskState> _state;
Event _cancelEvent;
mutable FastMutex _mutex;
friend class TaskManager;
};
//
// inlines
//
inline const std::string& Task::name() const
{
return _name;
}
inline float Task::progress() const
{
return _progress;
}
inline bool Task::isCancelled() const
{
return _state == TASK_CANCELLING;
}
inline Task::TaskState Task::state() const
{
return _state;
}
inline TaskManager* Task::getOwner() const
{
return _pOwner;
}
inline bool Task::hasOwner() const
{
return _pOwner != nullptr;
}
} // namespace Poco
#endif // Foundation_Task_INCLUDED
|
