All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
error.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration | Website: https://openfoam.org
5  \\ / A nd | Copyright (C) 2011-2024 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 "OStringStream.H"
52 #include "messageStream.H"
53 
54 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
55 
56 namespace Foam
57 {
58 
59 // Forward declaration of friend functions and operators
60 class error;
61 Ostream& operator<<(Ostream&, const error&);
62 
63 
64 /*---------------------------------------------------------------------------*\
65  Class error Declaration
66 \*---------------------------------------------------------------------------*/
67 
68 class error
69 :
70  public std::exception,
71  public messageStream
72 {
73 
74 protected:
75 
76  // Protected data
77 
78  string functionName_;
81 
82  bool abort_;
83 
84  bool throwExceptions_;
85 
87 
88 
89 public:
90 
91  // Constructors
92 
93  //- Construct from title string
94  error(const string& title);
95 
96 
97  // Member Functions
98 
99  string message() const;
100 
101  const string& functionName() const
102  {
103  return functionName_;
104  }
105 
106  const string& sourceFileName() const
107  {
108  return sourceFileName_;
109  }
110 
112  {
113  return sourceFileLineNumber_;
114  }
115 
116  void throwExceptions()
117  {
118  throwExceptions_ = true;
119  }
120 
121  void dontThrowExceptions()
122  {
123  throwExceptions_ = false;
124  }
125 
126  //- Convert to OSstream
127  // Prints basic message and returns OSstream for further info.
128  OSstream& operator()
129  (
130  const char* functionName,
131  const char* sourceFileName,
132  const int sourceFileLineNumber = 0
133  );
134 
135  //- Convert to OSstream
136  // Prints basic message and returns OSstream for further info.
137  OSstream& operator()
138  (
139  const string& functionName,
140  const char* sourceFileName,
141  const int sourceFileLineNumber = 0
142  );
143 
144  //- Explicitly convert to OSstream for << operations
145  OSstream& operator()();
146 
147  //- Convert to OSstream for << operations
148  operator OSstream&()
149  {
150  return this->operator()();
151  }
152 
153  //- Create and return a dictionary
154  operator dictionary() const;
155 
156  //- Helper function to print a stack (if OpenFOAM IO not yet
157  // initialised)
158  static void safePrintStack(std::ostream&);
159 
160  //- Helper function to print a stack
161  static void printStack(Ostream&);
162 
163  //- Exit : can be called for any error to exit program.
164  // Prints stack before exiting.
165  void exit(const int errNo = 1);
166 
167  //- Abort : used to stop code for fatal errors.
168  // Prints stack before exiting.
169  void abort();
170 
171 
172  // Ostream operator
173 
174  friend Ostream& operator<<(Ostream&, const error&);
175 };
176 
177 
178 // Forward declaration of friend functions and operators
179 class IOerror;
180 Ostream& operator<<(Ostream&, const IOerror&);
181 
182 
183 /*---------------------------------------------------------------------------*\
184  Class IOerrorLocation Declaration
185 \*---------------------------------------------------------------------------*/
186 
187 class IOerrorLocation
188 {
189  // Private Data
190 
191  //- File name
192  string ioFileName_;
193 
194  //- Start line number
195  label ioStartLineNumber_;
196 
197  //- End Line number
198  label ioEndLineNumber_;
199 
200  //- Is file global
201  bool ioGlobal_;
202 
203 
204 public:
205 
206  // Constructors
207 
208  //- Construct null
209  IOerrorLocation();
210 
211  //- Construct from components
213  (
214  const string& ioFileName,
215  const label ioStartLineNumber = -1,
216  const label ioEndLineNumber = -1,
217  const bool ioGlobal = false
218  );
219 
220  //- Construct from a stream
221  IOerrorLocation(const IOstream&);
222 
223  //- Construct from a dictionary
224  IOerrorLocation(const dictionary&);
225 
226 
227  // Member Functions
228 
229  //- Access the file name
230  inline const string& ioFileName() const
231  {
232  return ioFileName_;
233  }
234 
235  //- Access the start line number
236  inline label ioStartLineNumber() const
237  {
238  return ioStartLineNumber_;
239  }
240 
241  //- Access the end line number
242  inline label ioEndLineNumber() const
243  {
244  return ioEndLineNumber_;
245  }
246 
247  //- Assess to the global/local file switch
248  inline bool ioGlobal() const
249  {
250  return ioGlobal_;
251  }
252 };
253 
254 
255 /*---------------------------------------------------------------------------*\
256  Class IOerror Declaration
257 \*---------------------------------------------------------------------------*/
258 
259 class IOerror
260 :
261  public error,
262  public IOerrorLocation
263 {
264 public:
265 
266  // Constructors
267 
268  //- Construct from title string
269  IOerror(const string& title);
270 
271 
272  // Member Functions
273 
274  //- Convert to OSstream
275  // Prints basic message and returns OSstream for further info.
276  OSstream& operator()
277  (
278  const char* functionName,
279  const char* sourceFileName,
280  const int sourceFileLineNumber,
281  const IOerrorLocation& location
282  );
283 
284  //- Print basic message and exit. Uses cerr if streams not constructed
285  // yet (at startup). Use in startup parsing instead of FatalError.
286  static void SafeFatalIOError
287  (
288  const char* functionName,
289  const char* sourceFileName,
290  const int sourceFileLineNumber,
291  const IOstream&,
292  const string& msg
293  );
294 
295  //- Create and return a dictionary
296  operator dictionary() const;
297 
298  //- Exit : can be called for any error to exit program
299  void exit(const int errNo = 1);
300 
301  //- Abort : used to stop code for fatal errors
302  void abort();
303 
304 
305  // Ostream operator
306 
307  friend Ostream& operator<<(Ostream&, const IOerror&);
308 };
309 
310 
311 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
312 // Global error declarations: defined in error.C
313 
314 extern error FatalError;
315 extern IOerror FatalIOError;
316 
317 // Template argument dependent "false" for static_assert in templated functions
318 template <class... T>
319 constexpr bool False = false;
320 
321 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
322 
323 } // End namespace Foam
324 
325 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
326 // Convenience macros to add the file name and line number to the function name
327 
328 //- Report an error message using Foam::FatalError
329 // for functionName in file __FILE__ at line __LINE__
330 #define FatalErrorIn(functionName) \
331  ::Foam::FatalError((functionName), __FILE__, __LINE__)
332 
333 //- Report an error message using Foam::FatalError
334 // for FUNCTION_NAME in file __FILE__ at line __LINE__
335 #define FatalErrorInFunction FatalErrorIn(FUNCTION_NAME)
336 
337 
338 //- Report an error message using Foam::FatalIOError
339 // for functionName in file __FILE__ at line __LINE__
340 // for a particular IOstream
341 #define FatalIOErrorIn(functionName, ios) \
342  ::Foam::FatalIOError((functionName), __FILE__, __LINE__, (ios))
343 
344 //- Report an error message using Foam::FatalIOError
345 // for FUNCTION_NAME in file __FILE__ at line __LINE__
346 // for a particular IOstream
347 #define FatalIOErrorInFunction(ios) FatalIOErrorIn(FUNCTION_NAME, ios)
348 
349 
350 //- Report an error message using Foam::FatalIOError
351 // (or cerr if FatalIOError not yet constructed)
352 // for functionName in file __FILE__ at line __LINE__
353 // for a particular IOstream
354 #define SafeFatalIOErrorIn(functionName, ios, msg) \
355  ::Foam::IOerror::SafeFatalIOError \
356  ((functionName), __FILE__, __LINE__, (ios), (msg))
357 
358 //- Report an error message using Foam::FatalIOError
359 // (or cerr if FatalIOError not yet constructed)
360 // for functionName in file __FILE__ at line __LINE__
361 // for a particular IOstream
362 #define SafeFatalIOErrorInFunction(ios, msg) \
363  SafeFatalIOErrorIn(FUNCTION_NAME, ios, msg)
364 
365 
366 //- Issue a FatalErrorIn for a function not currently implemented.
367 // The functionName is printed and then abort is called.
368 //
369 // This macro can be particularly useful when methods must be defined to
370 // complete the interface of a derived class even if they should never be
371 // called for this derived class.
372 #define notImplemented(functionName) \
373  FatalErrorIn(functionName) \
374  << "Not implemented" << ::Foam::abort(::Foam::FatalError);
375 
376 //- Issue a FatalErrorIn for a function not currently implemented.
377 // The FUNCTION_NAME is printed and then abort is called.
378 //
379 // This macro can be particularly useful when methods must be defined to
380 // complete the interface of a derived class even if they should never be
381 // called for this derived class.
382 #define NotImplemented notImplemented(FUNCTION_NAME)
383 
384 
385 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
386 
387 #include "errorManip.H"
388 
389 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
390 
391 #endif
392 
393 // ************************************************************************* //
const string & ioFileName() const
Access the file name.
Definition: error.H:229
IOerrorLocation()
Construct null.
Definition: IOerror.C:35
label ioEndLineNumber() const
Access the end line number.
Definition: error.H:241
label ioStartLineNumber() const
Access the start line number.
Definition: error.H:235
bool ioGlobal() const
Assess to the global/local file switch.
Definition: error.H:247
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:101
void exit(const int errNo=1)
Exit : can be called for any error to exit program.
Definition: IOerror.C:154
IOerror(const string &title)
Construct from title string.
Definition: IOerror.C:77
void abort()
Abort : used to stop code for fatal errors.
Definition: IOerror.C:207
friend Ostream & operator<<(Ostream &, const IOerror &)
An IOstream is an abstract base class for all input/output systems; be they streams,...
Definition: IOstream.H:72
Generic output stream.
Definition: OSstream.H:54
Output to memory buffer stream.
Definition: OStringStream.H:52
An Ostream is an abstract base class for all output systems (streams, files, token lists,...
Definition: Ostream.H:57
A list of keyword definitions, which are a keyword followed by any number of values (e....
Definition: dictionary.H:162
Class to handle errors and exceptions in a simple, consistent stream-based manner.
Definition: error.H:71
string functionName_
Definition: error.H:77
bool abort_
Definition: error.H:81
const string & sourceFileName() const
Definition: error.H:105
label sourceFileLineNumber_
Definition: error.H:79
friend Ostream & operator<<(Ostream &, const error &)
OStringStream messageStream_
Definition: error.H:85
const string & functionName() const
Definition: error.H:100
string message() const
Definition: error.C:119
static void printStack(Ostream &)
Helper function to print a stack.
void exit(const int errNo=1)
Exit : can be called for any error to exit program.
Definition: error.C:125
void throwExceptions()
Definition: error.H:115
error(const string &title)
Construct from title string.
Definition: error.C:36
OSstream & operator()()
Explicitly convert to OSstream for << operations.
Definition: error.C:88
static void safePrintStack(std::ostream &)
Helper function to print a stack (if OpenFOAM IO not yet.
Definition: printStack.C:192
string sourceFileName_
Definition: error.H:78
void abort()
Abort : used to stop code for fatal errors.
Definition: error.C:166
bool throwExceptions_
Definition: error.H:83
void dontThrowExceptions()
Definition: error.H:120
label sourceFileLineNumber() const
Definition: error.H:110
A functionName is a word starting with '#'.
Definition: functionName.H:60
Class to handle messaging in a simple, consistent stream-based manner.
Definition: messageStream.H:69
const string & title() const
Return the title of this error type.
Namespace for OpenFOAM.
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
constexpr bool False
Definition: error.H:318
IOerror FatalIOError
Ostream & operator<<(Ostream &os, const fvConstraints &constraints)
error FatalError
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)