IMP  2.1.0
The Integrative Modeling Platform
base/exception.h
Go to the documentation of this file.
1 /**
2  * \file IMP/base/exception.h
3  * \brief Exception definitions and assertions.
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPBASE_EXCEPTION_H
10 #define IMPBASE_EXCEPTION_H
11 
12 #include <IMP/base/base_config.h>
13 #include "random.h"
14 #include "compiler_macros.h"
15 #include "enums.h"
16 #include <IMP/base/nullptr.h>
17 #include "internal/static.h"
18 #include <boost/static_assert.hpp>
19 #include <boost/type_traits.hpp>
20 #include <boost/random/uniform_real.hpp>
21 #include <cassert>
22 #include <string>
23 #include <iostream>
24 #include <new>
25 #include <sstream>
26 #include <stdexcept>
27 
28 IMPBASE_BEGIN_NAMESPACE
29 
30 #ifndef IMP_DOXYGEN
31 typedef std::runtime_error ExceptionBase;
32 #endif
33 
34 #ifndef SWIG
35 /**
36  \name Error checking and reporting
37  \anchor assert
38 
39  By default \imp performs a variety of runtime error checks. These
40  can be controlled using the IMP::set_check_level function. Call
41  IMP::set_check_level with IMP::NONE to disable all checks when you
42  are performing your optimization as opposed to testing your
43  code. Make sure you run your code with the level set to at least
44  USAGE before running your final optimization to make sure that
45  \imp is used correctly.
46 
47  Error handling is provided by IMP/base/exception.h,
48 
49  Use the \c gdbinit file provided in \c tools to automatically have \c gdb
50  break when \imp errors are detected.
51  @{
52  */
53 
54 //! The general base class for \imp exceptions
55 /** Exceptions should be used to report all errors that occur within \imp.
56 */
57 class IMPBASEEXPORT Exception
58 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
59  : public std::runtime_error
60 #endif
61  {
62  public:
63 #if defined(SWIG) || defined(IMP_DOXYGEN)
64  const char *what() const IMP_NOEXCEPT;
65 #endif
66  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(Exception);
67  Exception(const char *message);
68  ~Exception() IMP_NOEXCEPT;
69 };
70 
71 #endif
72 
73 #if !defined(SWIG) && !defined(IMP_DOXYGEN) && !IMP_BASE_HAS_LOG4CXX
74 IMPBASEEXPORT std::string get_context_message();
75 #endif
76 
77 //! Control runtime checks in the code
78 /** The default level of checks is USAGE for release builds and
79  USAGE_AND_INTERNAL for debug builds.
80 */
81 inline void set_check_level(CheckLevel tf) {
82  // cap it against the maximum supported level
83  internal::check_level = std::min<int>(tf, IMP_HAS_CHECKS);
84 }
85 
86 //! Get the current audit mode
87 /**
88  */
90 #if IMP_HAS_CHECKS
91  return CheckLevel(internal::check_level);
92 #else
93  return NONE;
94 #endif
95 }
96 
97 /** This function is called whenever IMP detects an error. It can be
98  useful to add a breakpoint in the function when using a debugger.
99 */
100 IMPBASEEXPORT void handle_error(const char *msg);
101 
102 /** @} */
103 
104 #ifndef SWIG
105 
106 //! A general exception for an intenal error in IMP.
107 /** This exception is thrown by the IMP_INTERNAL_CHECK() and
108  IMP_FAILURE() macros. It should never be caught.
109  */
110 struct IMPBASEEXPORT InternalException
111 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
112  : public std::runtime_error
113 #endif
114  {
115  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(InternalException);
116  InternalException(const char *msg = "Fatal error")
117  : std::runtime_error(msg) {}
118  ~InternalException() IMP_NOEXCEPT;
119 };
120 
121 //! An exception for an invalid usage of \imp
122 /** It is thrown by the IMP_USAGE_CHECK() macro. It should never be
123  caught internally to \imp, but it one may be able to recover from
124  it being thrown.
125 
126  \advanceddoc
127  As the usage checks are disabled in fast mode,
128  UsageExceptions are not considered part of the API and hence
129  should not be documented or checked in test cases.
130  */
131 class IMPBASEEXPORT UsageException
132 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
133  : public std::runtime_error
134 #endif
135  {
136  public:
137  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(UsageException);
138  UsageException(const char *t) : std::runtime_error(t) {}
139  ~UsageException() IMP_NOEXCEPT;
140 };
141 
142 //! An exception for an invalid value being passed to \imp
143 /** The equivalent Python type also derives from Python's ValueError.
144  */
145 class IMPBASEEXPORT ValueException : public Exception {
146  public:
147  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(ValueException);
148  ValueException(const char *t) : Exception(t) {}
149  ~ValueException() IMP_NOEXCEPT;
150 };
151 
152 //! An exception for a request for an invalid member of a container
153 /** The equivalent Python type also derives from Python's IndexError.
154  */
155 class IMPBASEEXPORT IndexException : public Exception {
156  public:
157  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(IndexException);
158  //! Create exception with an error message
159  IndexException(const char *t) : Exception(t) {}
160  ~IndexException() IMP_NOEXCEPT;
161 };
162 
163 //! An input/output exception
164 /** This exception should be used when an IO
165  operation fails in a way that leaves the internal state OK. For
166  example, failure to open a file should result in an IOException.
167 
168  It is OK to catch such exceptions in \imp.
169 
170  The equivalent Python type also derives from Python's IOError.
171  */
172 class IMPBASEEXPORT IOException : public Exception {
173  public:
174  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(IOException);
175  IOException(const char *t) : Exception(t) {}
176  ~IOException() IMP_NOEXCEPT;
177 };
178 
179 /** \brief An exception which is thrown when the kernel::Model has
180  attributes with invalid values.
181 
182  It may be OK to catch an \imp ModelException, when, for example,
183  the catcher can simply re-randomize the optimized coordinates and
184  restart the optimization. Sampling protocols, such as
185  IMP::core::MCCGSampler, tend to do this.
186  */
187 class IMPBASEEXPORT ModelException : public Exception {
188  public:
189  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(ModelException);
190  //! Create exception with an error message
191  ModelException(const char *t) : Exception(t) {}
192  ~ModelException() IMP_NOEXCEPT;
193 };
194 
195 /** \brief An exception that signifies some event occurred.
196 
197  It is difficult to add exceptions to the python wrappers,
198  so use this type if want to raise an exception when something
199  happens.
200 
201  We can add event types later via a key.
202  */
203 class IMPBASEEXPORT EventException : public Exception {
204  public:
205  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(EventException);
206  //! Create exception with an error message
207  EventException(const char *t = "") : Exception(t) {}
208  ~EventException() IMP_NOEXCEPT;
209 };
210 #endif
211 
212 IMPBASE_END_NAMESPACE
213 
214 #endif /* IMPBASE_EXCEPTION_H */
An exception for a request for an invalid member of a container.
CheckLevel
Specify the level of runtime checks performed.
Definition: base/enums.h:52
A general exception for an intenal error in IMP.
An input/output exception.
IndexException(const char *t)
Create exception with an error message.
An exception that signifies some event occurred.
void set_check_level(CheckLevel tf)
Control runtime checks in the code.
The general base class for IMP exceptions.
Random number generators used by IMP.
An exception which is thrown when the kernel::Model has attributes with invalid values.
Various compiler workarounds.
Provide a nullptr keyword analog.
EventException(const char *t="")
Create exception with an error message.
ModelException(const char *t)
Create exception with an error message.
Basic types used by IMP.
void handle_error(const char *msg)
CheckLevel get_check_level()
Get the current audit mode.
An exception for an invalid usage of IMP.
An exception for an invalid value being passed to IMP.