IMP Reference Guide  develop.b708a66810,2021/08/02 The Integrative Modeling Platform
check_macros.h File Reference

Helper macros for throwing and handling exceptions. More...

#include <IMP/kernel_config.h>
#include "exception.h"
#include "compiler_macros.h"
#include <iostream>
#include <cmath>
Include dependency graph for check_macros.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros

#define IMP_ALWAYS_CHECK(condition, message, exception_name)
Throw an exception if a check fails. More...

#define IMP_CATCH_AND_TERMINATE(expr)

#define IMP_CHECK_CODE(expr)
Only compile the code if checks are enabled. More...

#define IMP_CHECK_OBJECT(obj)   IMP_UNUSED(obj)
Perform some basic validity checks on the object for memory debugging. More...

#define IMP_CHECK_OBJECT_IF_NOT_nullptr(obj)   IMP_UNUSED(obj)

#define IMP_FAILURE(message)
A runtime failure for IMP. More...

#define IMP_IF_CHECK(level)
Execute the code block if a certain level checks are on. More...

#define IMP_INTERNAL_CHECK(expr, message)
An assertion to check for internal errors in IMP. An IMP::ErrorException will be thrown. More...

#define IMP_INTERNAL_CHECK_FLOAT_EQUAL(expra, exprb, message)

#define IMP_INTERNAL_CHECK_VARIABLE(variable)

#define IMP_NOT_IMPLEMENTED
Use this to mark that the method is not implemented yet. More...

#define IMP_THROW(message, exception_name)
Throw an exception with a message. More...

#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method. More...

#define IMP_USAGE_CHECK_FLOAT_EQUAL(expra, exprb, message)

#define IMP_USAGE_CHECK_VARIABLE(variable)

## Detailed Description

Helper macros for throwing and handling exceptions.

Definition in file check_macros.h.

## Macro Definition Documentation

 #define IMP_ALWAYS_CHECK ( condition, message, exception_name )
Value:
if (!(condition)) { \
IMP_THROW(message, exception_name); \
}
#define IMP_THROW(message, exception_name)
Throw an exception with a message.
Definition: check_macros.h:50

Throw an exception if a check fails.

Do IMP_THROW() if the check as the first argument fails. Unlike IMP_USAGE_CHECK() and IMP_INTERNAL_CHECK() these checks are always present.

Definition at line 61 of file check_macros.h.

 #define IMP_CATCH_AND_TERMINATE ( expr )

Catch any IMP exception thrown by expr and terminate with an error message. Use this for basic error handling in main functions in C++. Do not use within the IMP library.

Definition at line 30 of file check_macros.h.

 #define IMP_CHECK_CODE ( expr )

Only compile the code if checks are enabled.

For example

Vector<Particle*> testp(input.begin(), input.end());
std::sort(testp.begin(), testp.end());
IMP_USAGE_CHECK(std::unique(testp.begin(), testp.end()) == testp.end(),
"Duplicate particles found in the input list.");
});

Definition at line 117 of file check_macros.h.

 #define IMP_CHECK_OBJECT ( obj ) IMP_UNUSED(obj)

Perform some basic validity checks on the object for memory debugging.

Definition at line 277 of file check_macros.h.

 #define IMP_FAILURE ( message )

A runtime failure for IMP.

Parameters
 [in] message Failure message to write. This macro is used to provide nice error messages when there is an internal error in IMP. It causes an IMP::InternalException to be thrown.

Definition at line 72 of file check_macros.h.

 #define IMP_IF_CHECK ( level )

Execute the code block if a certain level checks are on.

The next code block (delimited by { }) is executed if get_check_level() <= level.

For example:

Vector<Particle*> testp(input.begin(), input.end());
std::sort(testp.begin(), testp.end());
IMP_USAGE_CHECK(std::unique(testp.begin(), testp.end()) == testp.end(),
"Duplicate particles found in the input list.");
}

Definition at line 104 of file check_macros.h.

 #define IMP_INTERNAL_CHECK ( expr, message )

An assertion to check for internal errors in IMP. An IMP::ErrorException will be thrown.

Since it is a debug-only check and no attempt should be made to recover from it, the exception type cannot be specified.

For example:

IMP_INTERNAL_CHECK((3.14-PI) < .01,
"PI is not close to 3.14. It is instead " << PI);
Note
if the code is compiled with 'fast', or the check level is less than IMP::USAGE_AND_INTERNAL, the check is not performed. Do not use asserts as a shorthand to throw exceptions (throw the exception yourself); use them only to check for logic errors.
Parameters
 [in] expr The assertion expression. [in] message Write this message if the assertion fails.

Definition at line 139 of file check_macros.h.

 #define IMP_INTERNAL_CHECK_FLOAT_EQUAL ( expra, exprb, message )

This is like IMP_INTERNAL_CHECK, however designed to check if two floating point numbers are almost equal. The check looks something like

std::abs(a-b) < .1*(a+b)+.1

Using this makes such tests a bit easier to spot and not mess up.

Definition at line 149 of file check_macros.h.

 #define IMP_INTERNAL_CHECK_VARIABLE ( variable )

Mark a variable as one that is only used in checks. This disables unused variable warnings on it in fast mode.

Definition at line 195 of file check_macros.h.

 #define IMP_NOT_IMPLEMENTED

Use this to mark that the method is not implemented yet.

Definition at line 81 of file check_macros.h.

 #define IMP_THROW ( message, exception_name )

Throw an exception with a message.

The exception thrown must inherit from Exception and not be UsageException or InternalException as those are reserved for disableable checks (the IMP_INTERNAL_CHECK() and IMP_USAGE_CHECK() macros).

IMP_THROW("Could not open file " << file_name,
IOException);

Definition at line 50 of file check_macros.h.

 #define IMP_USAGE_CHECK ( expr, message )

A runtime test for incorrect usage of a class or method.

Parameters
 [in] expr The assertion expression. [in] message Write this message if the assertion fails.

It should be used to check arguments to function. For example

IMP_USAGE_CHECK(positive_argument >0,
"Argument positive_argument to function my_function "
<< " must be positive. Instead got " << positive_argument);
Note
if the build is 'fast', or the check level is less than IMP::USAGE, the check is not performed. Do not use these checks as a shorthand to throw necessary exceptions (throw the exception yourself); use them only to check for errors, such as inappropriate input.

Definition at line 168 of file check_macros.h.

 #define IMP_USAGE_CHECK_FLOAT_EQUAL ( expra, exprb, message )

This is like IMP_USAGE_CHECK, however designed to check if two floating point numbers are almost equal. The check looks something like

std::abs(a-b) < .1*(a+b)+.1

Using this makes such tests a bit easier to spot and not mess up.

Definition at line 178 of file check_macros.h.

 #define IMP_USAGE_CHECK_VARIABLE ( variable )

Mark a variable as one that is only used in checks. This disables unused variable warnings on it in fast mode.

Definition at line 190 of file check_macros.h.