oomph_definitions.h
Go to the documentation of this file.
1// LIC// ====================================================================
2// LIC// This file forms part of oomph-lib, the object-oriented,
3// LIC// multi-physics finite-element library, available
4// LIC// at http://www.oomph-lib.org.
5// LIC//
6// LIC// Copyright (C) 2006-2022 Matthias Heil and Andrew Hazel
7// LIC//
8// LIC// This library is free software; you can redistribute it and/or
9// LIC// modify it under the terms of the GNU Lesser General Public
10// LIC// License as published by the Free Software Foundation; either
11// LIC// version 2.1 of the License, or (at your option) any later version.
12// LIC//
13// LIC// This library is distributed in the hope that it will be useful,
14// LIC// but WITHOUT ANY WARRANTY; without even the implied warranty of
15// LIC// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16// LIC// Lesser General Public License for more details.
17// LIC//
18// LIC// You should have received a copy of the GNU Lesser General Public
19// LIC// License along with this library; if not, write to the Free Software
20// LIC// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21// LIC// 02110-1301 USA.
22// LIC//
23// LIC// The authors may be contacted at oomph-lib@maths.man.ac.uk.
24// LIC//
25// LIC//====================================================================
26// A header containing the definition of the Oomph run-time
27// exception classes and our standard (info) output stream
28//(essentially a wrapper to cout but it can be customised,
29// e.g. for mpi runs.
30
31// Include guard to prevent multiple inclusions of the header
32#ifndef OOMPH_DEFINITIONS_HEADER
33#define OOMPH_DEFINITIONS_HEADER
34
35// Config header generated by autoconfig
36#ifdef HAVE_CONFIG_H
37#include <oomph-lib-config.h>
38#endif
39
40// Standard libray headers
41#include <stdexcept>
42#include <iostream>
43#include <string>
44#include <vector>
45
46
47namespace oomph
48{
49// Pre-processor magic for error reporting
50// Macro that converts argument to string
51#define OOMPH_MAKE_STRING(x) #x
52
53// Macro wrapper to MAKE_STRING, required because calling
54// OOMPH_MAKE_STRING(__LINE__) directly returns __LINE__
55// i.e. the conversion of __LINE__ into a number must be performed before
56// its conversion into a string
57#define OOMPH_TO_STRING(x) OOMPH_MAKE_STRING(x)
58
59// Combine the FILE and LINE built-in macros into a string that can
60// be used in erorr messages.
61#define OOMPH_EXCEPTION_LOCATION __FILE__ ":" OOMPH_TO_STRING(__LINE__)
62
63// Get the current function name. All the mess is due to different
64// compilers naming the macro we need differently.
65#if defined(__GNUC__) || (defined(__MWERKS__) && (__MWERKS__ >= 0x3000)) || \
66 (defined(__ICC) && (__ICC >= 600)) || defined(__ghs__)
67#define OOMPH_CURRENT_FUNCTION __PRETTY_FUNCTION__
68
69#elif defined(__DMC__) && (__DMC__ >= 0x810)
70#define OOMPH_CURRENT_FUNCTION __PRETTY_FUNCTION__
71
72#elif defined(__FUNCSIG__)
73#define OOMPH_CURRENT_FUNCTION __FUNCSIG__
74
75#elif (defined(__INTEL_COMPILER) && (__INTEL_COMPILER >= 600)) || \
76 (defined(__IBMCPP__) && (__IBMCPP__ >= 500))
77#define OOMPH_CURRENT_FUNCTION __FUNCTION__
78
79#elif defined(__BORLANDC__) && (__BORLANDC__ >= 0x550)
80#define OOMPH_CURRENT_FUNCTION __FUNC__
81
82#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901)
83#define OOMPH_CURRENT_FUNCTION __func__
84
85#else
86#define OOMPH_CURRENT_FUNCTION "[Unknown function -- unrecognised compiler]"
87
88#endif
89
90
91 /// ////////////////////////////////////////////////////////////////////
92 /// ////////////////////////////////////////////////////////////////////
93 /// ////////////////////////////////////////////////////////////////////
94
95
96 /// =====================================================================
97 /// Namespace to control level of comprehensive timings
98 //======================================================================
99 namespace Global_timings
100 {
101 /// Global boolean to switch on comprehensive timing -- can
102 /// probably be declared const false when development on hector
103 /// is complete
104 extern bool Doc_comprehensive_timings;
105
106 }; // namespace Global_timings
107
108
109 /// //////////////////////////////////////////////////////////////////
110 /// //////////////////////////////////////////////////////////////////
111 /// //////////////////////////////////////////////////////////////////
112
113 //=======================================================================
114 /// Helper namespace for set_terminate function -- used to spawn
115 /// messages from uncaught errors (their destructor may not be called)
116 /// =======================================================================
117 namespace TerminateHelper
118 {
119 /// Setup terminate helper
120 extern void setup();
121
122 /// Suppress error messages (e.g. because error has been caught)
124
125 /// Function to spawn messages from uncaught errors
127
128 /// Clean up function that deletes anything dynamically allocated
129 /// in this namespace
130 extern void clean_up_memory();
131
132 /// Stream to output error messages
133 extern std::ostream* Error_message_stream_pt;
134
135 /// String stream that records the error message
136 extern std::stringstream* Exception_stringstream_pt;
137
138 } // namespace TerminateHelper
139
140 /// ////////////////////////////////////////////////////////////////////
141 /// ////////////////////////////////////////////////////////////////////
142 /// ////////////////////////////////////////////////////////////////////
143
144
145 /// =====================================================================
146 /// A class for handling oomph-lib run-time exceptions quietly.
147 //======================================================================
148 class OomphLibQuietException : public std::runtime_error
149 {
150 public:
151 /// Constructor
153
154 /// The destructor cannot throw an exception (C++ STL standard)
156 };
157
158 /// ////////////////////////////////////////////////////////////////////
159 /// ////////////////////////////////////////////////////////////////////
160 /// ////////////////////////////////////////////////////////////////////
161
162
163 /// =====================================================================
164 /// A Base class for oomph-lib run-time exception (error and warning)
165 /// handling.
166 ///
167 /// The class can only be instantiated by the derived classes
168 /// OomphLibError and OomphLibWarning. The (protected) constructor
169 /// combines its string arguments into a standard format
170 /// for uniform exception reports which are written to the specified
171 /// output stream.
172 //======================================================================
173 class OomphLibException : public std::runtime_error
174 {
175 public:
176 /// Suppress issueing of the error message in destructor
177 /// (useful if error is caught successfully!)
179 {
180 // Suppress output of message in destructor...
182
183 // ...and in the big cleanup operation at the end
185 }
186
187 protected:
188 /// Constructor takes the error description, function name
189 /// and a location string provided by the OOMPH_EXCEPTION_LOCATION
190 /// macro and combines them into a standard header. The exception type
191 /// will be the string "WARNING" or "ERROR" and the message is written to
192 /// the exception_stream, with a specified output_width. Optionally
193 /// provide a traceback of the function calls.
194 OomphLibException(const std::string& error_description,
195 const std::string& function_name,
196 const char* location,
197 const std::string& exception_type,
198 std::ostream& exception_stream,
199 const unsigned& output_width,
200 bool list_trace_back);
201
202 /// The destructor cannot throw an exception (C++ STL standard)
203 ~OomphLibException() throw();
204
205 /// Exception stream to which we write message in destructor
206 std::ostream* Exception_stream_pt;
207
208 /// String stream that records the error message
209 std::stringstream* Exception_stringstream_pt;
210
211 /// Boolean to suppress issuing of the error message in destructor
212 /// (useful if error is caught successfully!)
214 };
215
216 //====================================================================
217 /// An OomphLibError object which should be thrown when an run-time
218 /// error is encountered. The error stream and stream width can be
219 /// specified. The default is cerr with a width of 70 characters.
220 //====================================================================
222 {
223 /// Output stream that is used to write the errors
224 static std::ostream* Stream_pt;
225
226 /// Width in characters of the output report
227 static unsigned Output_width;
228
229 public:
230 /// Constructor requires the error description and the function
231 /// in which the error occured and the location provided by the
232 /// OOMPH_EXCEPTION_LOCATION macro
233 OomphLibError(const std::string& error_description,
234 const std::string& function_name,
235 const char* location)
236 : OomphLibException(error_description,
237 function_name,
238 location,
239 "ERROR",
240 *Stream_pt,
241 Output_width,
242 true)
243 {
244 }
245
246 /// Static member function used to specify the error stream,
247 /// which must be passed as a pointer because streams cannot be copied.
248 static inline void set_stream_pt(std::ostream* const& stream_pt)
249 {
250 Stream_pt = stream_pt;
251 }
252
253 /// Static member function used to specify the width (in characters)
254 /// of the error stream
255 static inline void set_output_width(const unsigned& output_width)
256 {
257 Output_width = output_width;
258 }
259 };
260
261 //====================================================================
262 /// An OomphLibWarning object which should be created as a temporary
263 /// object to issue a warning. The warning stream and stream width can be
264 /// specified. The default is cerr with a width of 70 characters.
265 //====================================================================
267 {
268 /// Output stream that is used to write the errors
269 static std::ostream* Stream_pt;
270
271 /// Width of output
272 static unsigned Output_width;
273
274 public:
275 /// Constructor requires the warning description and the function
276 /// in which the warning occurred.
277 OomphLibWarning(const std::string& warning_description,
278 const std::string& function_name,
279 const char* location)
280 : OomphLibException(warning_description,
281 function_name,
282 location,
283 "WARNING",
284 *Stream_pt,
285 Output_width,
286 false)
287 {
288 }
289
290 /// Static member function used to specify the error stream,
291 /// which must be passed as a pointer because streams cannot be copied.
292 static inline void set_stream_pt(std::ostream* const& stream_pt)
293 {
294 Stream_pt = stream_pt;
295 }
296
297 /// Static member function used to specify the width (in characters)
298 /// of the error stream
299 static inline void set_output_width(const unsigned& output_width)
300 {
301 Output_width = output_width;
302 }
303 };
304
305
306 /// /////////////////////////////////////////////////////////////////////
307 /// /////////////////////////////////////////////////////////////////////
308 /// /////////////////////////////////////////////////////////////////////
309
310
311 //=====================================================================
312 /// A small nullstream class that throws away everything sent to it.
313 //=====================================================================
314 class Nullstream : public std::ostream
315 {
316 public:
317 /// Constructor sets the buffer sizes to zero, suppressing all output
318 Nullstream() : std::ios(0), std::ostream(0) {}
319 };
320
321
322 //========================================================================
323 /// Single (global) instantiation of the Nullstream
324 //========================================================================
325 extern Nullstream oomph_nullstream;
326
327
328 /// /////////////////////////////////////////////////////////////////////
329 /// /////////////////////////////////////////////////////////////////////
330 /// /////////////////////////////////////////////////////////////////////
331
332
333 //========================================================================
334 /// A base class that contains a single virtual member function:
335 /// The () operator that may be used to modify the output in
336 /// OomphOutput objects. The default implementation
337 /// =======================================================================
339 {
340 public:
341 /// Empty constructor
343
344 /// Empty virtual destructor
345 virtual ~OutputModifier() {}
346
347 /// Function that will be called before output from an
348 /// OomphOutput object. It returns a bool (true in this default
349 /// implementation) to indicate that output should be continued.
350 virtual bool operator()(std::ostream& stream)
351 {
352 return true;
353 }
354 };
355
356
357 //========================================================================
358 /// Single global instatiation of the default output modifier.
359 //========================================================================
360 extern OutputModifier default_output_modifier;
361
362
363 /// /////////////////////////////////////////////////////////////////////
364 /// /////////////////////////////////////////////////////////////////////
365 /// /////////////////////////////////////////////////////////////////////
366
367
368 //=======================================================================
369 /// Namespace containing an output stream that can be used for
370 /// debugging. Use at your own risk -- global data is evil!
371 //=======================================================================
372 namespace Global_output_stream
373 {
374 /// Output stream
375 extern std::ofstream* Outfile;
376
377 } // namespace Global_output_stream
378
379
380 /// /////////////////////////////////////////////////////////////////////
381 /// /////////////////////////////////////////////////////////////////////
382 /// /////////////////////////////////////////////////////////////////////
383
384
385 //=======================================================================
386 /// Namespace containing a number that can be used to annotate things for
387 /// debugging. Use at your own risk -- global data is evil!
388 //=======================================================================
389 namespace Global_unsigned
390 {
391 /// The unsigned
392 extern unsigned Number;
393
394 } // namespace Global_unsigned
395
396
397 /// /////////////////////////////////////////////////////////////////////
398 /// /////////////////////////////////////////////////////////////////////
399 /// /////////////////////////////////////////////////////////////////////
400
401
402 //=======================================================================
403 /// Namespace containing a vector of strings that can be used to
404 /// to store global output modifiers. This is global data
405 /// and you use it at your own risk!
406 //=======================================================================
407 namespace Global_string_for_annotation
408 {
409 /// Return the i-th string or "" if the relevant string hasn't
410 /// been defined
411 extern std::string string(const unsigned& i);
412
413 /// Storage for strings that may be used for global annotations.
414 /// This is global data and you use it at your own risk!
415 extern std::vector<std::string> String;
416 } // namespace Global_string_for_annotation
417
418
419 /// /////////////////////////////////////////////////////////////////////
420 /// /////////////////////////////////////////////////////////////////////
421 /// /////////////////////////////////////////////////////////////////////
422
423
424 //=======================================================================
425 /// This class is a wrapper to a stream and an output modifier that is
426 /// used to control the "info" output from OomphLib. Its instationiation
427 /// can be used like std::cout.
428 //=======================================================================
430 {
431 private:
432 /// Pointer to the output stream -- defaults to std::cout
433 std::ostream* Stream_pt;
434
435 /// Pointer to the output modifier object -- defaults to no modification
437
438 public:
439 /// Set default values for the output stream (cout)
440 /// and modifier (no modification)
442 : Stream_pt(&std::cout), Output_modifier_pt(&default_output_modifier)
443 {
444 }
445
446 /// Overload the << operator, writing output to the stream addressed
447 /// by Stream_pt and calling the function defined by the object addressed by
448 /// Output_modifier_pt
449 template<class _Tp>
450 std::ostream& operator<<(_Tp argument)
451 {
452 // If the Output_modifer function returns true
453 // echo the argument to the stream and return the (vanilla) stream
454 if ((*Output_modifier_pt)(*Stream_pt))
455 {
456 *Stream_pt << argument;
457 return (*Stream_pt);
458 }
459 // Otherwise return the null stream (suppress all future output)
460 return oomph_nullstream;
461 }
462
463 /// Access function for the stream pointer
464 std::ostream*& stream_pt()
465 {
466 return Stream_pt;
467 }
468
469 /// Overload insertor to handle stream modifiers
470 std::ostream& operator<<(std::ostream& (*f)(std::ostream&))
471 {
472 return f(*Stream_pt);
473 }
474
475 /// Access function for the output modifier pointer
477 {
478 return Output_modifier_pt;
479 }
480 };
481
482
483 //========================================================================
484 /// Single (global) instantiation of the OomphInfo object -- this
485 /// is used throughout the library as a "replacement" for std::cout
486 //========================================================================
487 extern OomphInfo oomph_info;
488
489
490} // namespace oomph
491
492#endif
cstr elem_len * i
Definition: cfortran.h:603
///////////////////////////////////////////////////////////////////// ///////////////////////////////...
Nullstream()
Constructor sets the buffer sizes to zero, suppressing all output.
///////////////////////////////////////////////////////////////////// ///////////////////////////////...
std::ostream * Stream_pt
Pointer to the output stream – defaults to std::cout.
std::ostream *& stream_pt()
Access function for the stream pointer.
std::ostream & operator<<(std::ostream &(*f)(std::ostream &))
Overload insertor to handle stream modifiers.
OutputModifier *& output_modifier_pt()
Access function for the output modifier pointer.
OomphInfo()
Set default values for the output stream (cout) and modifier (no modification)
OutputModifier * Output_modifier_pt
Pointer to the output modifier object – defaults to no modification.
std::ostream & operator<<(_Tp argument)
Overload the << operator, writing output to the stream addressed by Stream_pt and calling the functio...
An OomphLibError object which should be thrown when an run-time error is encountered....
OomphLibError(const std::string &error_description, const std::string &function_name, const char *location)
Constructor requires the error description and the function in which the error occured and the locati...
static unsigned Output_width
Width in characters of the output report.
static void set_stream_pt(std::ostream *const &stream_pt)
Static member function used to specify the error stream, which must be passed as a pointer because st...
static std::ostream * Stream_pt
Output stream that is used to write the errors.
static void set_output_width(const unsigned &output_width)
Static member function used to specify the width (in characters) of the error stream.
//////////////////////////////////////////////////////////////////// ////////////////////////////////...
~OomphLibException()
The destructor cannot throw an exception (C++ STL standard)
OomphLibException(const std::string &error_description, const std::string &function_name, const char *location, const std::string &exception_type, std::ostream &exception_stream, const unsigned &output_width, bool list_trace_back)
Constructor takes the error description, function name and a location string provided by the OOMPH_EX...
void disable_error_message()
Suppress issueing of the error message in destructor (useful if error is caught successfully!...
std::stringstream * Exception_stringstream_pt
String stream that records the error message.
std::ostream * Exception_stream_pt
Exception stream to which we write message in destructor.
bool Suppress_error_message
Boolean to suppress issuing of the error message in destructor (useful if error is caught successfull...
//////////////////////////////////////////////////////////////////// ////////////////////////////////...
~OomphLibQuietException()
The destructor cannot throw an exception (C++ STL standard)
An OomphLibWarning object which should be created as a temporary object to issue a warning....
static void set_output_width(const unsigned &output_width)
Static member function used to specify the width (in characters) of the error stream.
static unsigned Output_width
Width of output.
static std::ostream * Stream_pt
Output stream that is used to write the errors.
static void set_stream_pt(std::ostream *const &stream_pt)
Static member function used to specify the error stream, which must be passed as a pointer because st...
OomphLibWarning(const std::string &warning_description, const std::string &function_name, const char *location)
Constructor requires the warning description and the function in which the warning occurred.
///////////////////////////////////////////////////////////////////// ///////////////////////////////...
virtual ~OutputModifier()
Empty virtual destructor.
OutputModifier()
Empty constructor.
virtual bool operator()(std::ostream &stream)
Function that will be called before output from an OomphOutput object. It returns a bool (true in thi...
std::ofstream * Outfile
Output stream.
std::vector< std::string > String
Storage for strings that may be used for global annotations. This is global data and you use it at yo...
std::string string(const unsigned &i)
Return the i-th string or "" if the relevant string hasn't been defined.
bool Doc_comprehensive_timings
Global boolean to switch on comprehensive timing – can probably be declared const false when developm...
unsigned Number
The unsigned.
void clean_up_memory()
Clean up function that deletes anything dynamically allocated in this namespace.
void suppress_exception_error_messages()
Flush string stream of error messages (call when error has been caught)
void setup()
Setup terminate helper.
void spawn_errors_from_uncaught_errors()
Function to spawn messages from uncaught errors.
std::stringstream * Exception_stringstream_pt
String stream that records the error message.
std::ostream * Error_message_stream_pt
Stream to output error messages.
//////////////////////////////////////////////////////////////////// ////////////////////////////////...
Nullstream oomph_nullstream
///////////////////////////////////////////////////////////////////////// ///////////////////////////...
OutputModifier default_output_modifier
Single global instatiation of the default output modifier.
OomphInfo oomph_info
Single (global) instantiation of the OomphInfo object – this is used throughout the library as a "rep...