272 lines
8.5 KiB
C++
272 lines
8.5 KiB
C++
/***
|
|
|
|
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 <QObject>
|
|
|
|
#include "task/taskthread.h"
|
|
|
|
/**
|
|
* @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 *suceeded* 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
|
|
{
|
|
Q_OBJECT
|
|
public:
|
|
/**
|
|
* @brief The Status enum
|
|
*
|
|
* All states that a Task can be in. When subclassing, you don't need to set the Task's status as the base class
|
|
* does that automatically.
|
|
*/
|
|
enum Status {
|
|
/// This Task is yet to start
|
|
kWaiting,
|
|
|
|
/// This Task is currently running (see Action())
|
|
kWorking,
|
|
|
|
/// This Task has completed successfully
|
|
kFinished,
|
|
|
|
/// This Task failed and could not complete
|
|
kError
|
|
};
|
|
|
|
/**
|
|
* @brief Task Constructor
|
|
*/
|
|
Task();
|
|
|
|
/**
|
|
* @brief Try to start this Task
|
|
*
|
|
* The main function for starting this Task. If this task is currently waiting, this function will start a new thread
|
|
* and set the status to kWorking.
|
|
*
|
|
* This function also checks its dependency Tasks and will only start if all of them are complete. If they are still
|
|
* working, this function will return FALSE and the status will continue to be kWaiting. If any of them failed, this
|
|
* Task will also fail - this function will return FALSE and the status will be set to kError.
|
|
*
|
|
* @return
|
|
*
|
|
* TRUE if the Task started, FALSE if not.
|
|
*/
|
|
bool Start();
|
|
|
|
/**
|
|
* @brief Perform opening tasks before main Task thread begins
|
|
*
|
|
* If a Task needs to perform any actions in the main thread before starting the Task's thread, (e.g. copying or
|
|
* altering information) this function should be overridden and those actions should be performed here. It's
|
|
* guaranteed that Prologue() will run in the main thread, and as such, functions here should remain as minimal as
|
|
* possible as to not block the main thread for a noticeable amount of time. If your Task does not need any such
|
|
* actions, you don't need to override this.
|
|
*
|
|
* @return
|
|
*
|
|
* TRUE if the prologue was successful and we can start the Task now. If Prologue returns FALSE, the thread is never
|
|
* created and Action()/Epilogue() are never run.
|
|
*/
|
|
virtual bool Prologue();
|
|
|
|
/**
|
|
* @brief The main Task function which is run in a separate thread
|
|
*
|
|
* Action() is the function that gets called once the separate thread has been created. This function should be
|
|
* overridden in subclasses.
|
|
*
|
|
* It's also recommended to emit ProgressChanged() throughout your Action() so that any attached ProgressBars can
|
|
* show accurate progress information.
|
|
*
|
|
* @return
|
|
*
|
|
* TRUE if the Task could complete successfully. FALSE if not. Note that FALSE should only be returned if the Task
|
|
* could not finish, not if the Task found a negative result (see Task documentation for details). Before returning
|
|
* FALSE, it's recommended to use set_error() to signal to the user what caused the failure.
|
|
*/
|
|
virtual bool Action();
|
|
|
|
/**
|
|
* @brief Perform any closing Tasks in the main thread after the Task thread finishes
|
|
*
|
|
* It's likely your Task modifies data used throughout the program in some way, and to prevent race conditions, it's
|
|
* recommended to work with "copies" of that data in Action() (which is run in separate thread) and never
|
|
* access/modify any data used in other threads. Then, after the Action() thread is complete, that data can be used to
|
|
* "apply" that data in the main thread here.
|
|
*
|
|
* As this runs in the main thread, these functions shouldn't be kept fairly minimal to prevent blocking the main
|
|
* thread.
|
|
*
|
|
* @return
|
|
*
|
|
* TRUE if the Epilogue completed successfully. FALSE if not. A FALSE result here is considered a complete failure
|
|
* of the Task, even though the bulk of the processing has been performed in Action().
|
|
*/
|
|
virtual bool Epilogue();
|
|
|
|
/**
|
|
* @brief Current status of the Task
|
|
*
|
|
* @return
|
|
*
|
|
* A member of the Task::Status enum.
|
|
*/
|
|
const Status& status();
|
|
|
|
/**
|
|
* @brief Retrieve the current title of this Task
|
|
*/
|
|
const QString& text();
|
|
|
|
/**
|
|
* @brief Retrieve the current error message (empty if no error)
|
|
*/
|
|
const QString& error();
|
|
|
|
/**
|
|
* @brief Add a dependency Task
|
|
*
|
|
* If another Task needs to complete before this one can begin, it can be added as a "dependency task". If a task
|
|
* has dependencies, Start() will not start the task until the dependency tasks have all completed. If any of the
|
|
* dependency tasks fail, this Task will also fail before starting.
|
|
*
|
|
* Dependencies can only be added if the Task is kWaiting.
|
|
*
|
|
* Naturally Tasks should never be dependent on each other. Circular dependencies will result in Tasks that never
|
|
* begin.
|
|
*
|
|
* @param dependency
|
|
*/
|
|
void AddDependency(Task* dependency);
|
|
|
|
/**
|
|
* @brief Reset this Task back to the waiting state
|
|
*/
|
|
void ResetState();
|
|
|
|
public slots:
|
|
/**
|
|
* @brief Cancel the Task
|
|
*
|
|
* Sends a signal to the Task to stop and waits for the Task to finish before returning. Tasks must be responsive to
|
|
* cancelling so that the main thread doesn't halt for too long.
|
|
*
|
|
* Cancel()'s function is fairly simple, it sets cancelled_ to TRUE and waits for the thread to return. It's the
|
|
* responsibility of the code in Action() to be able to respond quickly to cancelled_ changing.
|
|
*/
|
|
void Cancel();
|
|
|
|
protected:
|
|
/**
|
|
* @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 set_error(const QString& 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 set_text(const QString& s);
|
|
|
|
/**
|
|
* @brief Returns whether the thread has been explicitly cancelled or not
|
|
*/
|
|
bool cancelled();
|
|
|
|
signals:
|
|
/**
|
|
* @brief Signal emitted whenever the Task status changes
|
|
*/
|
|
void StatusChanged(Task::Status s);
|
|
|
|
/**
|
|
* @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 value (percentage) between 0 and 100.
|
|
*/
|
|
void ProgressChanged(int p);
|
|
|
|
/**
|
|
* @brief Signal emitted when the Task finishes whether it succeeded or failed
|
|
*/
|
|
void Finished();
|
|
|
|
/**
|
|
* @brief Signal emitted when this Task is removed from TaskManager
|
|
*/
|
|
void Removed();
|
|
|
|
private:
|
|
/**
|
|
* @brief Set the status of this Task (also emits StatusChanged())
|
|
*/
|
|
void set_status(const Task::Status& status);
|
|
|
|
Status status_;
|
|
|
|
TaskThread thread_;
|
|
|
|
QString text_;
|
|
|
|
QString error_;
|
|
|
|
QList<Task*> dependencies_;
|
|
|
|
bool cancelled_;
|
|
|
|
private slots:
|
|
/**
|
|
* @brief A slot when the inner thread completes either successfully or unsuccessfully
|
|
*/
|
|
void ThreadComplete();
|
|
};
|
|
|
|
using TaskPtr = std::shared_ptr<Task>;
|
|
|
|
#endif // TASK_H
|