0022545: Improved exception handling
[occt.git] / src / OSD / OSD.cdl
index 85f08da..7235c41 100755 (executable)
@@ -28,17 +28,17 @@ package OSD
  --   2.0
  --   3.0
  --   Windows NT 30/09/96 ( EUG )
- ---Purpose: Set of Operating Sytem Dependent Tools 
+ ---Purpose: Set of Operating Sytem Dependent Tools
  --         (O)perating (S)ystem (D)ependent
 
-uses  
+uses
 
-    Standard ,  
-    Quantity ,  
+    Standard ,
+    Quantity ,
     TCollection
 
 is
+
  exception OSDError inherits Failure from Standard  ;
 
  imported Function;
@@ -51,7 +51,7 @@ is
    ---Purpose: This is set of possible machine types
    --          used in OSD_Host::MachineType
 
- enumeration SysType is Unknown,Default,UnixBSD, UnixSystemV, VMS, OS2, 
+ enumeration SysType is Unknown,Default,UnixBSD, UnixSystemV, VMS, OS2,
                         OSF, MacOs, Taligent, WindowsNT, LinuxREDHAT,Aix;
    ---Purpose: Thisd is a set of possible system types.
    --          'Default' means SysType of machine operating this process.
@@ -59,7 +59,7 @@ is
    --          All UNIX-like are grouped under "UnixBSD" or "UnixSystemV".
    --          Such systems are Solaris, NexTOS ...
    --          A category of systems accept MSDOS-like path such as
-   --          WindowsNT and OS2. 
+   --          WindowsNT and OS2.
 
  enumeration FromWhere is FromBeginning, FromHere, FromEnd;
    ---Purpose: Used by OSD_File in the method Seek.
@@ -70,7 +70,7 @@ is
    --
    --          ReadLock allows only one reading of the file at a time.
    --
-   --          WriteLock prevents others writing into a file(excepted the user 
+   --          WriteLock prevents others writing into a file(excepted the user
    --          who puts the lock)but allows everybody to read.
    --
    --          ExclusiveLock prevents reading and writing except for the
@@ -94,8 +94,8 @@ is
  enumeration KindFile is FILE, DIRECTORY, LINK, SOCKET, UNKNOWN;
    ---Purpose: Specifies the type of files.
 
- private enumeration WhoAmI is  WDirectory, WDirectoryIterator, 
-             WEnvironment, WFile, WFileNode, WFileIterator, WMailBox, 
+ private enumeration WhoAmI is  WDirectory, WDirectoryIterator,
+             WEnvironment, WFile, WFileNode, WFileIterator, WMailBox,
              WPath, WProcess, WProtection, WSemaphore, WHost, WDisk,
              WChronometer, WSharedMemory, WTimer, WPackage, WPrinter,
              WEnvironmentIterator;
@@ -109,7 +109,7 @@ is
          class Protection;
              ---Purpose: Gets and sets protection attributes of 'system , user ,
              --          group, and world'.
-  
+
          class Path;
              ---Purpose: Manages independent system path translation.
 
@@ -132,7 +132,7 @@ is
              ---Purpose: Searches sub-directories in current directory.
 
          class Chronometer;
-             ---Purpose: Measures time elapsed for performance program tests. 
+             ---Purpose: Measures time elapsed for performance program tests.
              --          Measures CPU time consumed by a method call.
 
          class Timer;
@@ -155,17 +155,17 @@ is
              ---Purpose: Process specific oriented tools
 
          class SharedMemory;
-             ---Purpose: Manages shared memory. 
+             ---Purpose: Manages shared memory.
 
          class Semaphore;
              ---Purpose: Manages semaphores.
+
 --         class Mutex is alias Mutex from Standard;
              ---Purpose: Mutex object to synchronize threads within one process
+
          class MailBox;
              ---Purpose: Manages asynchronous mail boxes.
-    
+
          class SharedLibrary;
              ---Purpose: Provides tools to load a shared library
              --          and retrieve the address of an entry point.
@@ -177,11 +177,11 @@ is
              ---Purpose: A tool to manage threads
 
     class Real2String;
-             ---Purpose: Convertion of CString to Real and reciprocally   
+             ---Purpose: Convertion of CString to Real and reciprocally
 
     class Localizer;
              ---Purpose: Manages locale.
-   
+
 
     -----------------------------------------------
     --  UNIX specific exceptions and enumeration --
@@ -196,12 +196,12 @@ is
     exception SIGBUS  inherits Signal;
     exception SIGSEGV inherits Signal;
     exception SIGSYS  inherits Signal;
-    
+
 
     enumeration Signals is
       ---purpose:
       --     The "posix" signals.
-      --     
+      --
       S_SIGHUP,          -- "hangup."
       S_SIGINT,          -- "interrupt."
       S_SIGQUIT,         -- "quit."
@@ -218,13 +218,13 @@ is
       S_FPE_FLTUND_TRAP, -- "floating underflow."
       S_FPE_FLTINEX_TRAP -- "floating inexact result."
     end Signals;
-    
+
     ----------------------------------------
     -- Exceptions ( Windows NT specific ) --
     ----------------------------------------
 
     exception Exception inherits Failure   from  Standard;
-    
+
     exception Exception_ACCESS_VIOLATION         inherits Exception;
     exception Exception_ARRAY_BOUNDS_EXCEEDED    inherits Exception;
     exception Exception_FLT_DENORMAL_OPERAND     inherits Exception;
@@ -249,35 +249,35 @@ is
     -- Handler and SegvHandler (UNIX specific ) --
     ----------------------------------------------
 
-    -- 
-    --     Handler(aSignal: Signals; aCode: Signals) 
-    --     
-    Handler(aSignal: Signals; aSigInfo: Address; aContext: Address)    
+    --
+    --     Handler(aSignal: Signals; aCode: Signals)
+    --
+
+    Handler(aSignal: Signals; aSigInfo: Address; aContext: Address)
     ---Purpose:
     --   1) Raise a exception when aSignal is a floating point signal.
     --    aSignal is SIGFPE.
-    --    aCode is 
+    --    aCode is
     --        (FPE:  Floating Point Exception)
     --        (FLT:  FLoaTing operation.)
     --        (INT:  INTeger  operation.)
     --        (DIV:  DIVided by zero.)
     --        (OVF:  OVerFlow.)
     --        (INEX: INEXact operation.)
-    --        
+    --
     --        FPE_FLTDIV_TRAP  (the exception "DivideByZero" is raised.)
     --        FPE_INTDIV_TRAP  (the exception "DivideByZero" is raised.)
-    --        
+    --
     --        FPE_FLTOVF_TRAP  (the exception "Overflow" is raised.)
     --        FPE_INTOVF_TRAP  (the exception "Overflow" is raised.)
-    --        
+    --
     --        FPE_FLTINEX_TRAP (the exception "NumericError" is raised.)
-    --        
+    --
     --   2) Display the signal name, and call "exit" with signal number for
     --   a "Hardware" signal.
-    --   
+    --
     raises
-        DivideByZero, 
+        DivideByZero,
     Overflow,
     Underflow,
         SIGHUP,
@@ -338,42 +338,77 @@ is
         --  2) Displays a message box 'Continue' - 'Debugger' - 'Stop' if the environment
         --     variable 'CSF_EXCEPTION_PROMPT' is set and takes appropriate action.
         --     Raises an exception otherwise.
-    SetSignal(aFloatingSignal: Boolean = Standard_True);
+
+    SetSignal(theFloatingSignal: Boolean = Standard_True);
     ---Purpose:
-    --   1) Arms some floating point signals, and sets a "Handler" for them.
-    --   2) Sets a "Handler" for the "Hardware" signals.
-    --   For Win32 users: under VC++ you can control which method of handling
-    --   exceptions is used by means of UseSETranslator method before calling
-    --   SetSignal
+    -- Sets signal and exception handlers.
+    -- <b>Windows-specific notes<\b>
+    -- Compiled with MS VC++ sets 3 main handlers:
+    -- @li Signal handlers (via ::signal() functions) that translate system signals
+    --     (SIGSEGV, SIGFPE, SIGILL) into C++ exceptions (classes inheriting
+    --     Standard_Failure). They only be called if user calls ::raise() function
+    --     with one of supported signal type set.
+    -- @li Exception handler OSD::WntHandler() (via ::SetUnhandledExceptionFilter())
+    --     that will be used when user's code is compiled with /EHs option.
+    -- @li Structured exception (SE) translator (via _set_se_translator()) that
+    --     translates SE exceptions (aka asynchronous exceptions) into the
+    --     C++ exceptions inheriting Standard_Failure. This translator will be
+    --     used when user's code is compiled with /EHa option.
+    -- .
+    -- This approach ensures that regardless of the option the user chooses to
+    -- compile his code with (/EHs or /EHa), signals (or SE exceptions) will be
+    -- translated into Open CASCADE C++ exceptions.
+    -- .
+    -- If @a theFloatingSignal is TRUE then floating point exceptions will be
+    -- generated in accordance with the mask
+    -- <tt>_EM_INVALID | _EM_DENORMAL | _EM_ZERODIVIDE | _EM_OVERFLOW<\tt> that is
+    -- used to call ::_controlfp() system function. If @a theFloatingSignal is FALSE
+    -- corresponding operations (e.g. division by zero) will gracefully complete
+    -- without an exception.
+    -- .
+    -- <b>Unix-specific notes<\b>
+    -- OSD::SetSignal() sets handlers (via ::sigaction()) for multiple signals
+    -- (SIGFPE, SIGSEGV, etc). Currently the number of handled signals is much
+    -- greater than for Windows, in the future this may change to provide better
+    -- consistency with Windows.
+    -- .
+    -- @a theFloatingSignal is recognized on Sun Solaris, Linux, and SGI Irix to
+    -- generate floating-point exception according to the mask
+    -- <tt>FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW</tt> (in Linux conventions).<br>
+    -- When compiled with OBJS macro defined, already set signal handlers (e.g.
+    -- by Data Base Managers) are not redefined.
+    -- .
+    -- <b>Common notes<\b>
+    -- If OSD::SetSignal() method is used in at least one thread, it must also be
+    -- called in any other thread where Open CASCADE will be used, to ensure
+    -- consistency of behavior. Its @a aFloatingSignal argument must be consistent
+    -- across threads.
+    -- .
+    -- Keep in mind that whether the C++ exception will really be thrown (i.e.
+    -- ::throw() will be called) is regulated by the NO_CXX_EXCEPTIONS and
+    -- OCC_CONVERT_SIGNALS macros used during compilation of Open CASCADE and
+    -- user's code. Refer to Foundation Classes User's Guide for further details.
     --
-    --  Warning:
-    --   Some "Data Base Managers" use their own "Handler" for the signals 
-    --   such as  "SIGSEGV". So if a "Handler" is set for a signal it will
-    --   not be replaced by Standard "Handler". It is managed by OBJS
-    --   preprocessor definition.
-    --
-    ---Level: Internal    
 
     AvailableMemory returns Integer from Standard;
     ---Purpose: Returns available memory in Kilobytes.
     ---Level: Advanced
-     
+
     SecSleep(aDelay: Integer from Standard);
     ---Purpose: Commands the process to sleep for a number of seconds.
-    ---Level: Public    
+    ---Level: Public
 
     MilliSecSleep(aDelay: Integer from Standard);
     ---Purpose: Commands the process to sleep for a number of milliseconds
-    ---Level: Public    
+    ---Level: Public
 
-    RealToCString(aReal: Real; aString:out PCharacter)  
+    RealToCString(aReal: Real; aString:out PCharacter)
         returns Boolean ;
     ---Purpose:
     --  Converts aReal into aCstring in exponential format with a period as
     --  decimal point, no thousand separator and no grouping of digits.
     --  The conversion is independant from the current locale
-    ---Level: Public    
+    ---Level: Public
 
     CStringToReal(aString: CString; aReal: out Real) returns Boolean ;
     ---Purpose:
@@ -381,46 +416,31 @@ is
     --  decimal point, no thousand separator and no grouping of digits
     --  into aReal .
     --  The conversion is independant from the current locale.
-    ---Level: Public    
+    ---Level: Public
 
     IsDivisible(aDividend, aDivisor: Real from Standard)
     returns Boolean from Standard;
     ---Purpose: Tests if the quotient theDividend/theDivisor
     --          does not overflow
-    ---Level: Public    
-    
+    ---Level: Public
+
     GetExponent(aReal: Real from Standard)
     returns Integer from Standard;
     ---Purpose: Returns the exponent in base 2 of a floating-point number.
-    ---Level: Public    
-    
+    ---Level: Public
+
     GetMantissa(aReal: Real from Standard)
     returns Real from Standard;
     ---Purpose: Returns the mantissa of a floating-point number.
-    ---Level: Public    
-    
+    ---Level: Public
+
     -------------------------
     -- Windows NT specific --
     -------------------------
-                            
+
     ControlBreak raises  Exception_CTRL_BREAK;
     ---Purpose: since Windows NT does not support 'SIGINT' signal like UNIX,
     --          then this method checks whether Ctrl-Break keystroke was or
     --          not. If yes then raises Exception_CTRL_BREAK.
 
-    UseSETranslator(useSE : Boolean);
-    ---Purpose: Defines whether SetSignal must use _se_translator_function or
-    --          SetUnhandledExceptionFilter and signal to catch system
-    --          exceptions. The default behaviour is to use SE translator.
-    --  Warning: Using SE translator method SetSignal should be called for each
-    --          new created thread, while using the alternative method 
-    --          the exception handler is established once for the whole
-    --          process and all its threads.
-    --          This function takes effect only under VC++ compiler.
-
-    UseSETranslator returns Boolean;
-    ---Purpose: Returns the current value of the flag set by above method.
-
 end OSD;
-
-