src/OSD/OSD.hxx

   1 // Copyright (c) 1992-1999 Matra Datavision
   2 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   3 //
   4 // This file is part of Open CASCADE Technology software library.
   5 //
   6 // This library is free software; you can redistribute it and/or modify it under
   7 // the terms of the GNU Lesser General Public License version 2.1 as published
   8 // by the Free Software Foundation, with special exception defined in the file
   9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  10 // distribution for complete text of the license and disclaimer of any warranty.
  11 //
  12 // Alternatively, this file may be used under the terms of Open CASCADE
  13 // commercial license or contractual agreement.
  14
  15 #ifndef _OSD_HeaderFile
  16 #define _OSD_HeaderFile
  17
  18 #include <Standard.hxx>
  19 #include <Standard_PCharacter.hxx>
  20 #include <OSD_SignalMode.hxx>
  21
  22 //! Set of Operating Sytem Dependent (OSD) Tools
  23 class OSD
  24 {
  25 public:
  26
  27   DEFINE_STANDARD_ALLOC
  28
  29   //! Sets or removes signal and FPE (floating-point exception) handlers.
  30   //! OCCT signal handlers translate signals raised by C subsystem to C++
  31   //! exceptions inheriting Standard_Failure.
  32   //!
  33   //! ### Windows-specific notes
  34   //!
  35   //! Compiled with MS VC++ sets 3 main handlers:
  36   //! @li Signal handlers (via ::signal() functions) that translate system signals
  37   //! (SIGSEGV, SIGFPE, SIGILL) into C++ exceptions (classes inheriting
  38   //! Standard_Failure). They only be called if function ::raise() is called
  39   //! with one of supported signal type set.
  40   //! @li Exception handler OSD::WntHandler() (via ::SetUnhandledExceptionFilter())
  41   //! that will be used when user's code is compiled with /EHs option.
  42   //! @li Structured exception (SE) translator (via _set_se_translator()) that
  43   //! translates SE exceptions (aka asynchronous exceptions) into the
  44   //! C++ exceptions inheriting Standard_Failure. This translator will be
  45   //! used when user's code is compiled with /EHa option.
  46   //!
  47   //! This approach ensures that regardless of the option the user chooses to
  48   //! compile his code with (/EHs or /EHa), signals (or SE exceptions) will be
  49   //! translated into Open CASCADE C++ exceptions.
  50   //!
  51   //! MinGW should use SEH exception mode for signal handling to work.
  52   //!
  53   //! ### Linux-specific notes
  54   //!
  55   //! OSD::SetSignal() sets handlers (via ::sigaction()) for multiple signals
  56   //! (SIGFPE, SIGSEGV, etc).
  57   //!
  58   //! ### Common notes
  59   //!
  60   //! If @a theFloatingSignal is TRUE then floating point exceptions will
  61   //! generate SIGFPE in accordance with the mask
  62   //! - Windows: _EM_INVALID | _EM_DENORMAL | _EM_ZERODIVIDE | _EM_OVERFLOW,
  63   //!            see _controlfp() system function.
  64   //! - Linux:   FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW,
  65   //!            see feenableexcept() system function.
  66   //!
  67   //! If @a theFloatingSignal is FALSE then floating point calculations will gracefully
  68   //! complete regardless of occurred exceptions (e.g. division by zero).
  69   //! Otherwise the (thread-specific) FPE flags are set to raise signal if one of
  70   //! floating-point exceptions (division by zero, overflow, or invalid operation) occurs.
  71   //!
  72   //! The recommended approach is to call OSD::SetSignal() in the beginning of the
  73   //! execution of the program, in function main() or its equivalent.
  74   //! In multithreaded programs it is advisable to call OSD::SetSignal() or
  75   //! OSD::SetThreadLocalSignal() with the same parameters in other threads where
  76   //! OCCT is used, to ensure consistency of behavior.
  77   //!
  78   //! Note that in order to handle signals as C++ exceptions on Linux and under
  79   //! MinGW on Windows it is necessary to compile both OCCT and application with
  80   //! OCC_CONVERT_SIGNALS macro, and use macro OCC_CATCH_SIGNALS within each try{}
  81   //! block that has to catch this kind of exceptions.
  82   //!
  83   //! Refer to documentation of Standard_ErrorHandler.hxx for details.
  84   Standard_EXPORT static void SetSignal (OSD_SignalMode theSignalMode,
  85                                          Standard_Boolean theFloatingSignal);
  86
  87   //! Sets signal and FPE handlers.
  88   //! Short-cut for OSD::SetSignal (OSD_SignalMode_Set, theFloatingSignal).
  89   static void SetSignal (const Standard_Boolean theFloatingSignal = Standard_True)
  90   {
  91     SetSignal (OSD_SignalMode_Set, theFloatingSignal);
  92   }
  93
  94   //! Initializes thread-local signal handlers.
  95   //! This includes _set_se_translator() on Windows platform, and SetFloatingSignal().
  96   //! The main purpose of this method is initializing handlers for newly created threads
  97   //! without overriding global handlers (set by application or by OSD::SetSignal()).
  98   Standard_EXPORT static void SetThreadLocalSignal (OSD_SignalMode theSignalMode,
  99                                                     Standard_Boolean theFloatingSignal);
 100
 101   //! Enables / disables generation of C signal on floating point exceptions (FPE).
 102   //! This call does NOT register a handler for signal raised in case of FPE -
 103   //! SetSignal() should be called beforehand for complete setup.
 104   //! Note that FPE setting is thread-local, new threads inherit it from parent.
 105   Standard_EXPORT static void SetFloatingSignal (Standard_Boolean theFloatingSignal);
 106
 107   //! Returns signal mode set by the last call to SetSignal().
 108   //! By default, returns OSD_SignalMode_AsIs.
 109   Standard_EXPORT static OSD_SignalMode SignalMode();
 110
 111   //! Returns true if floating point exceptions will raise C signal
 112   //! according to current (platform-dependent) settings in this thread.
 113   Standard_EXPORT static Standard_Boolean ToCatchFloatingSignals();
 114
 115   //! Commands the process to sleep for a number of seconds.
 116   Standard_EXPORT static void SecSleep (const Standard_Integer aDelay);
 117
 118   //! Commands the process to sleep for a number of milliseconds
 119   Standard_EXPORT static void MilliSecSleep (const Standard_Integer aDelay);
 120
 121   //! Converts aReal into aCstring in exponential format with a period as
 122   //! decimal point, no thousand separator and no grouping of digits.
 123   //! The conversion is independant from the current locale
 124   Standard_EXPORT static Standard_Boolean RealToCString (const Standard_Real aReal, Standard_PCharacter& aString);
 125
 126   //! Converts aCstring representing a real with a period as
 127   //! decimal point, no thousand separator and no grouping of digits
 128   //! into aReal .
 129   //! The conversion is independant from the current locale.
 130   Standard_EXPORT static Standard_Boolean CStringToReal (const Standard_CString aString, Standard_Real& aReal);
 131
 132   //! since Windows NT does not support 'SIGINT' signal like UNIX,
 133   //! then this method checks whether Ctrl-Break keystroke was or
 134   //! not. If yes then raises Exception_CTRL_BREAK.
 135   Standard_EXPORT static void ControlBreak();
 136
 137 };
 138
 139 #endif // _OSD_HeaderFile