1 | // |
2 | // Task.h |
3 | // |
4 | // Library: Foundation |
5 | // Package: Tasks |
6 | // Module: Tasks |
7 | // |
8 | // Definition of the Task class. |
9 | // |
10 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
11 | // and Contributors. |
12 | // |
13 | // SPDX-License-Identifier: BSL-1.0 |
14 | // |
15 | |
16 | |
17 | #ifndef Foundation_Task_INCLUDED |
18 | #define Foundation_Task_INCLUDED |
19 | |
20 | |
21 | #include "Poco/Foundation.h" |
22 | #include "Poco/Runnable.h" |
23 | #include "Poco/RefCountedObject.h" |
24 | #include "Poco/Mutex.h" |
25 | #include "Poco/Event.h" |
26 | |
27 | #include <atomic> |
28 | |
29 | namespace Poco { |
30 | |
31 | |
32 | class TaskManager; |
33 | class Notification; |
34 | class NotificationCenter; |
35 | |
36 | |
37 | class Foundation_API Task: public Runnable, public RefCountedObject |
38 | /// A Task is a subclass of Runnable that has a name |
39 | /// and supports progress reporting and cancellation. |
40 | /// |
41 | /// A TaskManager object can be used to take care of the |
42 | /// lifecycle of a Task. |
43 | { |
44 | public: |
45 | enum TaskState |
46 | { |
47 | TASK_IDLE, |
48 | TASK_STARTING, |
49 | TASK_RUNNING, |
50 | TASK_CANCELLING, |
51 | TASK_FINISHED |
52 | }; |
53 | |
54 | Task(const std::string& name); |
55 | /// Creates the Task. |
56 | |
57 | const std::string& name() const; |
58 | /// Returns the task's name. |
59 | |
60 | float progress() const; |
61 | /// Returns the task's progress. |
62 | /// The value will be between 0.0 (just started) |
63 | /// and 1.0 (completed). |
64 | |
65 | virtual void cancel(); |
66 | /// Requests the task to cancel itself. For cancellation |
67 | /// to work, the task's runTask() method must periodically |
68 | /// call isCancelled() and react accordingly. |
69 | /// |
70 | /// Can be overridden to implement custom behavior, |
71 | /// but the base class implementation of cancel() should |
72 | /// be called to ensure proper behavior. |
73 | |
74 | bool isCancelled() const; |
75 | /// Returns true if cancellation of the task has been |
76 | /// requested. |
77 | /// |
78 | /// A Task's runTask() method should periodically |
79 | /// call this method and stop whatever it is doing in an |
80 | /// orderly way when this method returns true. |
81 | |
82 | TaskState state() const; |
83 | /// Returns the task's current state. |
84 | |
85 | void reset(); |
86 | /// Sets the task's progress to zero and clears the |
87 | /// cancel flag. |
88 | |
89 | virtual void runTask() = 0; |
90 | /// Do whatever the task needs to do. Must |
91 | /// be overridden by subclasses. |
92 | |
93 | void run(); |
94 | /// Calls the task's runTask() method and notifies the owner |
95 | /// of the task's start and completion. |
96 | |
97 | protected: |
98 | bool sleep(long milliseconds); |
99 | /// Suspends the current thread for the specified |
100 | /// amount of time. |
101 | /// |
102 | /// If the task is cancelled while it is sleeping, |
103 | /// sleep() will return immediately and the return |
104 | /// value will be true. If the time interval |
105 | /// passes without the task being cancelled, the |
106 | /// return value is false. |
107 | /// |
108 | /// A Task should use this method in favor of Thread::sleep(). |
109 | |
110 | void setProgress(float progress); |
111 | /// Sets the task's progress. |
112 | /// The value should be between 0.0 (just started) |
113 | /// and 1.0 (completed). |
114 | |
115 | virtual void postNotification(Notification* pNf); |
116 | /// Posts a notification to the task manager's |
117 | /// notification center. |
118 | /// |
119 | /// A task can use this method to post custom |
120 | /// notifications about its progress. |
121 | |
122 | void setOwner(TaskManager* pOwner); |
123 | /// Sets the (optional) owner of the task. |
124 | |
125 | TaskManager* getOwner() const; |
126 | /// Returns the owner of the task, which may be NULL. |
127 | |
128 | void setState(TaskState state); |
129 | /// Sets the task's state. |
130 | |
131 | virtual ~Task(); |
132 | /// Destroys the Task. |
133 | |
134 | private: |
135 | Task(); |
136 | Task(const Task&); |
137 | Task& operator = (const Task&); |
138 | |
139 | std::string _name; |
140 | TaskManager* _pOwner; |
141 | float _progress; |
142 | std::atomic<TaskState> _state; |
143 | Event _cancelEvent; |
144 | mutable FastMutex _mutex; |
145 | |
146 | friend class TaskManager; |
147 | }; |
148 | |
149 | |
150 | // |
151 | // inlines |
152 | // |
153 | inline const std::string& Task::name() const |
154 | { |
155 | return _name; |
156 | } |
157 | |
158 | |
159 | inline float Task::progress() const |
160 | { |
161 | FastMutex::ScopedLock lock(_mutex); |
162 | |
163 | return _progress; |
164 | } |
165 | |
166 | |
167 | inline bool Task::isCancelled() const |
168 | { |
169 | return _state == TASK_CANCELLING; |
170 | } |
171 | |
172 | |
173 | inline Task::TaskState Task::state() const |
174 | { |
175 | return _state; |
176 | } |
177 | |
178 | |
179 | inline TaskManager* Task::getOwner() const |
180 | { |
181 | FastMutex::ScopedLock lock(_mutex); |
182 | |
183 | return _pOwner; |
184 | } |
185 | |
186 | |
187 | } // namespace Poco |
188 | |
189 | |
190 | #endif // Foundation_Task_INCLUDED |
191 | |