@@ -346,10 +346,25 @@ class CORE_EXPORT QgsProcessingAlgorithm
346
346
*
347
347
* The \a context argument specifies the context in which the algorithm is being run.
348
348
*
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
+ *
349
360
* Algorithm preparation progress should be reported using the supplied \a feedback object. Additionally,
350
361
* well-behaved algorithms should periodically check \a feedback to determine whether the
351
362
* algorithm should be canceled and exited early.
352
363
*
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
+ *
353
368
* \returns true if preparation was successful.
354
369
* \see processAlgorithm()
355
370
* \see postProcessAlgorithm()
@@ -360,14 +375,29 @@ class CORE_EXPORT QgsProcessingAlgorithm
360
375
* Runs the algorithm using the specified \a parameters. Algorithms should implement
361
376
* their custom processing logic here.
362
377
*
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.
364
385
*
365
386
* Algorithm progress should be reported using the supplied \a feedback object. Additionally,
366
387
* well-behaved algorithms should periodically check \a feedback to determine whether the
367
388
* algorithm should be canceled and exited early.
368
389
*
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
+ *
369
396
* \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
+ *
371
401
* \see prepareAlgorithm()
372
402
* \see postProcessAlgorithm()
373
403
*/
@@ -384,8 +414,19 @@ class CORE_EXPORT QgsProcessingAlgorithm
384
414
* well-behaved algorithms should periodically check \a feedback to determine whether the
385
415
* post processing should be canceled and exited early.
386
416
*
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
+ *
387
426
* \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
+ *
389
430
* \see prepareAlgorithm()
390
431
* \see processAlgorithm()
391
432
*/
0 commit comments