error.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration |
5  \\ / A nd | Copyright (C) 2004-2011, 2015-2018 OpenCFD Ltd.
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8  | Copyright (C) 2011-2015 OpenFOAM Foundation
9 -------------------------------------------------------------------------------
10 License
11  This file is part of OpenFOAM.
12 
13  OpenFOAM is free software: you can redistribute it and/or modify it
14  under the terms of the GNU General Public License as published by
15  the Free Software Foundation, either version 3 of the License, or
16  (at your option) any later version.
17 
18  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
19  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
20  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21  for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
25 
26 Class
27  Foam::error
28 
29 Description
30  Class to handle errors and exceptions in a simple, consistent stream-based
31  manner.
32 
33  The error class is globally instantiated with a title string. Errors,
34  messages and other data are piped to the messageStream class in the
35  standard manner. Manipulators are supplied for exit and abort that may
36  terminate the program or throw an exception depending on whether the
37  exception handling has been switched on (off by default).
38 
39 Usage
40  \code
41  error << "message1" << "message2" << FoamDataType << exit(errNo);
42  error << "message1" << "message2" << FoamDataType << abort();
43  \endcode
44 
45 SourceFiles
46  error.C
47 
48 \*---------------------------------------------------------------------------*/
49 
50 #ifndef error_H
51 #define error_H
52 
53 #include "messageStream.H"
54 
55 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
56 
57 namespace Foam
58 {
59 
60 /*---------------------------------------------------------------------------*\
61  Class error Declaration
62 \*---------------------------------------------------------------------------*/
63 
64 class error
65 :
66  public std::exception,
67  public messageStream
68 {
69 
70 protected:
71 
72  // Protected data
73 
74  string functionName_;
77 
80 
81 
82 public:
83 
84  // Constructors
85 
86  //- Construct from title string
87  error(const string& title);
88 
89  //- Construct from dictionary
90  error(const dictionary& errDict);
91 
92  //- Construct as copy
93  error(const error& err);
94 
95 
96  //- Destructor
97  virtual ~error() throw();
98 
99 
100  // Static Member Functions
101 
102  //- Emit warning on stderr about something being old.
103  // \param what description for the warning
104  // \param version is the old version (YYMM) for determining the
105  // age in months compared to the current OpenFOAM version
106  // as conveyed by the \c OPENFOAM compiler define.
107  static void warnAboutAge(const char* what, const int version);
108 
109 
110  // Member Functions
111 
112  string message() const;
113 
114  //- Clear any messages
115  void clear() const;
116 
117  inline const string& functionName() const
118  {
119  return functionName_;
120  }
121 
122  inline const string& sourceFileName() const
123  {
124  return sourceFileName_;
125  }
126 
127  inline label sourceFileLineNumber() const
128  {
129  return sourceFileLineNumber_;
130  }
131 
132  //- Return the current exception throwing (on or off)
133  inline bool throwing() const
134  {
135  return throwExceptions_;
136  }
137 
138  //- Activate/deactivate exception throwing
139  // \return the previous throwing state
140  inline bool throwExceptions(bool doThrow)
141  {
142  const bool prev = throwExceptions_;
143  throwExceptions_ = doThrow;
144  return prev;
145  }
146 
147  //- Activate exception throwing
148  // \return the previous throwing state
149  inline bool throwExceptions()
150  {
151  return throwExceptions(true);
152  }
153 
154  //- Deactivate exception throwing
155  // \return the previous throwing state
156  inline bool dontThrowExceptions()
157  {
158  return throwExceptions(false);
159  }
160 
161  //- Convert to OSstream
162  // Prints basic message and returns OSstream for further info.
163  OSstream& operator()
164  (
165  const char* functionName,
166  const char* sourceFileName,
167  const int sourceFileLineNumber = 0
168  );
169 
170  //- Convert to OSstream
171  // Prints basic message and returns OSstream for further info.
172  OSstream& operator()
173  (
174  const string& functionName,
175  const char* sourceFileName,
176  const int sourceFileLineNumber = 0
177  );
178 
179  //- Convert to OSstream
180  // Prints basic message and returns OSstream for further info.
181  operator OSstream&();
182 
183  //- Explicitly convert to OSstream for << operations
185  {
186  return operator OSstream&();
187  }
188 
189  //- Create and return a dictionary representation of the error
190  operator dictionary() const;
191 
192 
193  //- Helper function to print a stack (if OpenFOAM IO not yet
194  // initialised)
195  static void safePrintStack(std::ostream& os);
196 
197  //- Helper function to print a stack
198  static void printStack(Ostream& os);
199 
200  //- Exit : can be called for any error to exit program.
201  // Prints stack before exiting.
202  void exit(const int errNo = 1);
203 
204  //- Abort : used to stop code for fatal errors.
205  // Prints stack before exiting.
206  void abort();
207 
208  //- Print error message
209  void write(Ostream& os, const bool includeTitle = true) const;
210 };
211 
212 
213 /*---------------------------------------------------------------------------*\
214  Class IOerror Declaration
215 \*---------------------------------------------------------------------------*/
216 
217 //- Report an I/O error
218 class IOerror
219 :
220  public error
221 {
222  // Private data
223 
224  string ioFileName_;
225  label ioStartLineNumber_;
226  label ioEndLineNumber_;
227 
228 
229 public:
230 
231  // Constructors
232 
233  //- Construct from title string
234  IOerror(const string& title);
235 
236  //- Construct from dictionary
237  IOerror(const dictionary& errDict);
238 
239 
240  //- Destructor
241  virtual ~IOerror() throw();
242 
243 
244  // Member functions
245 
246  inline const string& ioFileName() const
247  {
248  return ioFileName_;
249  }
250 
251  inline label ioStartLineNumber() const
252  {
253  return ioStartLineNumber_;
254  }
255 
256  inline label ioEndLineNumber() const
257  {
258  return ioEndLineNumber_;
259  }
260 
261  //- Convert to OSstream
262  // Prints basic message and returns OSstream for further info.
263  OSstream& operator()
264  (
265  const char* functionName,
266  const char* sourceFileName,
267  const int sourceFileLineNumber,
268  const string& ioFileName,
269  const label ioStartLineNumber = -1,
270  const label ioEndLineNumber = -1
271  );
272 
273  //- Convert to OSstream
274  // Prints basic message and returns OSstream for further info.
275  OSstream& operator()
276  (
277  const char* functionName,
278  const char* sourceFileName,
279  const int sourceFileLineNumber,
280  const IOstream&
281  );
282 
283  //- Convert to OSstream
284  // Prints basic message and returns OSstream for further info.
285  OSstream& operator()
286  (
287  const char* functionName,
288  const char* sourceFileName,
289  const int sourceFileLineNumber,
290  const dictionary&
291  );
292 
293  //- Print basic message and exit. Uses cerr if streams not constructed
294  // yet (at startup). Use in startup parsing instead of FatalError.
295  static void SafeFatalIOError
296  (
297  const char* functionName,
298  const char* sourceFileName,
299  const int sourceFileLineNumber,
300  const IOstream&,
301  const string& msg
302  );
303 
304  //- Create and return a dictionary representation of the error
305  operator dictionary() const;
306 
307 
308  //- Exit : can be called for any error to exit program
309  void exit(const int errNo = 1);
310 
311  //- Abort : used to stop code for fatal errors
312  void abort();
313 
314  //- Print error message
315  void write(Ostream& os, const bool includeTitle = true) const;
316 };
317 
318 
319 // * * * * * * * * * * * * * * * Global Operators * * * * * * * * * * * * * //
320 
321 //- Ostream operator
322 Ostream& operator<<(Ostream& os, const error& err);
323 
324 //- Ostream operator
325 Ostream& operator<<(Ostream& os, const IOerror& err);
326 
327 
328 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
329 // Global error declarations: defined in error.C
330 
331 //- Error stream (uses stdout - output on all processes),
332 //- with additional 'FOAM FATAL ERROR' header text and stack trace.
333 extern error FatalError;
334 
335 //- Error stream (uses stdout - output on all processes),
336 //- with additional 'FOAM FATAL IO ERROR' header text and stack trace.
337 extern IOerror FatalIOError;
338 
339 
340 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
341 
342 } // End namespace Foam
343 
344 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
345 // Convenience macros to add the file name and line number to the function name
346 
347 //- Report an error message using Foam::FatalError
348 // for functionName in file __FILE__ at line __LINE__
349 #define FatalErrorIn(functionName) \
350  ::Foam::FatalError((functionName), __FILE__, __LINE__)
351 
352 //- Report an error message using Foam::FatalError
353 // for FUNCTION_NAME in file __FILE__ at line __LINE__
354 #define FatalErrorInFunction FatalErrorIn(FUNCTION_NAME)
355 
356 
357 //- Report an error message using Foam::FatalIOError
358 // for functionName in file __FILE__ at line __LINE__
359 // for a particular IOstream
360 #define FatalIOErrorIn(functionName, ios) \
361  ::Foam::FatalIOError((functionName), __FILE__, __LINE__, (ios))
362 
363 //- Report an error message using Foam::FatalIOError
364 // for FUNCTION_NAME in file __FILE__ at line __LINE__
365 // for a particular IOstream
366 #define FatalIOErrorInFunction(ios) FatalIOErrorIn(FUNCTION_NAME, ios)
367 
368 
369 //- Report an error message using Foam::FatalIOError
370 // (or cerr if FatalIOError not yet constructed)
371 // for functionName in file __FILE__ at line __LINE__
372 // for a particular IOstream
373 #define SafeFatalIOErrorIn(functionName, ios, msg) \
374  ::Foam::IOerror::SafeFatalIOError \
375  ((functionName), __FILE__, __LINE__, (ios), (msg))
376 
377 //- Report an error message using Foam::FatalIOError
378 // (or cerr if FatalIOError not yet constructed)
379 // for functionName in file __FILE__ at line __LINE__
380 // for a particular IOstream
381 #define SafeFatalIOErrorInFunction(ios, msg) \
382  SafeFatalIOErrorIn(FUNCTION_NAME, ios, msg)
383 
384 
385 //- Issue a FatalErrorIn for a function not currently implemented.
386 // The functionName is printed and then abort is called.
387 //
388 // This macro can be particularly useful when methods must be defined to
389 // complete the interface of a derived class even if they should never be
390 // called for this derived class.
391 #define notImplemented(functionName) \
392  FatalErrorIn(functionName) \
393  << "Not implemented" << ::Foam::abort(FatalError);
394 
395 //- Issue a FatalErrorIn for a function not currently implemented.
396 // The FUNCTION_NAME is printed and then abort is called.
397 //
398 // This macro can be particularly useful when methods must be defined to
399 // complete the interface of a derived class even if they should never be
400 // called for this derived class.
401 #define NotImplemented notImplemented(FUNCTION_NAME)
402 
403 
404 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
405 
406 #include "errorManip.H"
407 
408 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
409 
410 #endif
411 
412 // ************************************************************************* //
Foam::IOerror::ioEndLineNumber
label ioEndLineNumber() const
Definition: error.H:255
Foam::error::sourceFileName
const string & sourceFileName() const
Definition: error.H:121
Foam::error::printStack
static void printStack(Ostream &os)
Helper function to print a stack.
Definition: dummyPrintStack.C:36
Foam::error::dontThrowExceptions
bool dontThrowExceptions()
Deactivate exception throwing.
Definition: error.H:155
Foam::IOerror::abort
void abort()
Abort : used to stop code for fatal errors.
Definition: IOerror.C:215
Foam::error::throwExceptions
bool throwExceptions()
Activate exception throwing.
Definition: error.H:148
Foam::messageStream
Class to handle messaging in a simple, consistent stream-based manner.
Definition: messageStream.H:70
Foam::error::sourceFileName_
string sourceFileName_
Definition: error.H:74
Foam::IOerror::IOerror
IOerror(const string &title)
Construct from title string.
Definition: IOerror.C:37
Foam::IOstream
An IOstream is an abstract base class for all input/output systems; be they streams,...
Definition: IOstream.H:74
Foam::IOerror::ioStartLineNumber
label ioStartLineNumber() const
Definition: error.H:250
Foam::error::functionName
const string & functionName() const
Definition: error.H:116
SafeFatalIOErrorIn
#define SafeFatalIOErrorIn(functionName, ios, msg)
Report an error message using Foam::FatalIOError.
Definition: error.H:372
Foam::FatalIOError
IOerror FatalIOError
Foam::error::throwing
bool throwing() const
Return the current exception throwing (on or off)
Definition: error.H:132
NotImplemented
#define NotImplemented
Issue a FatalErrorIn for a function not currently implemented.
Definition: error.H:400
Foam::IOerror::ioFileName
const string & ioFileName() const
Definition: error.H:245
Foam::error::error
error(const string &title)
Construct from title string.
Definition: error.C:73
Foam::label
intWM_LABEL_SIZE_t label
A label is an int32_t or int64_t as specified by the pre-processor macro WM_LABEL_SIZE.
Definition: label.H:61
Foam::error::throwExceptions_
bool throwExceptions_
Definition: error.H:77
Foam::IOerror::~IOerror
virtual ~IOerror()
Destructor.
Definition: IOerror.C:57
notImplemented
#define notImplemented(functionName)
Issue a FatalErrorIn for a function not currently implemented.
Definition: error.H:390
FatalIOErrorIn
#define FatalIOErrorIn(functionName, ios)
Report an error message using Foam::FatalIOError.
Definition: error.H:359
Foam::IOerror::SafeFatalIOError
static void SafeFatalIOError(const char *functionName, const char *sourceFileName, const int sourceFileLineNumber, const IOstream &, const string &msg)
Print basic message and exit. Uses cerr if streams not constructed.
Definition: IOerror.C:123
Foam::OSstream
Generic output stream.
Definition: OSstream.H:53
SafeFatalIOErrorInFunction
#define SafeFatalIOErrorInFunction(ios, msg)
Report an error message using Foam::FatalIOError.
Definition: error.H:380
Foam::FatalError
error FatalError
Foam::dictionary
A list of keyword definitions, which are a keyword followed by a number of values (eg,...
Definition: dictionary.H:120
Foam::error::message
string message() const
Definition: error.C:202
Foam::error::sourceFileLineNumber_
label sourceFileLineNumber_
Definition: error.H:75
Foam
Namespace for OpenFOAM.
Definition: atmBoundaryLayer.C:32
Foam::error::exit
void exit(const int errNo=1)
Exit : can be called for any error to exit program.
Definition: error.C:214
Foam::foamVersion::version
const std::string version
OpenFOAM version (name or stringified number) as a std::string.
messageStream.H
Foam::error::operator()
OSstream & operator()()
Explicitly convert to OSstream for << operations.
Definition: error.H:183
Foam::error::functionName_
string functionName_
Definition: error.H:73
Foam::error::sourceFileLineNumber
label sourceFileLineNumber() const
Definition: error.H:126
Foam::error::~error
virtual ~error()
Destructor.
Definition: error.C:130
Foam::IOerror::exit
void exit(const int errNo=1)
Exit : can be called for any error to exit program.
Definition: IOerror.C:178
Foam::error::warnAboutAge
static void warnAboutAge(const char *what, const int version)
Emit warning on stderr about something being old.
Definition: error.C:38
Foam::error::abort
void abort()
Abort : used to stop code for fatal errors.
Definition: error.C:251
Foam::IOerror::write
void write(Ostream &os, const bool includeTitle=true) const
Print error message.
Definition: IOerror.C:262
Foam::OStringStream
Output to string buffer, using a OSstream.
Definition: StringStream.H:187
Foam::error::messageStreamPtr_
OStringStream * messageStreamPtr_
Definition: error.H:78
Foam::error::clear
void clear() const
Clear any messages.
Definition: error.C:208
FUNCTION_NAME
#define FUNCTION_NAME
Definition: messageStream.H:256
Foam::messageStream::title
const string & title() const
Return the title of this error type.
Definition: messageStream.H:127
errorManip.H
Foam::IOerror
Report an I/O error.
Definition: error.H:217
FatalErrorIn
#define FatalErrorIn(functionName)
Report an error message using Foam::FatalError.
Definition: error.H:348
Foam::error::write
void write(Ostream &os, const bool includeTitle=true) const
Print error message.
Definition: error.C:298
Foam::Ostream
An Ostream is an abstract base class for all output systems (streams, files, token lists,...
Definition: Ostream.H:55
Foam::error
Class to handle errors and exceptions in a simple, consistent stream-based manner.
Definition: error.H:63
Foam::operator<<
Ostream & operator<<(Ostream &, const boundaryPatch &)
Definition: boundaryPatch.C:102
Foam::error::safePrintStack
static void safePrintStack(std::ostream &os)
Helper function to print a stack (if OpenFOAM IO not yet.
Definition: dummyPrintStack.C:32