.. SPDX-FileCopyrightText: 2021 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _onedtl_error_handling:

Error Handling
--------------

oneDTL error handling relies on the mechanism of C++ exceptions. Should an error occur, it must be propagated at the point of a function call where it must be caught using standard C++ exception handling mechanism.

.. _onedtl_exception_classification:

Exception Classification
+++++++++++++++++++++++++

Exception classification in oneDTL is aligned with C++ Standard Library classification. oneDTL implementation must introduce class that defines the base class in the hierarchy of oneDTL exception classes. All other exception classes must be derived from the base class.

This specification does not require implementations to perform error-checking. However, if an implementation does provide error-checking, it must use the exception classes below. Additional implementation-specific exception classes inherited from base class may be used for exceptional conditions not fitting any of these classes.

.. _onedtl_common_exceptions:

Common Exceptions
******************

.. csv-table::
    :header: "Exception class", "Description"
    :widths: 40, 60

    ".. _onedtl_exception:

    ``oneapi::dtl::exception``", "Abstract class, base for all other oneDTL exception classes"
    ".. _onedtl_exception_logic_error:

    ``oneapi::dtl::logic_error``", "Abstract class, base for all oneDTL exception classes on logic errors (that are a consequence of faulty logic within the program)"
    ".. _onedtl_exception_runtime_error:

    ``oneapi::dtl::runtime_error``", "Abstract class, base for all oneDTL exception classes on runtime errors (that are due to events beyond the scope of the program)"
    ".. _onedtl_exception_invalid_argument:

    ``oneapi::dtl::invalid_argument``", "Reports a problem when arguments to the routine were rejected"
    ".. _onedtl_exception_domain_error:

    ``oneapi::dtl::domain_error``", "Reports a problem when inputs are outside of the domain on which an operation is defined"
    ".. _onedtl_exception_out_of_range:

    ``oneapi::dtl::out_of_range``", "Reports a problem when there is an attempt to access element(s) out of defined range"
    ".. _onedtl_exception_range_error:

    ``oneapi::dtl::range_error``", "Reports a problem when a result of a computation cannot be represented by the destination type"
    ".. _onedtl_exception_bad_alloc:

    ``oneapi::dtl::bad_alloc``", "Base class for all oneDTL exception classes for bad allocation errors, reports a problem when an allocation function has failed to allocate storage"
    ".. _onedtl_exception_host_bad_alloc:

    ``oneapi::dtl::host_bad_alloc``", "Reports a problem that occurred during memory allocation on the host"
    ".. _onedtl_exception_device_bad_alloc:

    ``oneapi::dtl::device_bad_alloc``", "Reports a problem that occurred during memory allocation on a specific device"
    ".. _onedtl_exception_unsupported_device:

    ``oneapi::dtl::unsupported_device``", "Reports a problem when the routine is not supported on a specific device"
    ".. _onedtl_exception_unimplemented:

    ``oneapi::dtl::unimplemented``", "Reports a problem when a specific routine has not been implemented for the specified parameters"
    ".. _onedtl_exception_uninitialized:

    ``oneapi::dtl::uninitialized``", "Reports a problem when an object has not been initialized"