Skip to content

Commit

Permalink
Split algorithm execution into separate prepare/process/postProcess s…
Browse files Browse the repository at this point in the history
…teps

The prepare and postProcess steps are designed to be run in main
thread only, while the process step can safely be run in a background
thread.
  • Loading branch information
nyalldawson committed Jul 6, 2017
1 parent 5c4f642 commit c2621b1
Show file tree
Hide file tree
Showing 10 changed files with 702 additions and 262 deletions.
95 changes: 92 additions & 3 deletions python/core/processing/qgsprocessingalgorithm.sip
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,9 @@ class QgsProcessingAlgorithm
QVariantMap run( const QVariantMap &parameters,
QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool *ok /Out/ = 0 ) const;
%Docstring
Executes the algorithm using the specified ``parameters``.
Executes the algorithm using the specified ``parameters``. This method internally
creates a copy of the algorithm before running it, so it is safe to call
on algorithms directly retrieved from QgsProcessingRegistry and QgsProcessingProvider.

The ``context`` argument specifies the context in which the algorithm is being run.

Expand All @@ -234,6 +236,55 @@ class QgsProcessingAlgorithm

:return: A map of algorithm outputs. These may be output layer references, or calculated
values such as statistical calculations.

.. note::

this method can only be called from the main thread. Use prepare(), runPrepared() and postProcess()
if you need to run algorithms from a background thread, or use the QgsProcessingAlgRunnerTask class.
:rtype: QVariantMap
%End

bool prepare( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );
%Docstring
Prepares the algorithm for execution. This must be run in the main thread, and allows the algorithm
to pre-evaluate input parameters in a thread-safe manner. This must be called before
calling runPrepared() (which is safe to do in any thread).
.. seealso:: runPrepared()
.. seealso:: postProcess()
.. note::

This method modifies the algorithm instance, so it is not safe to call
on algorithms directly retrieved from QgsProcessingRegistry and QgsProcessingProvider. Instead, a copy
of the algorithm should be created with clone() and prepare()/runPrepared() called on the copy.
:rtype: bool
%End

bool runPrepared( QgsProcessingContext &context, QgsProcessingFeedback *feedback );
%Docstring
Runs the algorithm, which has been prepared by an earlier call to prepare().
This method is safe to call from any thread. Returns true if the algorithm was successfully executed.
After runPrepared() has finished, the postProcess() method should be called from the main thread
to allow the algorithm to perform any required cleanup tasks and return its final result.
.. seealso:: prepare()
.. seealso:: postProcess()
.. note::

This method modifies the algorithm instance, so it is not safe to call
on algorithms directly retrieved from QgsProcessingRegistry and QgsProcessingProvider. Instead, a copy
of the algorithm should be created with clone() and prepare()/runPrepared() called on the copy.
:rtype: bool
%End

QVariantMap postProcess( QgsProcessingContext &context, QgsProcessingFeedback *feedback );
%Docstring
Should be called in the main thread following the completion of runPrepared(). This method
allows the algorithm to perform any required cleanup tasks. The returned variant map
includes the results evaluated by the algorithm.
.. note::

This method modifies the algorithm instance, so it is not safe to call
on algorithms directly retrieved from QgsProcessingRegistry and QgsProcessingProvider. Instead, a copy
of the algorithm should be created with clone() and prepare()/runPrepared() called on the copy.
:rtype: QVariantMap
%End

Expand Down Expand Up @@ -305,8 +356,25 @@ class QgsProcessingAlgorithm
:rtype: bool
%End

virtual QVariantMap processAlgorithm( const QVariantMap &parameters,
QgsProcessingContext &context, QgsProcessingFeedback *feedback ) const = 0 /VirtualErrorHandler=processing_exception_handler/;
virtual bool prepareAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) /VirtualErrorHandler=processing_exception_handler/;
%Docstring
Prepares the algorithm to run using the specified ``parameters``. Algorithms should implement
their logic for evaluating parameter values here. The evaluated parameter results should
be stored in member variables ready for a call to processAlgorithm().

The ``context`` argument specifies the context in which the algorithm is being run.

Algorithm preparation progress should be reported using the supplied ``feedback`` object. Additionally,
well-behaved algorithms should periodically check ``feedback`` to determine whether the
algorithm should be canceled and exited early.

:return: true if preparation was successful.
.. seealso:: processAlgorithm()
.. seealso:: postProcessAlgorithm()
:rtype: bool
%End

virtual bool processAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) = 0 /VirtualErrorHandler=processing_exception_handler/;
%Docstring
Runs the algorithm using the specified ``parameters``. Algorithms should implement
their custom processing logic here.
Expand All @@ -319,6 +387,27 @@ class QgsProcessingAlgorithm

:return: A map of algorithm outputs. These may be output layer references, or calculated
values such as statistical calculations.
.. seealso:: prepareAlgorithm()
.. seealso:: postProcessAlgorithm()
:rtype: bool
%End

virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) = 0 /VirtualErrorHandler=processing_exception_handler/;
%Docstring
Allows the algorithm to perform any required cleanup tasks. The returned variant map
includes the results evaluated by the algorithm. These may be output layer references, or calculated
values such as statistical calculations.

The ``context`` argument specifies the context in which the algorithm was run.

Postprocess progress should be reported using the supplied ``feedback`` object. Additionally,
well-behaved algorithms should periodically check ``feedback`` to determine whether the
post processing should be canceled and exited early.

:return: A map of algorithm outputs. These may be output layer references, or calculated
values such as statistical calculations.
.. seealso:: prepareAlgorithm()
.. seealso:: processAlgorithm()
:rtype: QVariantMap
%End

Expand Down
8 changes: 6 additions & 2 deletions python/core/processing/qgsprocessingmodelalgorithm.sip
Original file line number Diff line number Diff line change
Expand Up @@ -835,8 +835,12 @@ Copies are protected to avoid slicing

protected:

virtual QVariantMap processAlgorithm( const QVariantMap &parameters,
QgsProcessingContext &context, QgsProcessingFeedback *feedback ) const;
virtual bool prepareAlgorithm( const QVariantMap &parameters,
QgsProcessingContext &context, QgsProcessingFeedback *feedback );
virtual bool processAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback );

virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback );


};

Expand Down
Loading

0 comments on commit c2621b1

Please sign in to comment.