IMP logo
IMP Reference Guide  develop.e1fe35f,2019/09/16
The Integrative Modeling Platform
exception.h
Go to the documentation of this file.
1 /**
2  * \file IMP/exception.h
3  * \brief Exception definitions and assertions.
4  *
5  * Copyright 2007-2019 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPKERNEL_EXCEPTION_H
10 #define IMPKERNEL_EXCEPTION_H
11 
12 #include <IMP/kernel_config.h>
13 #include "compiler_macros.h"
14 #include "enums.h"
15 #include "nullptr.h"
16 #include "internal/base_static.h"
17 #include <string>
18 #include <stdexcept>
19 
20 IMPKERNEL_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/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 IMPKERNELEXPORT 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_KERNEL_HAS_LOG4CXX
66 IMPKERNELEXPORT 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 IMPKERNELEXPORT 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 IMPKERNELEXPORT 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 IMPKERNELEXPORT 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 IMPKERNELEXPORT 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 an invalid type being passed to \imp
145 /** The equivalent Python type also derives from Python's TypeError.
146  */
147 class IMPKERNELEXPORT TypeException : public Exception {
148  public:
149  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(TypeException);
150  TypeException(const char *t) : Exception(t) {}
151  ~TypeException() IMP_NOEXCEPT;
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 IMPKERNELEXPORT IndexException : public Exception {
158  public:
159  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(IndexException);
160  //! Create exception with an error message
161  IndexException(const char *t) : Exception(t) {}
162  ~IndexException() IMP_NOEXCEPT;
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 IMPKERNELEXPORT IOException : public Exception {
175  public:
176  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(IOException);
177  IOException(const char *t) : Exception(t) {}
178  ~IOException() IMP_NOEXCEPT;
179 };
180 
181 /** \brief An exception which is thrown when the Model has
182  attributes with invalid values.
183 
184  It may be OK to catch an \imp ModelException, when, for example,
185  the catcher can simply re-randomize the optimized coordinates and
186  restart the optimization. Sampling protocols, such as
187  IMP::core::MCCGSampler, tend to do this.
188  */
189 class IMPKERNELEXPORT ModelException : public Exception {
190  public:
191  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(ModelException);
192  //! Create exception with an error message
193  ModelException(const char *t) : Exception(t) {}
194  ~ModelException() IMP_NOEXCEPT;
195 };
196 
197 //! An exception that signifies some event occurred.
198 /** It is difficult to add exceptions to the Python wrappers,
199  so use this type if want to raise an exception when something
200  happens.
201 
202  We can add event types later via a key.
203  */
204 class IMPKERNELEXPORT EventException : public Exception {
205  public:
206  IMP_CXX11_DEFAULT_COPY_CONSTRUCTOR(EventException);
207  //! Create exception with an error message
208  EventException(const char *t = "") : Exception(t) {}
209  ~EventException() IMP_NOEXCEPT;
210 };
211 #endif
212 
213 IMPKERNEL_END_NAMESPACE
214 
215 #endif /* IMPKERNEL_EXCEPTION_H */
IndexException(const char *t)
Create exception with an error message.
Definition: exception.h:161
CheckLevel get_check_level()
Get the current audit mode.
Definition: exception.h:81
A general exception for an internal error in IMP.
Definition: exception.h:102
An exception for an invalid type being passed to IMP.
Definition: exception.h:147
An exception that signifies some event occurred.
Definition: exception.h:204
An exception for an invalid usage of IMP.
Definition: exception.h:123
ModelException(const char *t)
Create exception with an error message.
Definition: exception.h:193
An input/output exception.
Definition: exception.h:174
Provide a nullptr keyword analog.
An exception for a request for an invalid member of a container.
Definition: exception.h:157
Basic types used by IMP.
CheckLevel
Specify the level of runtime checks performed.
Definition: enums.h:53
EventException(const char *t="")
Create exception with an error message.
Definition: exception.h:208
The general base class for IMP exceptions.
Definition: exception.h:49
Various compiler workarounds.
void handle_error(const char *msg)
An exception which is thrown when the Model has attributes with invalid values.
Definition: exception.h:189
An exception for an invalid value being passed to IMP.
Definition: exception.h:137
void set_check_level(CheckLevel tf)
Control runtime checks in the code.
Definition: exception.h:73