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