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