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