src/Standard/Standard_Failure.hxx

   1 // Created on: 1991-09-05
   2 // Created by: Philippe COICADAN
   3 // Copyright (c) 1991-1999 Matra Datavision
   4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 //
   6 // This file is part of Open CASCADE Technology software library.
   7 //
   8 // This library is free software; you can redistribute it and/or modify it under
   9 // the terms of the GNU Lesser General Public License version 2.1 as published
  10 // by the Free Software Foundation, with special exception defined in the file
  11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 // distribution for complete text of the license and disclaimer of any warranty.
  13 //
  14 // Alternatively, this file may be used under the terms of Open CASCADE
  15 // commercial license or contractual agreement.
  16
  17 #ifndef _Standard_Failure_HeaderFile
  18 #define _Standard_Failure_HeaderFile
  19
  20 #include <Standard_Type.hxx>
  21
  22 #include <Standard_CString.hxx>
  23 #include <Standard_Transient.hxx>
  24 #include <Standard_OStream.hxx>
  25 #include <Standard_SStream.hxx>
  26
  27 DEFINE_STANDARD_HANDLE(Standard_Failure, Standard_Transient)
  28
  29 //! Forms the root of the entire exception hierarchy.
  30 class Standard_Failure : public Standard_Transient
  31 {
  32 public:
  33
  34   //! Creates a status object of type "Failure".
  35   Standard_EXPORT Standard_Failure();
  36
  37   //! Copy constructor
  38   Standard_EXPORT Standard_Failure (const Standard_Failure& f);
  39
  40   //! Creates a status object of type "Failure".
  41   //! @param theDesc [in] exception description
  42   Standard_EXPORT Standard_Failure (const Standard_CString theDesc);
  43
  44   //! Creates a status object of type "Failure" with stack trace.
  45   //! @param theDesc [in] exception description
  46   //! @param theStackTrace [in] associated stack trace
  47   Standard_EXPORT Standard_Failure (const Standard_CString theDesc,
  48                                     const Standard_CString theStackTrace);
  49
  50   //! Assignment operator
  51   Standard_EXPORT Standard_Failure& operator= (const Standard_Failure& f);
  52
  53   //! Destructor
  54   Standard_EXPORT ~Standard_Failure();
  55
  56   //! Prints on the stream @p theStream the exception name followed by the error message.
  57   //!
  58   //! Note: there is a short-cut @c operator<< (Standard_OStream&, Handle(Standard_Failure)&)
  59   Standard_EXPORT void Print (Standard_OStream& theStream) const;
  60
  61   //! Returns error message
  62   Standard_EXPORT virtual Standard_CString GetMessageString() const;
  63
  64   //! Sets error message
  65   Standard_EXPORT virtual void SetMessageString (const Standard_CString theMessage);
  66
  67   //! Returns the stack trace string
  68   Standard_EXPORT virtual Standard_CString GetStackString() const;
  69
  70   //! Sets the stack trace string
  71   Standard_EXPORT virtual void SetStackString (const Standard_CString theStack);
  72
  73   Standard_EXPORT void Reraise();
  74
  75   Standard_EXPORT void Reraise (const Standard_CString aMessage);
  76
  77   //! Reraises a caught exception and changes its error message.
  78   Standard_EXPORT void Reraise (const Standard_SStream& aReason);
  79
  80 public:
  81
  82   //! Raises an exception of type "Failure" and associates
  83   //! an error message to it. The message can be printed
  84   //! in an exception handler.
  85   Standard_EXPORT static void Raise (const Standard_CString aMessage = "");
  86
  87   //! Raises an exception of type "Failure" and associates
  88   //! an error message to it. The message can be constructed
  89   //! at run-time.
  90   Standard_EXPORT static void Raise (const Standard_SStream& aReason);
  91
  92   //! Used to construct an instance of the exception object as a handle.
  93   //! Shall be used to protect against possible construction of exception object in C stack,
  94   //! which is dangerous since some of methods require that object was allocated dynamically.
  95   Standard_EXPORT static Handle(Standard_Failure) NewInstance (Standard_CString theMessage);
  96
  97   //! Used to construct an instance of the exception object as a handle.
  98   Standard_EXPORT static Handle(Standard_Failure) NewInstance (Standard_CString theMessage,
  99                                                                Standard_CString theStackTrace);
 100
 101   //! Returns the default length of stack trace to be captured by Standard_Failure constructor;
 102   //! 0 by default meaning no stack trace.
 103   Standard_EXPORT static Standard_Integer DefaultStackTraceLength();
 104
 105   //! Sets default length of stack trace to be captured by Standard_Failure constructor.
 106   Standard_EXPORT static void SetDefaultStackTraceLength (Standard_Integer theNbStackTraces);
 107
 108 public:
 109
 110   //! Used to throw CASCADE exception from C signal handler.
 111   //! On platforms that do not allow throwing C++ exceptions
 112   //! from this handler (e.g. Linux), uses longjump to get to
 113   //! the current active signal handler, and only then is
 114   //! converted to C++ exception.
 115   Standard_EXPORT void Jump();
 116
 117   DEFINE_STANDARD_RTTIEXT(Standard_Failure,Standard_Transient)
 118
 119 protected:
 120
 121   //! Used only if standard C++ exceptions are used.
 122   //! Throws exception of the same type as this by C++ throw,
 123   //! and stores current object as last thrown exception,
 124   //! to be accessible by method Caught()
 125   Standard_EXPORT virtual void Throw() const;
 126
 127 private:
 128
 129   //! Reference-counted string,
 130   //! Memory block is allocated with an extra 4-byte header (int representing number of references)
 131   //! using low-level malloc() to avoid exceptions.
 132   struct StringRef
 133   {
 134     Standard_Integer   Counter;
 135     Standard_Character Message[1];
 136
 137     //! Return message string.
 138     Standard_CString GetMessage() const { return (Standard_CString )&Message[0]; }
 139
 140     //! Allocate reference-counted message string.
 141     static StringRef* allocate_message (Standard_CString theString);
 142
 143     //! Copy reference-counted message string.
 144     static StringRef* copy_message (StringRef* theString);
 145
 146     //! Release reference-counted message string.
 147     static void deallocate_message (StringRef* theString);
 148   };
 149
 150 private:
 151
 152   StringRef* myMessage;
 153   StringRef* myStackTrace;
 154
 155 };
 156
 157 // =======================================================================
 158 // function : operator<<
 159 // purpose  :
 160 // =======================================================================
 161 inline Standard_OStream& operator<< (Standard_OStream& theStream,
 162                                      const Handle(Standard_Failure)& theFailure)
 163 {
 164   theFailure->Print (theStream);
 165   return theStream;
 166 }
 167
 168 // =======================================================================
 169 // function : operator<<
 170 // purpose  :
 171 // =======================================================================
 172 inline Standard_OStream& operator<< (Standard_OStream& theStream,
 173                                      const Standard_Failure& theFailure)
 174 {
 175   theFailure.Print (theStream);
 176   return theStream;
 177 }
 178
 179 #endif // _Standard_Failure_HeaderFile