src/OpenFOAM/db/error/error.H

   1 /*---------------------------------------------------------------------------*\
   2   =========                 |
   3   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   4    \\    /   O peration     |
   5     \\  /    A nd           | Copyright (C) 2011 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 globaly 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 of if the exception
  35     handling has beed 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_;
  78         string sourceFileName_;
  79         label sourceFileLineNumber_;
  80
  81         bool abort_;
  82
  83         bool throwExceptions_;
  84         OStringStream* messageStreamPtr_;
  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;
 107
 108         const string& functionName() const
 109         {
 110             return functionName_;
 111         }
 112
 113         const string& sourceFileName() const
 114         {
 115             return sourceFileName_;
 116         }
 117
 118         label sourceFileLineNumber() const
 119         {
 120             return sourceFileLineNumber_;
 121         }
 122
 123         void throwExceptions()
 124         {
 125             throwExceptions_ = true;
 126         }
 127
 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
 156         OSstream& operator()()
 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
 166         static void printStack(Ostream&);
 167
 168         //- Exit : can be called for any error to exit program.
 169         //  Prints stack before exiting.
 170         void exit(const int errNo = 1);
 171
 172         //- Abort : used to stop code for fatal errors.
 173         //  Prints stack before exiting.
 174         void abort();
 175
 176
 177     // Ostream operator
 178
 179         friend Ostream& operator<<(Ostream&, const error&);
 180 };
 181
 182
 183 // Forward declaration of friend functions and operators
 184 class IOerror;
 185 Ostream& operator<<(Ostream&, const IOerror&);
 186
 187
 188 /*---------------------------------------------------------------------------*\
 189                            Class IOerror Declaration
 190 \*---------------------------------------------------------------------------*/
 191
 192 //- Report an I/O error
 193 class IOerror
 194 :
 195     public error
 196 {
 197     // Private data
 198
 199         string ioFileName_;
 200         label ioStartLineNumber_;
 201         label ioEndLineNumber_;
 202
 203
 204 public:
 205
 206     // Constructors
 207
 208         //- Construct from title string
 209         IOerror(const string& title);
 210
 211         //- Construct from dictionary
 212         IOerror(const dictionary&);
 213
 214
 215     //- Destructor
 216     virtual ~IOerror() throw();
 217
 218
 219     // Member functions
 220
 221         const string& ioFileName() const
 222         {
 223             return ioFileName_;
 224         }
 225
 226         label ioStartLineNumber() const
 227         {
 228             return ioStartLineNumber_;
 229         }
 230
 231         label ioEndLineNumber() const
 232         {
 233             return ioEndLineNumber_;
 234         }
 235
 236         //- Convert to OSstream
 237         //  Prints basic message and returns OSstream for further info.
 238         OSstream& operator()
 239         (
 240             const char* functionName,
 241             const char* sourceFileName,
 242             const int sourceFileLineNumber,
 243             const string& ioFileName,
 244             const label ioStartLineNumber = -1,
 245             const label ioEndLineNumber = -1
 246         );
 247
 248         //- Convert to OSstream
 249         //  Prints basic message and returns OSstream for further info.
 250         OSstream& operator()
 251         (
 252             const char* functionName,
 253             const char* sourceFileName,
 254             const int sourceFileLineNumber,
 255             const IOstream&
 256         );
 257
 258         //- Convert to OSstream
 259         //  Prints basic message and returns OSstream for further info.
 260         OSstream& operator()
 261         (
 262             const char* functionName,
 263             const char* sourceFileName,
 264             const int sourceFileLineNumber,
 265             const dictionary&
 266         );
 267
 268         //- Print basic message and exit. Uses cerr if streams not constructed
 269         //  yet (at startup). Use in startup parsing instead of FatalError.
 270         static void SafeFatalIOError
 271         (
 272             const char* functionName,
 273             const char* sourceFileName,
 274             const int sourceFileLineNumber,
 275             const IOstream&,
 276             const string& msg
 277         );
 278
 279         //- Create and return a dictionary
 280         operator dictionary() const;
 281
 282
 283         //- Exit : can be called for any error to exit program
 284         void exit(const int errNo = 1);
 285
 286         //- Abort : used to stop code for fatal errors
 287         void abort();
 288
 289
 290     // Ostream operator
 291
 292         friend Ostream& operator<<(Ostream&, const IOerror&);
 293 };
 294
 295
 296 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 297 // Global error declarations: defined in error.C
 298
 299 extern error   FatalError;
 300 extern IOerror FatalIOError;
 301
 302 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 303
 304 } // End namespace Foam
 305
 306 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 307 // Convenience macros to add the file name and line number to the function name
 308
 309 /**
 310  * \def FatalErrorIn(functionName)
 311  * Report an error message using Foam::FatalError for functionName in
 312  * file __FILE__ at line __LINE__
 313 */
 314 #define FatalErrorIn(fn) \
 315     ::Foam::FatalError((fn), __FILE__, __LINE__)
 316
 317 /**
 318  * \def FatalIOErrorIn(functionName, ios)
 319  * Report an error message using Foam::FatalIOError for functionName in
 320  * file __FILE__ at line __LINE__
 321  * for a particular IOstream
 322 */
 323 #define FatalIOErrorIn(fn, ios) \
 324     ::Foam::FatalIOError((fn), __FILE__, __LINE__, (ios))
 325
 326 /**
 327  * \def SafeFatalIOErrorIn(functionName, ios, msg)
 328  * Report an error message using Foam::FatalIOError (or cerr if FatalIOError
 329  * not yet constructed) for functionName in
 330  * file __FILE__ at line __LINE__
 331  * for a particular IOstream
 332 */
 333 #define SafeFatalIOErrorIn(fn, ios, msg) \
 334     ::Foam::IOerror::SafeFatalIOError((fn), __FILE__, __LINE__, (ios), (msg))
 335
 336 /**
 337  * \def notImplemented(functionName)
 338  * Issue a FatalErrorIn for the functionName.
 339  * This is used for functions that are not currently implemented.
 340  * The functionName is printed and then abort is called.
 341  *
 342  * \note
 343  * This macro can be particularly useful when methods must be defined to
 344  * complete the interface of a derived class even if they should never be
 345  * called for this derived class.
 346 */
 347 #define notImplemented(fn) \
 348     FatalErrorIn(fn) << "Not implemented" << ::Foam::abort(FatalError);
 349
 350 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 351
 352 #include "errorManip.H"
 353
 354 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 355
 356 #endif
 357
 358 // ************************************************************************* //