mirror of
https://gitlab.kitware.com/vtk/vtk-m
synced 2024-10-05 01:49:02 +00:00
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
This commit is contained in:
commit
716bfb6f90
@ -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.
|
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.
|
Asserts are useful debugging tools to ensure that software is behaving and being used as expected.
|
||||||
|
|
||||||
|
.. doxygendefine:: VTKM_ASSERT
|
||||||
|
|
||||||
.. load-example:: Assert
|
.. load-example:: Assert
|
||||||
:file: GuideExampleErrorHandling.cxx
|
:file: GuideExampleErrorHandling.cxx
|
||||||
:caption: Using :c:macro:`VTKM_ASSERT`.
|
:caption: Using :c:macro:`VTKM_ASSERT`.
|
||||||
|
@ -8,3 +8,4 @@ Advanced Development
|
|||||||
advanced-types.rst
|
advanced-types.rst
|
||||||
logging.rst
|
logging.rst
|
||||||
worklet-types.rst
|
worklet-types.rst
|
||||||
|
worklet-error-handling.rst
|
||||||
|
28
docs/users-guide/worklet-error-handling.rst
Normal file
28
docs/users-guide/worklet-error-handling.rst
Normal file
@ -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.
|
Loading…
Reference in New Issue
Block a user