From 05dbd670b3e88283da59ee9270e19e3a4feb3b08 Mon Sep 17 00:00:00 2001 From: Kenneth Moreland Date: Sat, 10 Feb 2024 16:23:27 -0500 Subject: [PATCH] Add worklet error handling section to users guide --- docs/users-guide/error-handling.rst | 2 ++ docs/users-guide/part-advanced.rst | 1 + docs/users-guide/worklet-error-handling.rst | 28 +++++++++++++++++++++ 3 files changed, 31 insertions(+) create mode 100644 docs/users-guide/worklet-error-handling.rst diff --git a/docs/users-guide/error-handling.rst b/docs/users-guide/error-handling.rst index 46b083fa3..3df8f64e2 100644 --- a/docs/users-guide/error-handling.rst +++ b/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`. diff --git a/docs/users-guide/part-advanced.rst b/docs/users-guide/part-advanced.rst index 2decb7860..9e624e9c5 100644 --- a/docs/users-guide/part-advanced.rst +++ b/docs/users-guide/part-advanced.rst @@ -8,3 +8,4 @@ Advanced Development advanced-types.rst logging.rst worklet-types.rst + worklet-error-handling.rst diff --git a/docs/users-guide/worklet-error-handling.rst b/docs/users-guide/worklet-error-handling.rst new file mode 100644 index 000000000..af41cf68d --- /dev/null +++ b/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.