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
29namespace Poco {
30
31
32class TaskManager;
33class Notification;
34class NotificationCenter;
35
36
37class 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{
44public:
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
97protected:
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
134private:
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//
153inline const std::string& Task::name() const
154{
155 return _name;
156}
157
158
159inline float Task::progress() const
160{
161 FastMutex::ScopedLock lock(_mutex);
162
163 return _progress;
164}
165
166
167inline bool Task::isCancelled() const
168{
169 return _state == TASK_CANCELLING;
170}
171
172
173inline Task::TaskState Task::state() const
174{
175 return _state;
176}
177
178
179inline 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