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