QgsTaskManager class

Task manager for managing a set of long-running QgsTask tasks.

Reference

This class can be created directly, or accessed via QgsApplication::taskManager().

Public types

struct TaskDefinition: Definition of a task for inclusion in the manager.

Constructors, destructors, conversion operators

QgsTaskManager(QObject* parent = nullptr): Constructor for QgsTaskManager.

Public functions

auto activeTasks() const -> QList<QgsTask*>: Returns a list of the active (queued or running) tasks.
auto addTask(QgsTask* task, int priority = 0) -> long: Adds a task to the manager.
auto addTask(const TaskDefinition& task, int priority = 0) -> long: Adds a task to the manager, using a full task definition (including dependency handling).
void cancelAll(): Instructs all tasks tracked by the manager to terminate.
auto count() const -> int: Returns the number of tasks tracked by the manager.
auto countActiveTasks() const -> int: Returns the number of active (queued or running) tasks.
auto dependencies(long taskId) const -> QSet<long>: Returns the set of task IDs on which a task is dependent.
auto dependenciesSatisfied(long taskId) const -> bool: Returns true if all dependencies for the specified task are satisfied.
auto dependentLayers(long taskId) const -> QList<QgsMapLayer*>: Returns a list of layers on which as task is dependent.
auto task(long id) const -> QgsTask*: Returns the task with matching ID.
auto taskId(QgsTask* task) const -> long: Returns the unique task ID corresponding to a task managed by the class.
auto tasks() const -> QList<QgsTask*>: Returns all tasks tracked by the manager.
auto tasksDependentOnLayer(QgsMapLayer* layer) const -> QList<QgsTask*>: Returns a list of tasks which depend on a layer.

Signals

void allTasksFinished(): Emitted when all tasks are complete.
void countActiveTasksChanged(int count): Emitted when the number of active tasks changes.
void finalTaskProgressChanged(double progress): Will be emitted when only a single task remains to complete and that task has reported a progress change.
void progressChanged(long taskId, double progress): Will be emitted when a task reports a progress change.
void statusChanged(long taskId, int status): Will be emitted when a task reports a status change.
void taskAboutToBeDeleted(long taskId): Emitted when a task is about to be deleted.
void taskAdded(long taskId): Emitted when a new task has been added to the manager.
void taskTriggered(QgsTask* task): Emitted when a task is triggered.

Public slots

void triggerTask(QgsTask* task): Triggers a task, e.g.

Function documentation

QgsTaskManager::QgsTaskManager(QObject* parent = nullptr)

Constructor for QgsTaskManager.

Parameters
parent	parent QObject

QList<QgsTask*> QgsTaskManager::activeTasks() const

Returns a list of the active (queued or running) tasks.

long QgsTaskManager::addTask(QgsTask* task, int priority = 0)

Adds a task to the manager.

Returns	unique task ID, or 0 if task could not be added

Ownership of the task is transferred to the manager, and the task manager will be responsible for starting the task. The priority argument can be used to control the run queue's order of execution, with larger numbers taking precedence over lower priority numbers.

long QgsTaskManager::addTask(const TaskDefinition& task, int priority = 0)

Adds a task to the manager, using a full task definition (including dependency handling).

Returns	unique task ID, or 0 if task could not be added

void QgsTaskManager::cancelAll()

Instructs all tasks tracked by the manager to terminate.

Individual tasks may take some time to cancel, or may totally ignore this instruction. Calling this does not block but will instead signal the tasks to cancel and then return immediately.

int QgsTaskManager::countActiveTasks() const

Returns the number of active (queued or running) tasks.

QSet<long> QgsTaskManager::dependencies(long taskId) const

Returns the set of task IDs on which a task is dependent.

QList<QgsMapLayer*> QgsTaskManager::dependentLayers(long taskId) const

Returns a list of layers on which as task is dependent.

Parameters
taskId	task ID
Returns	list of layers

The task will automatically be canceled if any of these layers are above to be removed.

QgsTask* QgsTaskManager::task(long id) const

Returns the task with matching ID.

Parameters
id	task ID
Returns	task if found, or nullptr

long QgsTaskManager::taskId(QgsTask* task) const

Returns the unique task ID corresponding to a task managed by the class.

Parameters
task	task to find
Returns	task ID, or -1 if task not found

QList<QgsTask> QgsTaskManager::tasksDependentOnLayer(QgsMapLayer layer) const

Returns a list of tasks which depend on a layer.

void QgsTaskManager::allTasksFinished() signal

Emitted when all tasks are complete.

void QgsTaskManager::countActiveTasksChanged(int count) signal

Emitted when the number of active tasks changes.

void QgsTaskManager::finalTaskProgressChanged(double progress) signal

Will be emitted when only a single task remains to complete and that task has reported a progress change.

Parameters
progress	percent of progress, from 0.0 - 100.0

void QgsTaskManager::progressChanged(long taskId, double progress) signal

Will be emitted when a task reports a progress change.

Parameters
taskId	ID of task
progress	percent of progress, from 0.0 - 100.0

void QgsTaskManager::statusChanged(long taskId, int status) signal

Will be emitted when a task reports a status change.

Parameters
taskId	ID of task
status	new task status

void QgsTaskManager::taskAboutToBeDeleted(long taskId) signal

Emitted when a task is about to be deleted.

Parameters
taskId	ID of task

void QgsTaskManager::taskAdded(long taskId) signal

Emitted when a new task has been added to the manager.

Parameters
taskId	ID of task

void QgsTaskManager::taskTriggered(QgsTask* task) signal

Emitted when a task is triggered.

This occurs when a user clicks on the task from the QGIS GUI, and can be used to show detailed progress reports or re-open a related dialog.

void QgsTaskManager::triggerTask(QgsTask* task) public slot

Triggers a task, e.g.

as a result of a GUI interaction.