Skip to content
Permalink
Browse files

Expand on docs

  • Loading branch information
nyalldawson committed Jul 7, 2017
1 parent da02c9a commit 2c91df4c127770b034a6810c9fe2ffeb176f2fe0
Showing with 88 additions and 6 deletions.
  1. +44 −3 python/core/processing/qgsprocessingalgorithm.sip
  2. +44 −3 src/core/processing/qgsprocessingalgorithm.h
@@ -364,10 +364,25 @@ class QgsProcessingAlgorithm

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

prepareAlgorithm should be used to handle any thread-sensitive preparation which is required
by the algorithm. It will always be called from the same thread that ``context`` has thread
affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
will call prepareAlgorithm from the same thread as that model/script it being executed in.

Note that the processAlgorithm step uses a temporary context with affinity for the thread in
which the algorithm is executed, making it safe for processAlgorithm implementations to load
sources and sinks without issue. Implementing prepareAlgorithm is only required if special
thread safe handling is required by the algorithm.

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.

If the preparation was successful algorithms must return true. If a false value is returned
this indicates that the preparation could not be completed, and the algorithm execution
will be canceled.

:return: true if preparation was successful.
.. seealso:: processAlgorithm()
.. seealso:: postProcessAlgorithm()
@@ -379,14 +394,29 @@ class QgsProcessingAlgorithm
Runs the algorithm using the specified ``parameters``. Algorithms should implement
their custom processing logic here.

The ``context`` argument specifies the context in which the algorithm is being run.
The ``context`` argument gives a temporary context with thread affinity matching the thread
in which the algorithm is being run. This is a cut-back copy of the context passed to
the prepareAlgorithm() and postProcessAlgorithm() steps, but it is generally safe
for most algorithms to utilize this context for loading layers and creating sinks.
Any loaded layers or sinks created within this temporary context will be transferred
back to the main execution context upon successful completion of the processAlgorithm()
step.

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

This method will not be called if the prepareAlgorithm() step failed (returned false).

c++ implementations of processAlgorithm can throw the QgsProcessingException exception
to indicate that a fatal error occurred within the execution. Python based subclasses
should raise GeoAlgorithmExecutionException for the same purpose.

:return: A map of algorithm outputs. These may be output layer references, or calculated
values such as statistical calculations.
values such as statistical calculations. Unless the algorithm subclass overrides
the postProcessAlgorithm() step this returned map will be used as the output for the
algorithm.

.. seealso:: prepareAlgorithm()
.. seealso:: postProcessAlgorithm()
:rtype: QVariantMap
@@ -404,8 +434,19 @@ class QgsProcessingAlgorithm
well-behaved algorithms should periodically check ``feedback`` to determine whether the
post processing should be canceled and exited early.

postProcessAlgorithm should be used to handle any thread-sensitive cleanup which is required
by the algorithm. It will always be called from the same thread that ``context`` has thread
affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
will call postProcessAlgorithm from the same thread as that model/script it being executed in.

postProcessAlgorithm will not be called if the prepareAlgorithm() step failed (returned false),
or if an exception was raised by the processAlgorithm() step.

:return: A map of algorithm outputs. These may be output layer references, or calculated
values such as statistical calculations.
values such as statistical calculations. Implementations which return a non-empty
map will override any results returned by processAlgorithm().

.. seealso:: prepareAlgorithm()
.. seealso:: processAlgorithm()
:rtype: QVariantMap
@@ -346,10 +346,25 @@ class CORE_EXPORT QgsProcessingAlgorithm
*
* The \a context argument specifies the context in which the algorithm is being run.
*
* prepareAlgorithm should be used to handle any thread-sensitive preparation which is required
* by the algorithm. It will always be called from the same thread that \a context has thread
* affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
* algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
* will call prepareAlgorithm from the same thread as that model/script it being executed in.
*
* Note that the processAlgorithm step uses a temporary context with affinity for the thread in
* which the algorithm is executed, making it safe for processAlgorithm implementations to load
* sources and sinks without issue. Implementing prepareAlgorithm is only required if special
* thread safe handling is required by the algorithm.
*
* Algorithm preparation progress should be reported using the supplied \a feedback object. Additionally,
* well-behaved algorithms should periodically check \a feedback to determine whether the
* algorithm should be canceled and exited early.
*
* If the preparation was successful algorithms must return true. If a false value is returned
* this indicates that the preparation could not be completed, and the algorithm execution
* will be canceled.
*
* \returns true if preparation was successful.
* \see processAlgorithm()
* \see postProcessAlgorithm()
@@ -360,14 +375,29 @@ class CORE_EXPORT QgsProcessingAlgorithm
* Runs the algorithm using the specified \a parameters. Algorithms should implement
* their custom processing logic here.
*
* The \a context argument specifies the context in which the algorithm is being run.
* The \a context argument gives a temporary context with thread affinity matching the thread
* in which the algorithm is being run. This is a cut-back copy of the context passed to
* the prepareAlgorithm() and postProcessAlgorithm() steps, but it is generally safe
* for most algorithms to utilize this context for loading layers and creating sinks.
* Any loaded layers or sinks created within this temporary context will be transferred
* back to the main execution context upon successful completion of the processAlgorithm()
* step.
*
* Algorithm progress should be reported using the supplied \a feedback object. Additionally,
* well-behaved algorithms should periodically check \a feedback to determine whether the
* algorithm should be canceled and exited early.
*
* This method will not be called if the prepareAlgorithm() step failed (returned false).
*
* c++ implementations of processAlgorithm can throw the QgsProcessingException exception
* to indicate that a fatal error occurred within the execution. Python based subclasses
* should raise GeoAlgorithmExecutionException for the same purpose.
*
* \returns A map of algorithm outputs. These may be output layer references, or calculated
* values such as statistical calculations.
* values such as statistical calculations. Unless the algorithm subclass overrides
* the postProcessAlgorithm() step this returned map will be used as the output for the
* algorithm.
*
* \see prepareAlgorithm()
* \see postProcessAlgorithm()
*/
@@ -384,8 +414,19 @@ class CORE_EXPORT QgsProcessingAlgorithm
* well-behaved algorithms should periodically check \a feedback to determine whether the
* post processing should be canceled and exited early.
*
* postProcessAlgorithm should be used to handle any thread-sensitive cleanup which is required
* by the algorithm. It will always be called from the same thread that \a context has thread
* affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
* algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
* will call postProcessAlgorithm from the same thread as that model/script it being executed in.
*
* postProcessAlgorithm will not be called if the prepareAlgorithm() step failed (returned false),
* or if an exception was raised by the processAlgorithm() step.
*
* \returns A map of algorithm outputs. These may be output layer references, or calculated
* values such as statistical calculations.
* values such as statistical calculations. Implementations which return a non-empty
* map will override any results returned by processAlgorithm().
*
* \see prepareAlgorithm()
* \see processAlgorithm()
*/

0 comments on commit 2c91df4

Please sign in to comment.
You can’t perform that action at this time.