QGIS API Documentation 3.41.0-Master (d5b93354e9c)
|
Abstract base class for long running background tasks. More...
#include <qgstaskmanager.h>
Public Types | |
enum | Flag { CanCancel = 1 << 1 , CancelWithoutPrompt = 1 << 2 , Hidden = 1 << 3 , Silent = 1 << 4 , AllFlags = CanCancel } |
Task flags. More... | |
typedef QFlags< Flag > | Flags |
enum | SubTaskDependency { SubTaskIndependent = 0 , ParentDependsOnSubTask } |
Controls how subtasks relate to their parent task. More... | |
enum | TaskStatus { Queued , OnHold , Running , Complete , Terminated } |
Status of tasks. More... | |
Signals | |
void | begun () |
Will be emitted by task to indicate its commencement. | |
void | progressChanged (double progress) |
Will be emitted by task when its progress changes. | |
void | statusChanged (int status) |
Will be emitted by task when its status changes. | |
void | taskCompleted () |
Will be emitted by task to indicate its successful completion. | |
void | taskTerminated () |
Will be emitted by task if it has terminated for any reason other then completion (e.g., when a task has been canceled or encountered an internal error). | |
Public Member Functions | |
QgsTask (const QString &description=QString(), QgsTask::Flags flags=AllFlags) | |
Constructor for QgsTask. | |
~QgsTask () override | |
void | addSubTask (QgsTask *subTask, const QgsTaskList &dependencies=QgsTaskList(), SubTaskDependency subTaskDependency=SubTaskIndependent) |
Adds a subtask to this task. | |
bool | canCancel () const |
Returns true if the task can be canceled. | |
virtual void | cancel () |
Notifies the task that it should terminate. | |
QList< QgsMapLayer * > | dependentLayers () const |
Returns the list of layers on which the task depends. | |
QString | description () const |
Returns the task's description. | |
qint64 | elapsedTime () const |
Returns the elapsed time since the task commenced, in milliseconds. | |
Flags | flags () const |
Returns the flags associated with the task. | |
void | hold () |
Places the task on hold. | |
bool | isActive () const |
Returns true if the task is active, ie it is not complete and has not been canceled. | |
double | progress () const |
Returns the task's progress (between 0.0 and 100.0) | |
void | setDependentLayers (const QList< QgsMapLayer * > &dependentLayers) |
Sets a list of layers on which the task depends. | |
void | setDescription (const QString &description) |
Sets the task's description. | |
TaskStatus | status () const |
Returns the current task status. | |
void | unhold () |
Releases the task from being held. | |
bool | waitForFinished (int timeout=30000) |
Blocks the current thread until the task finishes or a maximum of timeout milliseconds. | |
Protected Slots | |
void | setProgress (double progress) |
Sets the task's current progress. | |
Protected Member Functions | |
virtual void | finished (bool result) |
If the task is managed by a QgsTaskManager, this will be called after the task has finished (whether through successful completion or via early termination). | |
bool | isCanceled () const |
Will return true if task should terminate ASAP. | |
virtual bool | run ()=0 |
Performs the task's operation. | |
Friends | |
class | QgsTaskManager |
class | QgsTaskRunnableWrapper |
class | QgsTaskWithSerialSubTasks |
class | TestQgsTaskManager |
Abstract base class for long running background tasks.
Tasks can be controlled directly, or added to a QgsTaskManager for automatic management.
Derived classes should implement the process they want to execute in the background within the run() method. This method will be called when the task commences (ie via calling run() ).
Long running tasks should periodically check the isCanceled() flag to detect if the task has been canceled via some external event. If this flag is true
then the task should clean up and terminate at the earliest possible convenience.
Definition at line 54 of file qgstaskmanager.h.
typedef QFlags< Flag > QgsTask::Flags |
Definition at line 80 of file qgstaskmanager.h.
enum QgsTask::Flag |
Task flags.
Definition at line 72 of file qgstaskmanager.h.
Controls how subtasks relate to their parent task.
Enumerator | |
---|---|
SubTaskIndependent | Subtask is independent of the parent, and can run before, after or at the same time as the parent. |
ParentDependsOnSubTask | Subtask must complete before parent can begin. |
Definition at line 167 of file qgstaskmanager.h.
enum QgsTask::TaskStatus |
Status of tasks.
Definition at line 61 of file qgstaskmanager.h.
QgsTask::QgsTask | ( | const QString & | description = QString() , |
QgsTask::Flags | flags = AllFlags |
||
) |
Constructor for QgsTask.
description | text description of task |
flags | task flags |
Definition at line 31 of file qgstaskmanager.cpp.
|
override |
Definition at line 39 of file qgstaskmanager.cpp.
void QgsTask::addSubTask | ( | QgsTask * | subTask, |
const QgsTaskList & | dependencies = QgsTaskList() , |
||
SubTaskDependency | subTaskDependency = SubTaskIndependent |
||
) |
Adds a subtask to this task.
Subtasks allow a single task to be created which consists of multiple smaller tasks. Subtasks are not visible or indepedently controllable by users. Ownership of the subtask is transferred. Subtasks can have an optional list of dependent tasks, which must be completed before the subtask can begin. By default subtasks are considered independent of the parent task, ie they can be run either before, after, or at the same time as the parent task. This behavior can be overridden through the subTaskDependency argument. Note that subtasks should NEVER be dependent on their parent task, and violating this constraint will prevent the task from completing successfully.
The parent task must be added to a QgsTaskManager for subtasks to be utilized. Subtasks should not be added manually to a QgsTaskManager, rather, only the parent task should be added to the manager.
Subtasks can be nested, ie a subtask can legally be a parent task itself with its own set of subtasks.
Definition at line 157 of file qgstaskmanager.cpp.
|
signal |
Will be emitted by task to indicate its commencement.
|
inline |
Returns true
if the task can be canceled.
Definition at line 106 of file qgstaskmanager.h.
|
virtual |
Notifies the task that it should terminate.
Calling this is not guaranteed to immediately end the task, rather it sets the isCanceled() flag which task subclasses can check and terminate their operations at an appropriate time. Any subtasks owned by this task will also be canceled. Derived classes must ensure that the base class implementation is called from any overridden version.
Reimplemented in QgsVectorWarperTask, QgsProfileExporterTask, QgsMapRendererTask, QgsNetworkContentFetcherTask, QgsPointCloudLayerExporterTask, QgsProcessingAlgRunnerTask, QgsProviderSublayerTask, QgsMapHitTestTask, QgsProxyProgressTask, QgsTaskWithSerialSubTasks, QgsVectorFileWriterTask, QgsVirtualLayerTask, QgsRasterFileWriterTask, QgsVectorLayerExporterTask, and QgsVectorLayerFeatureCounter.
Definition at line 93 of file qgstaskmanager.cpp.
QList< QgsMapLayer * > QgsTask::dependentLayers | ( | ) | const |
Returns the list of layers on which the task depends.
The task will automatically be canceled if any of these layers are about to be removed.
Definition at line 165 of file qgstaskmanager.cpp.
|
inline |
Returns the task's description.
Definition at line 122 of file qgstaskmanager.h.
qint64 QgsTask::elapsedTime | ( | ) | const |
Returns the elapsed time since the task commenced, in milliseconds.
The value is undefined for tasks which have not begun.
Definition at line 58 of file qgstaskmanager.cpp.
|
inlineprotectedvirtual |
If the task is managed by a QgsTaskManager, this will be called after the task has finished (whether through successful completion or via early termination).
The result argument reflects whether the task was successfully completed or not. This method is always called from the main thread, so it is safe to create widgets and perform other operations which require the main thread. However, the GUI will be blocked for the duration of this method so tasks should avoid performing any lengthy operations here.
Reimplemented in QgsMapRendererTask, QgsPointCloudLayerExporterTask, QgsProcessingAlgRunnerTask, QgsVectorFileWriterTask, QgsRasterFileWriterTask, and QgsVectorLayerExporterTask.
Definition at line 284 of file qgstaskmanager.h.
|
inline |
Returns the flags associated with the task.
Definition at line 94 of file qgstaskmanager.h.
void QgsTask::hold | ( | ) |
Places the task on hold.
If the task in not queued (ie it is already running or has finished) then calling this has no effect. Calling this method only has an effect for tasks which are managed by a QgsTaskManager.
Definition at line 126 of file qgstaskmanager.cpp.
|
inline |
Returns true
if the task is active, ie it is not complete and has not been canceled.
Definition at line 112 of file qgstaskmanager.h.
|
protected |
Will return true
if task should terminate ASAP.
If the task reports the CanCancel flag, then derived classes' run() methods should periodically check this and terminate in a safe manner.
Definition at line 120 of file qgstaskmanager.cpp.
|
inline |
Returns the task's progress (between 0.0 and 100.0)
Definition at line 127 of file qgstaskmanager.h.
|
signal |
Will be emitted by task when its progress changes.
progress | percent of progress, from 0.0 - 100.0 |
|
protectedpure virtual |
Performs the task's operation.
This method will be called when the task commences (ie via calling start() ), and subclasses should implement the operation they wish to perform in the background within this method.
A task must return a boolean value to indicate whether the task was completed successfully or terminated before completion.
Implemented in QgsVectorWarperTask, QgsProfileExporterTask, QgsMapRendererTask, QgsNetworkContentFetcherTask, QgsPointCloudLayerExporterTask, QgsProcessingAlgRunnerTask, QgsProviderSublayerTask, QgsCopyFileTask, QgsMapHitTestTask, QgsProxyProgressTask, QgsTaskWithSerialSubTasks, QgsVectorFileWriterTask, QgsVirtualLayerTask, QgsRasterFileWriterTask, QgsVectorLayerExporterTask, and QgsVectorLayerFeatureCounter.
void QgsTask::setDependentLayers | ( | const QList< QgsMapLayer * > & | dependentLayers | ) |
Sets a list of layers on which the task depends.
The task will automatically be canceled if any of these layers are about to be removed.
Definition at line 199 of file qgstaskmanager.cpp.
void QgsTask::setDescription | ( | const QString & | description | ) |
Sets the task's description.
This must be called before adding the task to a QgsTaskManager, changing the description after queuing the task has no effect.
Definition at line 53 of file qgstaskmanager.cpp.
|
protectedslot |
Sets the task's current progress.
The derived class should call this method whenever the task wants to update its progress. Calling will automatically emit the progressChanged signal.
progress | percent of progress, from 0.0 - 100.0 |
Definition at line 235 of file qgstaskmanager.cpp.
|
inline |
Returns the current task status.
Definition at line 117 of file qgstaskmanager.h.
|
signal |
Will be emitted by task when its status changes.
status | new task status |
|
signal |
Will be emitted by task to indicate its successful completion.
|
signal |
Will be emitted by task if it has terminated for any reason other then completion (e.g., when a task has been canceled or encountered an internal error).
void QgsTask::unhold | ( | ) |
Releases the task from being held.
For tasks managed by a QgsTaskManager calling this will re-add them to the queue. If the task in not currently being held then calling this has no effect.
Definition at line 141 of file qgstaskmanager.cpp.
bool QgsTask::waitForFinished | ( | int | timeout = 30000 | ) |
Blocks the current thread until the task finishes or a maximum of timeout milliseconds.
If timeout is 0
the thread will be blocked forever. In case of a timeout, the task will still be running. In case the task already is finished, the method will return immediately while returning \c true
.
The result will be false
if the wait timed out and true
in any other case.
Definition at line 170 of file qgstaskmanager.cpp.
|
friend |
Definition at line 370 of file qgstaskmanager.h.
|
friend |
Definition at line 372 of file qgstaskmanager.h.
|
friend |
Definition at line 371 of file qgstaskmanager.h.
|
friend |
Definition at line 373 of file qgstaskmanager.h.