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

.. _oneipl_exception_classification:

Exception Classification
-------------------------

Exception classification in oneIPL is aligned with C++ Standard Library classification. 
oneIPL introduces class that defines the base class in the hierarchy of oneIPL exception classes. 
All oneIPL routines throw exceptions inherited from this base class.
In the hierarchy of oneIPL exceptions, ``oneapi::ipl::exception`` is the base class. 
All other oneIPL exception classes are derived from this base class 
and from ``std::exception`` class (or one of its child classes).

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

.. _oneipl_common_exceptions:

Common exceptions
*****************

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

    ".. _oneipl_exception:

    ``oneapi::ipl::exception``", "Abstract class, base for all other oneIPL exception classes"
    ".. _oneipl_exception_logic_error:

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

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

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

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

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

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

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

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

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

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

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

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