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
|
/***
Olive - Non-Linear Video Editor
Copyright (C) 2019 Olive Team
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
***/
#ifndef TASK_H
#define TASK_H
#include <memory>
#include <QDateTime>
#include <QObject>
#include "common/cancelableobject.h"
OLIVE_NAMESPACE_ENTER
/**
* @brief A base class for background tasks running in Olive.
*
* Tasks are multithreaded by design (i.e. they will always spawn
* a new thread and run in it).
*
* To subclass your own Task, override Action() and return TRUE on success or FALSE on failure. Note that a Task can
* provide a "negative" output and still have succeeded. For example, the ProbeTask's role is to determine whether a
* certain media file can be used in Olive. Even if the probe *fails* to find a Decoder for this file, the Task itself
* has *succeeded* at discovering this. A failure of ProbeTask would indicate a catastrophic failure meaning it was
* unable to determine anything about the file.
*
* Tasks should be used with the TaskManager which will manage starting and deleting them. It'll also only start as
* many Tasks as there are threads on the system as to not overload them.
*
* Tasks support "dependency tasks", i.e. a Task that should be complete before another Task begins.
*/
class Task : public QObject, public CancelableObject
{
Q_OBJECT
public:
/**
* @brief Task Constructor
*/
Task() :
title_(tr("Task")),
error_(tr("Unknown error")),
start_time_(0)
{
}
/**
* @brief Retrieve the current title of this Task
*/
const QString& GetTitle() const
{
return title_;
}
/**
* @brief Returns the error that occurred if Run() returns false
*/
const QString& GetError() const
{
return error_;
}
const qint64& GetStartTime() const
{
return start_time_;
}
public slots:
/**
* @brief Run this task
*
* @return True if the task completed successfully, false if not.
*
* \see GetError() if this returns false.
*/
bool Start()
{
start_time_ = QDateTime::currentMSecsSinceEpoch();
return Run();
}
/**
* @brief Reset state so that Run() can be called again.
*
* Override this if your class holds any persistent state that should be cleared/modified before
* it's safe for Run() to run again.
*/
virtual void Reset(){}
/**
* @brief Cancel the Task
*
* Sends a signal to the Task to stop as soon as possible. Always call this directly or connect
* with Qt::DirectConnection, or else it'll be queued *after* the task has already finished.
*/
void Cancel()
{
CancelableObject::Cancel();
}
protected:
virtual bool Run() = 0;
/**
* @brief Set the error message
*
* It is recommended to use this if your Action() function ever returns FALSE to tell the user why the failure
* occurred.
*/
void SetError(const QString& s)
{
error_ = s;
}
/**
* @brief Set the Task title
*
* Used in the UI Task Manager to distinguish Tasks from each other. Generally this should be set in the constructor
* and shouldn't need to change during the life of the Task. To show an error message, it's recommended to use
* set_error() instead.
*/
void SetTitle(const QString& s)
{
title_ = s;
}
signals:
/**
* @brief Signal emitted whenever progress is made
*
* Emit this throughout Action() to update any attached ProgressBars on the progress of this Task.
*
* @param p
*
* A progress value between 0.0 and 1.0.
*/
void ProgressChanged(double d);
private:
QString title_;
QString error_;
qint64 start_time_;
};
OLIVE_NAMESPACE_EXIT
#endif // TASK_H
|
