QgsTask class

Abstract base class for long running background tasks.

Reference

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.

Derived classes

class QgsMapRendererTask: QgsTask task which draws a map to an image file or a painter as a background task.
class QgsNetworkContentFetcherTask: Handles HTTP network content fetching in a background task.
class QgsProcessingAlgRunnerTask: QgsTask task which runs a QgsProcessingAlgorithm in a background task.
class QgsProxyProgressTask: A QgsTask shell which proxies progress reports.
class QgsRasterFileWriterTask: QgsTask task which performs a QgsRasterFileWriter layer saving operation as a background task.
class QgsVectorFileWriterTask: QgsTask task which performs a QgsVectorFileWriter layer saving operation as a background task.
class QgsVectorLayerExporterTask: QgsTask task which performs a QgsVectorLayerExporter layer export operation as a background task.
class QgsVectorLayerFeatureCounter: Counts the features in a QgsVectorLayer in task.
class QgsVirtualLayerTask: Initializes a virtual layer with postpone mode activated and reloads the data in a separated thread.

Public types

enum Flag { CanCancel = 1 << 1, AllFlags = CanCancel }: Task flags.
enum SubTaskDependency { SubTaskIndependent = 0, ParentDependsOnSubTask }: Controls how subtasks relate to their parent task.
enum TaskStatus { Queued, OnHold, Running, Complete, Terminated }: Status of tasks.

Constructors, destructors, conversion operators

QgsTask(const QString& description = QString(), QgsTask::Flags flags = AllFlags): Constructor for QgsTask.

Public functions

void addSubTask(QgsTask* subTask, const QgsTaskList& dependencies = QgsTaskList(), SubTaskDependency subTaskDependency = SubTaskIndependent): Adds a subtask to this task.
auto canCancel() const -> bool: Returns true if the task can be canceled.
void cancel() virtual: Notifies the task that it should terminate.
auto dependentLayers() const -> QList<QgsMapLayer*>: Returns the list of layers on which the task depends.
auto description() const -> QString: Returns the task's description.
auto elapsedTime() const -> qint64: Returns the elapsed time since the task commenced, in milliseconds.
auto flags() const -> Flags: Returns the flags associated with the task.
void hold(): Places the task on hold.
auto isActive() const -> bool: Returns true if the task is active, ie it is not complete and has not been canceled.
auto progress() const -> double: 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.
auto status() const -> TaskStatus: Returns the current task status.
void unhold(): Releases the task from being held.
auto waitForFinished(int timeout = 30000) -> bool: Blocks the current thread until the task finishes or a maximum of timeout milliseconds.

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).

Protected functions

void finished(bool result) virtual: 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).
auto isCanceled() const -> bool: Will return true if task should terminate ASAP.
auto run() -> bool pure virtual: Performs the task's operation.

Protected slots

void setProgress(double progress): Sets the task's current progress.

Enum documentation

enum QgsTask::Flag

Task flags.

Enumerators
CanCancel	Task can be canceled.
AllFlags	Task supports all flags.

enum QgsTask::SubTaskDependency

Controls how subtasks relate to their parent task.

Enumerators
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.

enum QgsTask::TaskStatus

Status of tasks.

Enumerators
Queued	Task is queued and has not begun.
OnHold	Task is queued but on hold and will not be started.
Running	Task is currently running.
Complete	Task successfully completed.
Terminated	Task was terminated or errored.

Function documentation

QgsTask::QgsTask(const QString& description = QString(), QgsTask::Flags flags = AllFlags)

Constructor for QgsTask.

Parameters
description	text description of task
flags	task flags

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.

void QgsTask::cancel() 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.

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.

qint64 QgsTask::elapsedTime() const

Returns the elapsed time since the task commenced, in milliseconds.

The value is undefined for tasks which have not begun.

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.

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.

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.

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 true.

The result will be false if the wait timed out and true in any other case.

void QgsTask::begun() signal

Will be emitted by task to indicate its commencement.

void QgsTask::progressChanged(double progress) signal

Will be emitted by task when its progress changes.

Parameters
progress	percent of progress, from 0.0 - 100.0

void QgsTask::statusChanged(int status) signal

Will be emitted by task when its status changes.

Parameters
status	new task status

void QgsTask::taskCompleted() signal

Will be emitted by task to indicate its successful completion.

void QgsTask::taskTerminated() 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::finished(bool result) virtual protected

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.

bool QgsTask::isCanceled() const 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.

bool QgsTask::run() pure virtual protected

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.

void QgsTask::setProgress(double progress) protected slot

Sets the task's current progress.

Parameters
progress	percent of progress, from 0.0 - 100.0

The derived class should call this method whenever the task wants to update its progress. Calling will automatically emit the progressChanged signal.