Background

The default way of Blaze to report errors of any kind is to throw a standard exception. However, although in general this approach works well, in certain environments and under special circumstances exceptions may not be the mechanism of choice and a different error reporting mechanism may be desirable. For this reason, Blaze provides several macros, which enable the customization of the error reporting mechanism. Via these macros it is possible to replace the standard exceptions by some other exception type or a completely different approach to report errors.

Customization of the Reporting Mechanism

In some cases it might be necessary to adapt the entire error reporting mechanism and to replace it by some other means to signal failure. The primary macro for this purpose is the BLAZE_THROW macro:

#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 exceptions by a call to a log() function and a direct call to abort:

#define BLAZE_THROW( EXCEPTION ) \
   log( "..." ); \
   abort()

#include <blaze/Blaze.h>

Doing this will trigger a call to log() and an abort instead of throwing an exception whenever an error (such as an invalid argument) is detected. Note that it is possible to execute several statements instead of executing a single statement to throw an exception. Also note that it is recommended to define the macro such that a subsequent semicolon is required!

Warning: This macro is provided with the intention to assist in adapting Blaze to special conditions and environments. However, the customization of the error reporting mechanism via this macro can have a significant effect on the library. Thus be advised to use the macro with due care!

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_LOGIC_ERROR( MESSAGE ) \
   BLAZE_THROW( std::logic_error( MESSAGE ) )

#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_OUT_OF_RANGE( MESSAGE ) \
   BLAZE_THROW( std::out_of_range( 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. Note that it is recommended to define the macro such that a subsequent semicolon is required!

Warning: These macros are provided with the intention to assist in adapting Blaze to special conditions and environments. However, the customization of the type of an exception via this macro may have an effect on the library. Thus be advised to use the macro with due care!

Customization of Special Errors

Last but not least it is possible to customize the error reporting for special kinds of errors. This can be achieved by customizing any number of the following macros:

#define BLAZE_THROW_DIVISION_BY_ZERO( MESSAGE ) \
   BLAZE_THROW_RUNTIME_ERROR( MESSAGE )

#define BLAZE_THROW_LAPACK_ERROR( MESSAGE ) \
   BLAZE_THROW_RUNTIME_ERROR( MESSAGE )

As explained in the previous sections, in order to customize the handling of special errors the according macro has to be defined prior to including any Blaze header file. This will override the Blaze default behavior.

Previous: Grouping/Tagging ---- Next: BLAS Functions