Expand on docs

Author: nyalldawson

python/core/processing/qgsprocessingalgorithm.sip

@@ -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

src/core/processing/qgsprocessingalgorithm.h

@@ -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()
      */