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