QGIS/python/core/auto_generated/qgstaskmanager.sip.in

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgstaskmanager.h                                            *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/






typedef QList< QgsTask * > QgsTaskList;

class QgsTask : QObject
{
%Docstring(signature="appended")
Abstract base class for long running background tasks.

Tasks can be controlled directly, or added to a
:py:class:`QgsTaskManager` for automatic management.

Derived classes should implement the process they want to execute in the
background within the :py:func:`~run` method. This method will be called
when the task commences (ie via calling :py:func:`~run` ).

Long running tasks should periodically check the :py:func:`~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.
%End

%TypeHeaderCode
#include "qgstaskmanager.h"
%End
  public:

    enum TaskStatus
    {
      Queued,
      OnHold,
      Running,
      Complete,
      Terminated,
    };

    enum Flag
    {
      CanCancel,
      CancelWithoutPrompt,
      Hidden,
      Silent,
      AllFlags,
    };
    typedef QFlags<QgsTask::Flag> Flags;


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

:param description: text description of task
:param flags: task flags
%End

    ~QgsTask();

    Flags flags() const;
%Docstring
Returns the flags associated with the task.
%End

    void setDescription( const QString &description );
%Docstring
Sets the task's ``description``. This must be called before adding the
task to a :py:class:`QgsTaskManager`, changing the description after
queuing the task has no effect.

.. versionadded:: 3.10
%End

    bool canCancel() const;
%Docstring
Returns ``True`` if the task can be canceled.
%End

    bool isActive() const;
%Docstring
Returns ``True`` if the task is active, ie it is not complete and has
not been canceled.
%End

    TaskStatus status() const;
%Docstring
Returns the current task status.
%End

    QString description() const;
%Docstring
Returns the task's description.
%End

    double progress() const;
%Docstring
Returns the task's progress (between 0.0 and 100.0)
%End

    qint64 elapsedTime() const;
%Docstring
Returns the elapsed time since the task commenced, in milliseconds.

The value is undefined for tasks which have not begun.

.. versionadded:: 3.4
%End

    virtual void cancel();
%Docstring
Notifies the task that it should terminate. Calling this is not
guaranteed to immediately end the task, rather it sets the
:py:func:`~QgsTask.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.

.. seealso:: :py:func:`isCanceled`
%End

    void hold();
%Docstring
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
:py:class:`QgsTaskManager`.

.. seealso:: :py:func:`unhold`
%End

    void unhold();
%Docstring
Releases the task from being held. For tasks managed by a
:py:class:`QgsTaskManager` calling this will re-add them to the queue.
If the task in not currently being held then calling this has no effect.

.. seealso:: :py:func:`hold`
%End

    enum SubTaskDependency
    {
      SubTaskIndependent,
      ParentDependsOnSubTask,
    };

    void addSubTask( QgsTask *subTask /Transfer/, const QgsTaskList &dependencies = QgsTaskList(),
                     SubTaskDependency subTaskDependency = SubTaskIndependent );
%Docstring
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 :py:class:`QgsTaskManager` for
subtasks to be utilized. Subtasks should not be added manually to a
:py:class:`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.
%End

    void setDependentLayers( const QList<QgsMapLayer *> &dependentLayers );
%Docstring
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.

.. seealso:: :py:func:`dependentLayers`
%End

    QList< QgsMapLayer * > dependentLayers() const;
%Docstring
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.

.. seealso:: :py:func:`setDependentLayers`
%End

    bool waitForFinished( int timeout = 30000 );
%Docstring
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.
%End

  signals:

    void progressChanged( double progress );
%Docstring
Will be emitted by task when its progress changes.

:param progress: percent of progress, from 0.0 - 100.0

.. note::

   derived classes should not emit this signal directly, instead they should call
   :py:func:`~QgsTask.setProgress`
%End

    void statusChanged( int status );
%Docstring
Will be emitted by task when its status changes.

:param status: new task status

.. note::

   derived classes should not emit this signal directly, it will automatically
   be emitted
%End

    void begun();
%Docstring
Will be emitted by task to indicate its commencement.

.. note::

   derived classes should not emit this signal directly, it will automatically
   be emitted when the task begins
%End

    void taskCompleted();
%Docstring
Will be emitted by task to indicate its successful completion.

.. note::

   derived classes should not emit this signal directly, it will automatically
   be emitted
%End

    void taskTerminated();
%Docstring
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).

.. note::

   derived classes should not emit this signal directly, it will automatically
   be emitted
%End

  protected:

    virtual bool run() = 0;
%Docstring
Performs the task's operation. This method will be called when the task
commences (ie via calling :py:func:`~QgsTask.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.
%End

    virtual void finished( bool result );
%Docstring
If the task is managed by a :py:class:`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.
%End

    bool isCanceled() const;
%Docstring
Will return ``True`` if task should terminate ASAP. If the task reports
the CanCancel flag, then derived classes' :py:func:`~QgsTask.run`
methods should periodically check this and terminate in a safe manner.
%End

  protected slots:

    void setProgress( double progress );
%Docstring
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.

:param progress: percent of progress, from 0.0 - 100.0
%End

};


QFlags<QgsTask::Flag> operator|(QgsTask::Flag f1, QFlags<QgsTask::Flag> f2);


class QgsTaskManager : QObject
{
%Docstring(signature="appended")
Task manager for managing a set of long-running :py:class:`QgsTask`
tasks.

This class can be created directly, or accessed via
:py:func:`QgsApplication.taskManager()`.
%End

%TypeHeaderCode
#include "qgstaskmanager.h"
%End
  public:

    QgsTaskManager( QObject *parent /TransferThis/ = 0 );
%Docstring
Constructor for QgsTaskManager.

:param parent: parent QObject
%End

    ~QgsTaskManager();

    struct TaskDefinition
    {

      explicit TaskDefinition( QgsTask *task, const QgsTaskList &dependentTasks = QgsTaskList() );
%Docstring
Constructor for TaskDefinition. Ownership of the task is not transferred
to the definition, but will be transferred to a QgsTaskManager.
%End

      QgsTask *task;

      QgsTaskList dependentTasks;

    };

    QThreadPool *threadPool();
%Docstring
Returns the threadpool utilized by the task manager.

.. versionadded:: 3.34
%End

    long addTask( QgsTask *task /Transfer/, int priority = 0 );
%Docstring
Adds a task to the manager. 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.

:return: unique task ID, or 0 if task could not be added
%End

    long addTask( const TaskDefinition &task /Transfer/, int priority = 0 );
%Docstring
Adds a task to the manager, using a full task definition (including
dependency handling). 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.

:return: unique task ID, or 0 if task could not be added
%End

    QgsTask *task( long id ) const;
%Docstring
Returns the task with matching ID.

:param id: task ID

:return: task if found, or ``None``
%End

    QList<QgsTask *> tasks() const;
%Docstring
Returns all tasks tracked by the manager.
%End

    int count() const;
%Docstring
Returns the number of tasks tracked by the manager.
%End

    long taskId( QgsTask *task ) const;
%Docstring
Returns the unique task ID corresponding to a task managed by the class.

:param task: task to find

:return: task ID, or -1 if task not found
%End

    void cancelAll();
%Docstring
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.
%End

    bool dependenciesSatisfied( long taskId ) const;
%Docstring
Returns ``True`` if all dependencies for the specified task are
satisfied
%End


    QList< QgsMapLayer * > dependentLayers( long taskId ) const;
%Docstring
Returns a list of layers on which as task is dependent. The task will
automatically be canceled if any of these layers are about to be
removed.

:param taskId: task ID

:return: list of layers

.. seealso:: :py:func:`tasksDependentOnLayer`
%End

    QList< QgsTask * > tasksDependentOnLayer( QgsMapLayer *layer ) const;
%Docstring
Returns a list of tasks which depend on a layer.

.. seealso:: :py:func:`dependentLayers`
%End

    QList< QgsTask * > activeTasks() const;
%Docstring
Returns a list of the active (queued or running) tasks.

.. seealso:: :py:func:`countActiveTasks`
%End

    int countActiveTasks( bool includeHidden = true ) const;
%Docstring
Returns the number of active (queued or running) tasks.

The ``includeHidden`` argument dictates whether hidden tasks should be
shown.

.. seealso:: :py:func:`activeTasks`

.. seealso:: :py:func:`countActiveTasksChanged`
%End

  public slots:

    void triggerTask( QgsTask *task );
%Docstring
Triggers a task, e.g. as a result of a GUI interaction.

.. seealso:: :py:func:`taskTriggered`
%End

  signals:

    void progressChanged( long taskId, double progress );
%Docstring
Will be emitted when a task reports a progress change

:param taskId: ID of task
:param progress: percent of progress, from 0.0 - 100.0
%End

    void finalTaskProgressChanged( double progress );
%Docstring
Will be emitted when only a single task remains to complete and that
task has reported a progress change

:param progress: percent of progress, from 0.0 - 100.0
%End

    void statusChanged( long taskId, int status );
%Docstring
Will be emitted when a task reports a status change

:param taskId: ID of task
:param status: new task status
%End

    void taskAdded( long taskId );
%Docstring
Emitted when a new task has been added to the manager

:param taskId: ID of task
%End

    void taskAboutToBeDeleted( long taskId );
%Docstring
Emitted when a task is about to be deleted

:param taskId: ID of task
%End

    void allTasksFinished();
%Docstring
Emitted when all tasks are complete

.. seealso:: :py:func:`countActiveTasksChanged`
%End

    void countActiveTasksChanged( int count );
%Docstring
Emitted when the number of active tasks changes

.. seealso:: :py:func:`countActiveTasks`
%End

    void taskTriggered( QgsTask *task );
%Docstring
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.

.. seealso:: :py:func:`triggerTask`
%End

};

class QgsTaskWithSerialSubTasks : QgsTask
{
%Docstring(signature="appended")
A task that is composed of sub-tasks to be executed in a serial way.

This may be useful for example to add several layers in a single target
dataset which does not support concurrent updates.

.. versionadded:: 3.36
%End

%TypeHeaderCode
#include "qgstaskmanager.h"
%End
  public:
    QgsTaskWithSerialSubTasks( const QString &desc = QString() );
%Docstring
Constructor
%End
    ~QgsTaskWithSerialSubTasks();

    void addSubTask( QgsTask *subTask /Transfer/ );
%Docstring
Add a subtask and transfer its ownership

The parent task must be added to a :py:class:`QgsTaskManager` for
subtasks to be utilized. Subtasks should not be added manually to a
:py:class:`QgsTaskManager`, rather, only the parent task should be added
to the manager.

For now, subtasks can *NOT* be nested.
%End

    virtual void cancel();


  protected:


    virtual bool run();

};

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgstaskmanager.h                                            *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/