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 | www.openfoam.com
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8  Copyright (C) 2011-2015 OpenFOAM Foundation
9  Copyright (C) 2015-2021 OpenCFD Ltd.
10 -------------------------------------------------------------------------------
11 License
12  This file is part of OpenFOAM.
13 
14  OpenFOAM is free software: you can redistribute it and/or modify it
15  under the terms of the GNU General Public License as published by
16  the Free Software Foundation, either version 3 of the License, or
17  (at your option) any later version.
18 
19  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
20  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
21  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22  for more details.
23 
24  You should have received a copy of the GNU General Public License
25  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
26 
27 Class
28  Foam::error
29 
30 Description
31  Class to handle errors and exceptions in a simple, consistent stream-based
32  manner.
33 
34  The error class is globally instantiated with a title string. Errors,
35  messages and other data are piped to the messageStream class in the
36  standard manner. Manipulators are supplied for exit and abort that may
37  terminate the program or throw an exception depending on whether the
38  exception handling has been switched on (off by default).
39 
40 Usage
41  \code
42  error << "message1" << "message2" << FoamDataType << exit(errNo);
43  error << "message1" << "message2" << FoamDataType << abort();
44  \endcode
45 
46 SourceFiles
47  error.C
48  IOerror.C
49 
50 SeeAlso
51  Foam::errorManip
52  Foam::errorManipArg
53 
54 \*---------------------------------------------------------------------------*/
55 
56 #ifndef error_H
57 #define error_H
58 
59 #include "messageStream.H"
60 #include <memory>
61 
62 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
63 
64 namespace Foam
65 {
66 
67 // Forward Declarations
68 class OStringStream;
69 
70 /*---------------------------------------------------------------------------*\
71  Class error Declaration
72 \*---------------------------------------------------------------------------*/
73 
74 class error
75 :
76  public std::exception,
77  public messageStream
78 {
79  // Private Member Functions
80 
81  //- Exit or abort code, with exception and jobinfo handling
82  void exiting(const int errNo, const bool isAbort);
83 
84 
85 protected:
86 
87  // Protected Data
88 
89  string functionName_;
92  bool throwing_;
93  std::unique_ptr<OStringStream> messageStreamPtr_;
94 
95 
96  // Protected Member Functions
97 
98  //- Exit or abort, without throwing or job control handling
99  void simpleExit(const int errNo, const bool isAbort);
100 
101 
102 public:
103 
104  // Constructors
105 
106  //- Construct from title string
107  explicit error(const string& title);
108 
109  //- Construct from dictionary
110  explicit error(const dictionary& errDict);
111 
112  //- Copy construct
113  error(const error& err);
114 
115 
116  //- Destructor
117  virtual ~error() noexcept;
118 
119 
120  // Static Functions
121 
122  //- Like Pstream::master but with a Pstream::parRun guard in case
123  //- Pstream has not yet been initialised.
124  //
125  // \param communicator is the numbered MPI communicator.
126  // By default it uses UPstream::worldComm
127  static bool master(const label communicator = -1);
128 
129  //- Test if an age warning should be emitted.
130  // \param version is the old version (YYMM) for determining the
131  // age in months compared to the current OpenFOAM version
132  // as conveyed by the \c foamVersion::api value.
133  static bool warnAboutAge(const int version) noexcept;
134 
135  //- Emit warning on stderr about something being old.
136  // \param what description for the warning
137  // \param version is the old version (YYMM) for determining the
138  // age in months compared to the current OpenFOAM version
139  // as conveyed by the \c foamVersion::api value.
140  static bool warnAboutAge(const char* what, const int version);
141 
142 
143  // Member Functions
144 
145  //- The accumulated error message
146  string message() const;
147 
148  //- Clear any messages
149  void clear() const;
150 
151  //- The currently defined function name for output messages
152  const string& functionName() const noexcept
153  {
154  return functionName_;
155  }
156 
157  //- The currently defined source-file name for output messages
158  const string& sourceFileName() const noexcept
159  {
160  return sourceFileName_;
161  }
162 
163  //- The currently defined source-file line number for output messages
164  label sourceFileLineNumber() const noexcept
165  {
166  return sourceFileLineNumber_;
167  }
168 
169  //- Return the current exception throwing state (on or off)
170  bool throwing() const noexcept
171  {
172  return throwing_;
173  }
174 
175  //- Specify exception throwing state (on or off)
176  // \return the previous throwing state
177  bool throwing(const bool on) noexcept
178  {
179  bool old(throwing_);
180  throwing_ = on;
181  return old;
182  }
183 
184 
185  // Output
186 
187  //- Return OSstream for output operations
188  OSstream& stream();
189 
190  //- Implicit cast to OSstream for << operations
191  operator OSstream&()
192  {
193  return this->stream();
194  }
195 
196  //- Explicit convert to OSstream for << operations
198  {
199  return this->stream();
200  }
201 
202  //- Define basic print message
203  // \return OSstream for further operations
204  OSstream& operator()
205  (
206  const string& functionName
207  );
208 
209  //- Define basic print message
210  // \return OSstream for further operations
211  OSstream& operator()
212  (
213  const char* functionName,
214  const char* sourceFileName,
215  const int sourceFileLineNumber = 0
216  );
217 
218  //- Define basic print message
219  // \return OSstream for further operations
220  OSstream& operator()
221  (
222  const string& functionName,
223  const char* sourceFileName,
224  const int sourceFileLineNumber = 0
225  );
226 
227 
228  // Other
229 
230  //- Extract a dictionary representation of the error information
231  operator dictionary() const;
232 
233 
234  //- Helper function to print a stack,
235  //- used when OpenFOAM IO not yet initialised.
236  static void safePrintStack(std::ostream& os);
237 
238  //- Helper function to print a stack
239  static void printStack(Ostream& os);
240 
241  //- True if FOAM_ABORT is on.
242  static bool useAbort();
243 
244 
245  //- Exit : can be called for any error to exit program.
246  // Redirects to abort() when FOAM_ABORT is on.
247  void exit(const int errNo = 1);
248 
249  //- Abort : used to stop code for fatal errors.
250  // Prints stack before exiting.
251  void abort();
252 
253  //- Print error message
254  virtual void write(Ostream& os, const bool withTitle = true) const;
255 
256 
257  // Housekeeping
258 
259  //- Specify exception throwing state (default is \b on)
260  // \return the previous throwing state
261  bool throwExceptions(const bool on = true) noexcept
262  {
263  return throwing(on);
264  }
265 
266  //- Deactivate exception throwing
267  // \return the previous throwing state
268  bool dontThrowExceptions() noexcept
269  {
270  return throwExceptions(false);
271  }
272 };
273 
274 
275 /*---------------------------------------------------------------------------*\
276  Class IOerror Declaration
277 \*---------------------------------------------------------------------------*/
278 
279 //- Report an I/O error
280 class IOerror
281 :
282  public error
283 {
284  // Private Data
285 
286  string ioFileName_;
287  label ioStartLineNumber_;
288  label ioEndLineNumber_;
289 
290 
291  // Private Member Functions
292 
293  //- Exit or abort code, with exception and jobinfo handling
294  void exiting(const int errNo, const bool isAbort);
295 
296 
297 public:
298 
299  // Constructors
300 
301  //- Construct from title string
302  explicit IOerror(const string& title);
303 
304  //- Construct from dictionary
305  explicit IOerror(const dictionary& errDict);
306 
307 
308  //- Destructor
309  virtual ~IOerror() noexcept;
310 
311 
312  // Member Functions
313 
314  //- The currently defined IO name for output messages
315  const string& ioFileName() const noexcept
316  {
317  return ioFileName_;
318  }
319 
320  //- The currently defined IO start-line number for output messages
321  label ioStartLineNumber() const noexcept
322  {
323  return ioStartLineNumber_;
324  }
325 
326  //- The currently defined IO end-line number
327  label ioEndLineNumber() const noexcept
328  {
329  return ioEndLineNumber_;
330  }
331 
332 
333  // Output
334 
335  //- Define basic print message
336  // \return OSstream for further operations
337  OSstream& operator()
338  (
339  const char* functionName,
340  const char* sourceFileName,
341  const int sourceFileLineNumber,
342  const string& ioFileName,
343  const label ioStartLineNumber = -1,
344  const label ioEndLineNumber = -1
345  );
346 
347  //- Define basic print message for IO stream
348  // \return OSstream for further operations
349  OSstream& operator()
350  (
351  const char* functionName,
352  const char* sourceFileName,
353  const int sourceFileLineNumber,
354  const IOstream& ioStream
355  );
356 
357  //- Define basic print message for dictionary entries.
358  //- Uses the dictionary::relativeName() on output.
359  // \return OSstream for further operations
360  OSstream& operator()
361  (
362  const char* functionName,
363  const char* sourceFileName,
364  const int sourceFileLineNumber,
365  const dictionary& dict
366  );
367 
368 
369  //- Define basic print message for IO stream,
370  //- independent of a source-file reference.
371  //- Uses the dictionary::relativeName() on output.
372  // \return OSstream for further operations
373  OSstream& operator()
374  (
375  const std::string& where,
376  const IOstream& ioStream
377  );
378 
379  //- Define basic print message for dictionary entries,
380  //- independent of a source-file reference.
381  //- Uses the dictionary::relativeName() on output.
382  // \return OSstream for further operations
383  OSstream& operator()
384  (
385  const std::string& where,
386  const dictionary& dict
387  );
388 
389 
390  //- Print basic message and exit.
391  // Uses cerr if streams not yet constructed (at startup).
392  // Use in startup parsing instead of FatalError.
393  static void SafeFatalIOError
394  (
395  const char* functionName,
396  const char* sourceFileName,
397  const int sourceFileLineNumber,
398  const IOstream& ioStream,
399  const string& msg
400  );
401 
402 
403  // Other
404 
405  //- Extract a dictionary representation of the error information
406  operator dictionary() const;
407 
408  //- Exit : can be called for any error to exit program
409  void exit(const int errNo = 1);
410 
411  //- Abort : used to stop code for fatal errors
412  void abort();
413 
414  //- Print error message
415  virtual void write(Ostream& os, const bool withTitle = true) const;
416 };
417 
418 
419 // * * * * * * * * * * * * * * * Global Operators * * * * * * * * * * * * * //
420 
421 //- Ostream operator
422 Ostream& operator<<(Ostream& os, const error& err);
423 
424 //- Ostream operator
425 Ostream& operator<<(Ostream& os, const IOerror& err);
426 
427 
428 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
429 // Global error declarations: defined in error.C
430 
431 //- Error stream (stdout output on all processes),
432 //- with additional 'FOAM FATAL ERROR' header text and stack trace.
433 extern error FatalError;
434 
435 //- Error stream (stdout output on all processes),
436 //- with additional 'FOAM FATAL IO ERROR' header text and stack trace.
437 extern IOerror FatalIOError;
438 
439 
440 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
441 
442 } // End namespace Foam
443 
444 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
445 // Convenience macros to add the file name and line number to the function name
446 
447 //- Report an error message using Foam::FatalError
448 // for functionName in file __FILE__ at line __LINE__
449 #define FatalErrorIn(functionName) \
450  ::Foam::FatalError((functionName), __FILE__, __LINE__)
451 
452 //- Report an error message using Foam::FatalError
453 // for FUNCTION_NAME in file __FILE__ at line __LINE__
454 #define FatalErrorInFunction FatalErrorIn(FUNCTION_NAME)
455 
456 //- Report an error message using Foam::FatalError
457 // about unknown lookup type in table
458 #define FatalErrorInLookup(lookupTag, lookupName, lookupTable) \
459  ::Foam::FatalError(FUNCTION_NAME, __FILE__, __LINE__) \
460  << "Unknown " << (lookupTag) << " type " << (lookupName) \
461  << "\n\nValid " << (lookupTag) << " types :\n" \
462  << ((lookupTable).sortedToc()) << '\n'
463 
464 
465 //- Report an error message using Foam::FatalIOError
466 // for functionName in file __FILE__ at line __LINE__
467 // for a particular IOstream
468 #define FatalIOErrorIn(functionName, ios) \
469  ::Foam::FatalIOError((functionName), __FILE__, __LINE__, (ios))
470 
471 //- Report an error message using Foam::FatalIOError
472 // for FUNCTION_NAME in file __FILE__ at line __LINE__
473 // for a particular IOstream
474 #define FatalIOErrorInFunction(ios) FatalIOErrorIn(FUNCTION_NAME, ios)
475 
476 
477 //- Report an error message using Foam::FatalIOError
478 // about unknown lookup type in table
479 #define FatalIOErrorInLookup(ios, lookupTag, lookupName, lookupTable) \
480  ::Foam::FatalIOError(FUNCTION_NAME, __FILE__, __LINE__, (ios)) \
481  << "Unknown " << (lookupTag) << " type " << (lookupName) \
482  << "\n\nValid " << (lookupTag) << " types :\n" \
483  << ((lookupTable).sortedToc()) << '\n'
484 
485 
486 //- Report an error message using Foam::FatalIOError
487 // (or cerr if FatalIOError not yet constructed)
488 // for functionName in file __FILE__ at line __LINE__
489 // for a particular IOstream
490 #define SafeFatalIOErrorIn(functionName, ios, msg) \
491  ::Foam::IOerror::SafeFatalIOError \
492  ((functionName), __FILE__, __LINE__, (ios), (msg))
493 
494 //- Report an error message using Foam::FatalIOError
495 // (or cerr if FatalIOError not yet constructed)
496 // for functionName in file __FILE__ at line __LINE__
497 // for a particular IOstream
498 #define SafeFatalIOErrorInFunction(ios, msg) \
499  SafeFatalIOErrorIn(FUNCTION_NAME, ios, msg)
500 
501 
502 //- Issue a FatalErrorIn for a function not currently implemented.
503 // The functionName is printed and then abort is called.
504 //
505 // This macro can be particularly useful when methods must be defined to
506 // complete the interface of a derived class even if they should never be
507 // called for this derived class.
508 #define notImplemented(functionName) \
509  FatalErrorIn(functionName) \
510  << "Not implemented" << ::Foam::abort(FatalError);
511 
512 //- Issue a FatalErrorIn for a function not currently implemented.
513 // The FUNCTION_NAME is printed and then abort is called.
514 //
515 // This macro can be particularly useful when methods must be defined to
516 // complete the interface of a derived class even if they should never be
517 // called for this derived class.
518 #define NotImplemented notImplemented(FUNCTION_NAME)
519 
520 
521 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
522 
523 #include "errorManip.H"
524 
525 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
526 
527 #endif
528 
529 // ************************************************************************* //
Foam::error::printStack
static void printStack(Ostream &os)
Helper function to print a stack.
Definition: dummyPrintStack.C:36
Foam::error::messageStreamPtr_
std::unique_ptr< OStringStream > messageStreamPtr_
Definition: error.H:92
Foam::IOerror::abort
void abort()
Abort : used to stop code for fatal errors.
Definition: IOerror.C:249
Foam::IOerror::ioEndLineNumber
label ioEndLineNumber() const noexcept
The currently defined IO end-line number.
Definition: error.H:326
Foam::messageStream
Handle output messages in a simple, consistent stream-based manner.
Definition: messageStream.H:73
Foam::error::sourceFileName_
string sourceFileName_
Definition: error.H:89
Foam::error::dontThrowExceptions
bool dontThrowExceptions() noexcept
Deactivate exception throwing.
Definition: error.H:267
Foam::IOerror::IOerror
IOerror(const string &title)
Construct from title string.
Definition: IOerror.C:38
Foam::IOstream
An IOstream is an abstract base class for all input/output systems; be they streams,...
Definition: IOstream.H:79
Foam::error::throwing
bool throwing() const noexcept
Return the current exception throwing state (on or off)
Definition: error.H:169
SafeFatalIOErrorIn
#define SafeFatalIOErrorIn(functionName, ios, msg)
Report an error message using Foam::FatalIOError.
Definition: error.H:489
Foam::error::functionName
const string & functionName() const noexcept
The currently defined function name for output messages.
Definition: error.H:151
Foam::FatalIOError
IOerror FatalIOError
Foam::error::sourceFileLineNumber
label sourceFileLineNumber() const noexcept
The currently defined source-file line number for output messages.
Definition: error.H:163
Foam::IOerror::ioStartLineNumber
label ioStartLineNumber() const noexcept
The currently defined IO start-line number for output messages.
Definition: error.H:320
Foam::operator<<
Ostream & operator<<(Ostream &, const boundaryPatch &p)
Write boundaryPatch as dictionary entries (without surrounding braces)
Definition: boundaryPatch.C:83
NotImplemented
#define NotImplemented
Issue a FatalErrorIn for a function not currently implemented.
Definition: error.H:517
Foam::IOerror::SafeFatalIOError
static void SafeFatalIOError(const char *functionName, const char *sourceFileName, const int sourceFileLineNumber, const IOstream &ioStream, const string &msg)
Print basic message and exit.
Definition: IOerror.C:166
FatalIOErrorInLookup
#define FatalIOErrorInLookup(ios, lookupTag, lookupName, lookupTable)
Report an error message using Foam::FatalIOError.
Definition: error.H:478
Foam::error::error
error(const string &title)
Construct from title string.
Definition: error.C:107
Foam::error::throwExceptions
bool throwExceptions(const bool on=true) noexcept
Specify exception throwing state (default is on)
Definition: error.H:260
notImplemented
#define notImplemented(functionName)
Issue a FatalErrorIn for a function not currently implemented.
Definition: error.H:507
FatalIOErrorIn
#define FatalIOErrorIn(functionName, ios)
Report an error message using Foam::FatalIOError.
Definition: error.H:467
Foam::OSstream
Generic output stream using a standard (STL) stream.
Definition: OSstream.H:54
Foam::IOerror::~IOerror
virtual ~IOerror() noexcept
Destructor.
Definition: IOerror.C:58
dict
dictionary dict
Definition: searchingEngine.H:14
SafeFatalIOErrorInFunction
#define SafeFatalIOErrorInFunction(ios, msg)
Report an error message using Foam::FatalIOError.
Definition: error.H:497
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:123
FatalErrorInLookup
#define FatalErrorInLookup(lookupTag, lookupName, lookupTable)
Report an error message using Foam::FatalError.
Definition: error.H:457
os
OBJstream os(runTime.globalPath()/outputName)
Foam::error::message
string message() const
The accumulated error message.
Definition: error.C:319
Foam::error::sourceFileLineNumber_
label sourceFileLineNumber_
Definition: error.H:90
Foam
Namespace for OpenFOAM.
Definition: atmBoundaryLayer.C:33
Foam::error::useAbort
static bool useAbort()
True if FOAM_ABORT is on.
Definition: error.C:98
Foam::error::exit
void exit(const int errNo=1)
Exit : can be called for any error to exit program.
Definition: error.C:331
Foam::foamVersion::version
const std::string version
OpenFOAM version (name or stringified number) as a std::string.
messageStream.H
Foam::error::operator()
OSstream & operator()()
Explicit convert to OSstream for << operations.
Definition: error.H:196
Foam::error::~error
virtual ~error() noexcept
Destructor.
Definition: error.C:145
Foam::error::functionName_
string functionName_
Definition: error.H:88
Foam::IOerror::exit
void exit(const int errNo=1)
Exit : can be called for any error to exit program.
Definition: IOerror.C:243
Foam::IOerror::ioFileName
const string & ioFileName() const noexcept
The currently defined IO name for output messages.
Definition: error.H:314
Foam::error::stream
OSstream & stream()
Return OSstream for output operations.
Definition: error.C:304
Foam::IOerror::write
virtual void write(Ostream &os, const bool withTitle=true) const
Print error message.
Definition: IOerror.C:255
Foam::error::abort
void abort()
Abort : used to stop code for fatal errors.
Definition: error.C:337
Foam::error::master
static bool master(const label communicator=-1)
Definition: error.C:41
Foam::error::simpleExit
void simpleExit(const int errNo, const bool isAbort)
Exit or abort, without throwing or job control handling.
Definition: error.C:253
Foam::error::clear
void clear() const
Clear any messages.
Definition: error.C:325
FUNCTION_NAME
#define FUNCTION_NAME
Definition: messageStream.H:295
errorManip.H
Foam::IOerror
Report an I/O error.
Definition: error.H:279
Foam::error::warnAboutAge
static bool warnAboutAge(const int version) noexcept
Test if an age warning should be emitted.
Definition: error.C:55
FatalErrorIn
#define FatalErrorIn(functionName)
Report an error message using Foam::FatalError.
Definition: error.H:448
Foam::error::throwing_
bool throwing_
Definition: error.H:91
Foam::Ostream
An Ostream is an abstract base class for all output systems (streams, files, token lists,...
Definition: Ostream.H:56
Foam::error::write
virtual void write(Ostream &os, const bool withTitle=true) const
Print error message.
Definition: error.C:343
Foam::error
Class to handle errors and exceptions in a simple, consistent stream-based manner.
Definition: error.H:73
Foam::messageStream::title
const string & title() const noexcept
The title of this error type.
Definition: messageStream.H:137
Foam::error::safePrintStack
static void safePrintStack(std::ostream &os)
Definition: dummyPrintStack.C:32
Foam::error::sourceFileName
const string & sourceFileName() const noexcept
The currently defined source-file name for output messages.
Definition: error.H:157