Skip to content

Commit 2c91df4

Browse files
committed
Expand on docs
1 parent da02c9a commit 2c91df4

File tree

2 files changed

+88
-6
lines changed

2 files changed

+88
-6
lines changed

python/core/processing/qgsprocessingalgorithm.sip

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -364,10 +364,25 @@ class QgsProcessingAlgorithm
364364

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

367+
prepareAlgorithm should be used to handle any thread-sensitive preparation which is required
368+
by the algorithm. It will always be called from the same thread that ``context`` has thread
369+
affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
370+
algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
371+
will call prepareAlgorithm from the same thread as that model/script it being executed in.
372+
373+
Note that the processAlgorithm step uses a temporary context with affinity for the thread in
374+
which the algorithm is executed, making it safe for processAlgorithm implementations to load
375+
sources and sinks without issue. Implementing prepareAlgorithm is only required if special
376+
thread safe handling is required by the algorithm.
377+
367378
Algorithm preparation progress should be reported using the supplied ``feedback`` object. Additionally,
368379
well-behaved algorithms should periodically check ``feedback`` to determine whether the
369380
algorithm should be canceled and exited early.
370381

382+
If the preparation was successful algorithms must return true. If a false value is returned
383+
this indicates that the preparation could not be completed, and the algorithm execution
384+
will be canceled.
385+
371386
:return: true if preparation was successful.
372387
.. seealso:: processAlgorithm()
373388
.. seealso:: postProcessAlgorithm()
@@ -379,14 +394,29 @@ class QgsProcessingAlgorithm
379394
Runs the algorithm using the specified ``parameters``. Algorithms should implement
380395
their custom processing logic here.
381396

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

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

409+
This method will not be called if the prepareAlgorithm() step failed (returned false).
410+
411+
c++ implementations of processAlgorithm can throw the QgsProcessingException exception
412+
to indicate that a fatal error occurred within the execution. Python based subclasses
413+
should raise GeoAlgorithmExecutionException for the same purpose.
414+
388415
:return: A map of algorithm outputs. These may be output layer references, or calculated
389-
values such as statistical calculations.
416+
values such as statistical calculations. Unless the algorithm subclass overrides
417+
the postProcessAlgorithm() step this returned map will be used as the output for the
418+
algorithm.
419+
390420
.. seealso:: prepareAlgorithm()
391421
.. seealso:: postProcessAlgorithm()
392422
:rtype: QVariantMap
@@ -404,8 +434,19 @@ class QgsProcessingAlgorithm
404434
well-behaved algorithms should periodically check ``feedback`` to determine whether the
405435
post processing should be canceled and exited early.
406436

437+
postProcessAlgorithm should be used to handle any thread-sensitive cleanup which is required
438+
by the algorithm. It will always be called from the same thread that ``context`` has thread
439+
affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
440+
algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
441+
will call postProcessAlgorithm from the same thread as that model/script it being executed in.
442+
443+
postProcessAlgorithm will not be called if the prepareAlgorithm() step failed (returned false),
444+
or if an exception was raised by the processAlgorithm() step.
445+
407446
:return: A map of algorithm outputs. These may be output layer references, or calculated
408-
values such as statistical calculations.
447+
values such as statistical calculations. Implementations which return a non-empty
448+
map will override any results returned by processAlgorithm().
449+
409450
.. seealso:: prepareAlgorithm()
410451
.. seealso:: processAlgorithm()
411452
:rtype: QVariantMap

src/core/processing/qgsprocessingalgorithm.h

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -346,10 +346,25 @@ class CORE_EXPORT QgsProcessingAlgorithm
346346
*
347347
* The \a context argument specifies the context in which the algorithm is being run.
348348
*
349+
* prepareAlgorithm should be used to handle any thread-sensitive preparation which is required
350+
* by the algorithm. It will always be called from the same thread that \a context has thread
351+
* affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
352+
* algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
353+
* will call prepareAlgorithm from the same thread as that model/script it being executed in.
354+
*
355+
* Note that the processAlgorithm step uses a temporary context with affinity for the thread in
356+
* which the algorithm is executed, making it safe for processAlgorithm implementations to load
357+
* sources and sinks without issue. Implementing prepareAlgorithm is only required if special
358+
* thread safe handling is required by the algorithm.
359+
*
349360
* Algorithm preparation progress should be reported using the supplied \a feedback object. Additionally,
350361
* well-behaved algorithms should periodically check \a feedback to determine whether the
351362
* algorithm should be canceled and exited early.
352363
*
364+
* If the preparation was successful algorithms must return true. If a false value is returned
365+
* this indicates that the preparation could not be completed, and the algorithm execution
366+
* will be canceled.
367+
*
353368
* \returns true if preparation was successful.
354369
* \see processAlgorithm()
355370
* \see postProcessAlgorithm()
@@ -360,14 +375,29 @@ class CORE_EXPORT QgsProcessingAlgorithm
360375
* Runs the algorithm using the specified \a parameters. Algorithms should implement
361376
* their custom processing logic here.
362377
*
363-
* The \a context argument specifies the context in which the algorithm is being run.
378+
* The \a context argument gives a temporary context with thread affinity matching the thread
379+
* in which the algorithm is being run. This is a cut-back copy of the context passed to
380+
* the prepareAlgorithm() and postProcessAlgorithm() steps, but it is generally safe
381+
* for most algorithms to utilize this context for loading layers and creating sinks.
382+
* Any loaded layers or sinks created within this temporary context will be transferred
383+
* back to the main execution context upon successful completion of the processAlgorithm()
384+
* step.
364385
*
365386
* Algorithm progress should be reported using the supplied \a feedback object. Additionally,
366387
* well-behaved algorithms should periodically check \a feedback to determine whether the
367388
* algorithm should be canceled and exited early.
368389
*
390+
* This method will not be called if the prepareAlgorithm() step failed (returned false).
391+
*
392+
* c++ implementations of processAlgorithm can throw the QgsProcessingException exception
393+
* to indicate that a fatal error occurred within the execution. Python based subclasses
394+
* should raise GeoAlgorithmExecutionException for the same purpose.
395+
*
369396
* \returns A map of algorithm outputs. These may be output layer references, or calculated
370-
* values such as statistical calculations.
397+
* values such as statistical calculations. Unless the algorithm subclass overrides
398+
* the postProcessAlgorithm() step this returned map will be used as the output for the
399+
* algorithm.
400+
*
371401
* \see prepareAlgorithm()
372402
* \see postProcessAlgorithm()
373403
*/
@@ -384,8 +414,19 @@ class CORE_EXPORT QgsProcessingAlgorithm
384414
* well-behaved algorithms should periodically check \a feedback to determine whether the
385415
* post processing should be canceled and exited early.
386416
*
417+
* postProcessAlgorithm should be used to handle any thread-sensitive cleanup which is required
418+
* by the algorithm. It will always be called from the same thread that \a context has thread
419+
* affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
420+
* algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
421+
* will call postProcessAlgorithm from the same thread as that model/script it being executed in.
422+
*
423+
* postProcessAlgorithm will not be called if the prepareAlgorithm() step failed (returned false),
424+
* or if an exception was raised by the processAlgorithm() step.
425+
*
387426
* \returns A map of algorithm outputs. These may be output layer references, or calculated
388-
* values such as statistical calculations.
427+
* values such as statistical calculations. Implementations which return a non-empty
428+
* map will override any results returned by processAlgorithm().
429+
*
389430
* \see prepareAlgorithm()
390431
* \see processAlgorithm()
391432
*/

0 commit comments

Comments
 (0)