Provide means to adapt the error reporting mechanism

[Klaus Iglberger]

Description

The main mechanism of Blaze to report errors are exceptions. However, although in general this works well, in some environments a different error reporting mechanism can be desirable, such as for instance in massively parallel environments. Therefore, the Blaze library should provide some means to be able to adapt the error reporting mechanism in a convenient way, which enables any user to replace exceptions by some other mechanism.

Tasks

• provide a convenient way to adapt the error reporting mechanism of Blaze
• provide a full documentation of the feature
• ensure that performance is not negatively influenced

[Klaus Iglberger]

##Summary##

The feature has been implemented, tested, and documented as required. It allows both the customization of the entire error reporting mechanism as well as the customization of the exception types being thrown. It is immediately available via cloning the Blaze repository and will be officially released in Blaze 2.5.

##Customization of the Error Reporting Mechanism##

For the customization of the error reporting mechanism the BLAZE_THROW macro has been introduced:

#define BLAZE_THROW( EXCEPTION ) \
   throw EXCEPTION

This macro represents the default mechanism of the Blaze library to report errors of any kind. In order to customize the error reporing mechanism all that needs to be done is to define the macro prior to including any Blaze header file. This will cause the Blaze specific mechanism to be overridden. The following example demonstrates this by replacing throwing an exceptions by an abort:

#define BLAZE_THROW( EXCEPTION ) abort();

#include <blaze/Blaze.h>

Doing this will trigger an abort instead of throwing an exception whenever an error (such as an invalid argument) is detected.

##Customization of the Type of Exceptions##

In addition to the customization of the entire error reporting mechanism it is also possible to customize the type of exceptions being thrown. This can be achieved by customizing any number of the following macros:

#define BLAZE_THROW_BAD_ALLOC \
   BLAZE_THROW( std::bad_alloc() )

#define BLAZE_THROW_INVALID_ARGUMENT( MESSAGE ) \
   BLAZE_THROW( std::invalid_argument( MESSAGE ) )

#define BLAZE_THROW_LENGTH_ERROR( MESSAGE ) \
   BLAZE_THROW( std::length_error( MESSAGE ) )

#define BLAZE_THROW_LOGIC_ERROR( MESSAGE ) \
   BLAZE_THROW( std::logic_error( MESSAGE ) )

#define BLAZE_THROW_RUNTIME_ERROR( MESSAGE ) \
   BLAZE_THROW( std::runtime_error( MESSAGE ) )

In order to customize the type of exception the according macro has to be defined prior to including any Blaze header file. This will override the Blaze default behavior. The following example demonstrates this by replacing std::invalid_argument by a custom exception type:

class InvalidArgument
{
 public:
   InvalidArgument();
   explicit InvalidArgument( const std::string& message );
   // ...
};

#define BLAZE_THROW_INVALID_ARGUMENT( MESSAGE ) \
   BLAZE_THROW( InvalidArgument( MESSAGE ) )

#include <blaze/Blaze.h>

By manually defining the macro, an InvalidArgument exception is thrown instead of a std::invalid_argument exception.