Merge topic 'guide-worklet-errors'

05dbd670b Add worklet error handling section to users guide

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Vicente Bolea <vicente.bolea@kitware.com>
Merge-request: !3196

docs/users-guide/error-handling.rst

@@ -67,6 +67,8 @@ It takes a single argument that is a condition that is expected to be true.
 If it is not true, the program is halted and a message is printed.
 Asserts are useful debugging tools to ensure that software is behaving and being used as expected.
 
+.. doxygendefine:: VTKM_ASSERT
+
 .. load-example:: Assert
    :file: GuideExampleErrorHandling.cxx
    :caption: Using :c:macro:`VTKM_ASSERT`.

docs/users-guide/part-advanced.rst

@@ -8,3 +8,4 @@ Advanced Development
    advanced-types.rst
    logging.rst
    worklet-types.rst
+   worklet-error-handling.rst

docs/users-guide/worklet-error-handling.rst

@@ -0,0 +1,28 @@
+==============================
+Worklet Error Handling
+==============================
+
+.. index::
+   double: worklet; error handling
+   double: execution environment; errors
+
+It is sometimes the case during the execution of an algorithm that an error condition can occur that causes the computation to become invalid.
+At such a time, it is important to raise an error to alert the calling code of the problem.
+Since |VTKm| uses an exception mechanism to raise errors, we want an error in the execution environment to throw an exception.
+
+However, throwing exceptions in a parallel algorithm is problematic.
+Some accelerator architectures, like CUDA, do not even support throwing exceptions.
+Even on architectures that do support exceptions, throwing them in a thread block can cause problems.
+An exception raised in one thread may or may not be thrown in another, which increases the potential for deadlocks, and it is unclear how uncaught exceptions progress through thread blocks.
+
+|VTKm| handles this problem by using a flag and check mechanism.
+When a worklet (or other subclass of :class:`vtkm::exec::FunctorBase`) encounters an error, it can call its :func:`vtkm::exec::FunctorBase::RaiseError` method to flag the problem and record a message for the error.
+Once all the threads terminate, the scheduler checks for the error, and if one exists it throws a \vtkmcont{ErrorExecution} exception in the control environment.
+Thus, calling :func:`vtkm::exec::FunctorBase::RaiseError` looks like an exception was thrown from the perspective of the control environment code that invoked it.
+
+.. load-example:: ExecutionErrors
+   :file: GuideExampleErrorHandling.cxx
+   :caption: Raising an error in the execution environment.
+
+It is also worth noting that the :c:macro:`VTKM_ASSERT` macro described in :secref:`error-handling:Asserting Conditions` also works within worklets and other code running in the execution environment.
+Of course, a failed assert will terminate execution rather than just raise an error so is best for checking invalid conditions for debugging purposes.