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