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) 2004-2011 OpenCFD Ltd.
   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         //- Create and return a dictionary
 269         operator dictionary() const;
 270
 271
 272         //- Exit : can be called for any error to exit program
 273         void exit(const int errNo = 1);
 274
 275         //- Abort : used to stop code for fatal errors
 276         void abort();
 277
 278
 279     // Ostream operator
 280
 281         friend Ostream& operator<<(Ostream&, const IOerror&);
 282 };
 283
 284
 285 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 286 // Global error declarations: defined in error.C
 287
 288 extern error   FatalError;
 289 extern IOerror FatalIOError;
 290
 291 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 292
 293 } // End namespace Foam
 294
 295 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 296 // Convenience macros to add the file name and line number to the function name
 297
 298 /**
 299  * \def FatalErrorIn(functionName)
 300  * Report an error message using Foam::FatalError for functionName in
 301  * file __FILE__ at line __LINE__
 302 */
 303 #define FatalErrorIn(fn) \
 304     ::Foam::FatalError((fn), __FILE__, __LINE__)
 305
 306 /**
 307  * \def FatalIOErrorIn(functionName, ios)
 308  * Report an error message using Foam::FatalIOError for functionName in
 309  * file __FILE__ at line __LINE__
 310  * for a particular IOstream
 311 */
 312 #define FatalIOErrorIn(fn, ios) \
 313     ::Foam::FatalIOError((fn), __FILE__, __LINE__, (ios))
 314
 315 /**
 316  * \def notImplemented(functionName)
 317  * Issue a FatalErrorIn for the functionName.
 318  * This is used for functions that are not currently implemented.
 319  * The functionName is printed and then abort is called.
 320  *
 321  * \note
 322  * This macro can be particularly useful when methods must be defined to
 323  * complete the interface of a derived class even if they should never be
 324  * called for this derived class.
 325 */
 326 #define notImplemented(fn) \
 327     FatalErrorIn(fn) << "Not implemented" << ::Foam::abort(FatalError);
 328
 329 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 330
 331 #include "errorManip.H"
 332
 333 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 334
 335 #endif
 336
 337 // ************************************************************************* //