IMP logo
IMP Reference Guide  develop.63b38c487d,2024/12/21
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.

Copyright 2007-2022 IMP Inventors. All rights reserved.

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]messageFailure 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]exprThe assertion expression.
[in]messageWrite 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]exprThe assertion expression.
[in]messageWrite 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.