Error handling

oneDAL error handling relies on the mechanism of C++ exceptions. If an error occurs, it shall be propagated at the point of a function call where it is caught using standard C++ error handling mechanism.

Exception classification

Exception classification in oneDAL is aligned with C++ Standard Library classification. oneDAL shall introduce abstract classes that define the base class in the hierarchy of exception classes. Non-abstract exception classes are derived from the respective C++ Standard Library exception classes. oneDAL shall throw exceptions represented with non-abstract classes.

In the hierarchy of oneDAL exceptions, oneapi::dal::exception is the base abstract class that all other exception classes are derived from.

class oneapi::dal::exception;

Exception	Description	Abstract
oneapi::dal::exception	The base class of oneDAL exception hierarchy.	Yes

All oneDAL exceptions shall be divided into three groups:

• logic errors

• runtime errors

• errors with allocation

class oneapi::dal::logic_error : public oneapi::dal::exception;
class oneapi::dal::runtime_error : public oneapi::dal::exception;
class oneapi::dal::bad_alloc :  public oneapi::dal::exception, public std::bad_alloc;

Exception	Description	Abstract
oneapi::dal::logic_error	Reports violations of preconditions and invariants.	Yes
oneapi::dal::runtime_error	Reports violations of postconditions and other errors happened during the execution of oneDAL functionality.	Yes
oneapi::dal::bad_alloc	Reports failure to allocate storage.	Yes

All precondition and invariant errors represented by oneapi::dal::logic_error shall be divided into the following groups:

• invalid argument errors

• domain errors

• out of range errors

• errors with an unimplemented method or algorithm

• unsupported device

class oneapi::dal::invalid_argument :  public oneapi::dal::logic_error, public std::invalid_argument;
class oneapi::dal::domain_error :  public oneapi::dal::logic_error, public std::domain_error;
class oneapi::dal::out_of_range :  public oneapi::dal::logic_error, public std::out_of_range;
class oneapi::dal::unimplemented :  public oneapi::dal::logic_error, public std::logic_error;
class oneapi::dal::unsupported_device :  public oneapi::dal::logic_error, public std::logic_error;

Exception	Description	Abstract
oneapi::dal::invalid_argument	Reports situations when the argument was not accepted.	No
oneapi::dal::domain_error	Reports situations when the argument is outside of the domain on which the operation is defined. Higher priority than oneapi::dal::invalid_argument.	No
oneapi::dal::out_of_range	Reports situations when the index is out of range. Higher priority than oneapi::dal::invalid_argument.	No
oneapi::dal::unimplemented	Reports errors that arise because an algorithm or a method is not implemented.	No
oneapi::dal::unsupported_device	Reports situations when a device is not supported.	No

Errors that occur during the execution of oneDAL functionality are represented with oneapi::dal::runtime_error. Two main groups of errors shall be distinguished:

• errors in the destination type range

• errors in the OS facilities interaction

All other errors are reported via oneapi::dal::internal_error.

class oneapi::dal::range_error :  public oneapi::dal::runtime_error, public std::range_error;
class oneapi::dal::system_error :  public oneapi::dal::runtime_error, public std::system_error;
class oneapi::dal::internal_error :  public oneapi::dal::runtime_error, public std::runtime_error;

Exception	Description	Abstract
oneapi::dal::range_error	Reports situations where a result of a computation cannot be represented by the destination type.	No
oneapi::dal::system_error	Reports errors occurred during interaction with OS facilities.	No
oneapi::dal::internal_error	Reports all runtime errors that could not be assigned to other inheritors.	No

All memory allocation errors are represented by oneapi::dal::bad_alloc. They shall be divided into two groups based on where they occur:

• Host memory allocation error

• Device memory allocation error

class oneapi::dal::host_bad_alloc :  public oneapi::dal::bad_alloc;
class oneapi::dal::device_bad_alloc :  public oneapi::dal::bad_alloc;

Exception	Description	Abstract
oneapi::dal::host_bad_alloc	Reports failure to allocate storage on the host.	No
oneapi::dal::device_bad_alloc	Reports failure to allocate storage on the device.	No