"

 COPYRIGHT (c) 1993 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

Object subclass:#Exception

	instanceVariableNames:'signal parameter errorString suspendedContext handlerContext

		rejected originator resumeBlock rejectBlock'

	classVariableNames:'EmergencyHandler RecursiveExceptionSignal'

	poolDictionaries:''

	category:'Kernel-Exceptions'

!

!Exception class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1993 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    Instances of Exception are passed to a Signal handling block as argument.

    The handler block may perform various actions by sending corresponding messages

    to the exception object. The following actions are possible:

	reject          - dont handle this signal;

			  another handler will be searched for, 

			  upper in the calling hierarchy

	proceed         - return from the Signal>>raise, with nil as value

	proceedWith:val - same, but return val from Signal>>raise

	return          - return from the Signal>>handle:do:, with nil as value

	returnWith:val  - same, but return val from Signal>>handle:do:

			  (this is also the handlers default, 

			   if it falls through; taking the handlerBlocks value

			   as return value)

	restart         - restart the Signal>>handle:do:, after repairing

    Via the Exception object, the handler can also query the state of execution:

    where the Signal was raised, where the handler is, the signal which caused

    the error and the errorString passed when the signal was raised. Also, an optional

    parameter can be passed - the use is signal specific.:

    [instance variables:]

	signal           <Signal>     the signal which caused the exception

	parameter        <Object>     a parameter (if any) which was passed when raising

				      the signal (only if raised with #raiseWith:aParameter)

	errorString      <String>     an errorString 

				      (usually the signals own errorString, but sometimes

				       changed explicitely in #raiseWith:errorString:)

	suspendedContext <Context>    the context in which the raise occured

	handlerContext   <Context>    the context of the handler (if any)

	resumeBlock      <Block>      private to the exception; needed to perform resume action

	rejectBlock      <Block>      private to the exception; needed to perform reject action

    In case of an unhandled signal raise, Exceptions EmergenyHandler will be evaluated. 

    The default emergeny handler will enter the debugger.

    For applications, which do not want Debuggers to come up, other handlers are

    possible.

    For example, to get the typical C++ behavior, use:

	Exception emergencyHandler:[:ex | Smalltalk exitWithCoreDump]

    [Class variables:]

	EmergencyHandler <Block>    this block is evaluated, if no handler was defined

				    for a signal (i.e. this one is responsible for the

				    unhandled exception debugger).

				    Having this being a block allows to globally catch

				    these errors - even when no enclosing handler-scope

				    around the erronous code exists.

				    (as the catch/through does).

	RecursiveExceptionSignal

			 <Signal>   raised when within a handler for some signal,

				    the same signal is raised again.

    [see also:]

	Signal  SignalSet QuerySignal

	Context Block

	Object DebugView

	(``Exception handling and signals'': programming/exceptions.html)

    [author:]

	Claus Gittinger

"

!

examples

"

    Examples on Exception-raising & handling are found in the doc/coding

    section (CodingExamples).

    The emergencyHandler stuff is very useful, to prevent endUser applications

    from entering the debugger.

    Some commonly used (useful) emergency handlers are provided in the

    'useful handlers' section; try them to learn more

    (especially, the mailingHandler is fun).

    Of course, these are only examples - you may define your own handler

    block and pass it to the #emergencyHandler: method.

    BTW: the Launchers 'source & debugger' settings menu allows you

         to install either a default or the notifying handler.

    A handler which shows a box, then aborts - (no more debuggers):

                                                                [exBegin]

        Exception emergencyHandler:(Exception abortingEmergencyHandler)

                                                                [exEnd]

    A handler which aborts - (no box, no debugger):

                                                                [exBegin]

        Exception emergencyHandler:[:ex | AbortSignal raise]

                                                                [exEnd]

    try some exception (for demonstration, in some other process):

                                                                [exBegin]

        [

            #(1 2 3) at:4

        ] fork.

                                                                [exEnd]

    cleanup (switch back to the regular handler, which enters the debugger):

                                                                [exBegin]

        Exception emergencyHandler:nil

                                                                [exEnd]

    A handler which shows a warnBox and asks for debugging:

                                                                [exBegin]

        Exception emergencyHandler:(Exception notifyingEmergencyHandler)

                                                                [exEnd]

    A handler which dumps information to a file (watch the file 'errorTrace.stx'):

                                                                [exBegin]

        Exception emergencyHandler:(Exception dumpingEmergencyHandler)

                                                                [exEnd]

    A handler which sends you mail:

                                                                [exBegin]

        Exception emergencyHandler:(Exception mailingEmergencyHandler)

                                                                [exEnd]

"

! !

!Exception class methodsFor:'initialization'!

initialize 

    "setup the signal used to handle unhandled signals"

    RecursiveExceptionSignal isNil ifTrue:[

	RecursiveExceptionSignal := ErrorSignal newSignalMayProceed:false.

	RecursiveExceptionSignal nameClass:self message:#recursiveExceptionSignal.

	RecursiveExceptionSignal notifierString:'recursive signal raise in handler'

    ]

! !

!Exception class methodsFor:'instance creation'!

signal:aSignal parameter:aParameter errorString:aString suspendedContext:sContext

    "create a new instance and set the fields in preparation for a raise.

     - only to be sent from the signal when raising"

    ^ (self new)

	signal:aSignal 

	parameter:aParameter 

	errorString:aString 

	suspendedContext:sContext 

	originator:(sContext receiver).

!

signal:aSignal parameter:aParameter errorString:aString suspendedContext:sContext originator:origin

    "create a new instance and set the fields in preparation for a raise.

     - only to be sent from the signal when raising"

    ^ (self new)

	signal:aSignal 

	parameter:aParameter 

	errorString:aString 

	suspendedContext:sContext 

	originator:origin.

! !

!Exception class methodsFor:'Signal constants'!

recursiveExceptionSignal

    "return the signal used to handle recursive signals in the handlers"

    ^ RecursiveExceptionSignal

! !

!Exception class methodsFor:'defaults'!

emergencyHandler

    "return the handler used for unhandled exceptions.

     If no EmergencyHandler has been set, a handler which enters the 

     debugger is returned.

     The debugger is opened by asking the signal for a debug action,

     this allows to provide other debuggers in specialized (subclass-instances)

     of Signal (if that is ever needed)"

    "

     set it up, when called the first time

    "

    EmergencyHandler isNil ifTrue:[

	EmergencyHandler := [:ex |

	    "

	     sending it to the signal allows per-signal specific

	     debuggers to be implemented in the future

	     (for example, segv in primitive code could show things 

	      on the C-level ..)

	    "

	    (ex signal) enterDebuggerWith:ex message:(ex errorString).

	]

    ].

    ^ EmergencyHandler

    "Modified: 15.1.1997 / 20:50:37 / cg"

!

emergencyHandler:aOneArgBlock

    "set the handler used for unhandled exceptions.

     The default (a nil-handler) leads to a debugger to be shown."

    EmergencyHandler := aOneArgBlock

    "ST-80 behavior of first showing a notifier:

     (I prefer to get right into the debugger, though)

     Exception

	emergencyHandler:

	    [:ex | self errorNotify:ex errorString ]

    "

    "ST-X behavior of going right into the debugger:

     Exception

	emergencyHandler:nil

    "

    "automatically aborting current operation, on error:

     (may be useful for end-user apps; make certain, 

      you have abortSignal handlers at appropriate places)

     Exception

	emergencyHandler:

	    [:ex | Object abortSignal raise. ex return. ]

    "

    "finally, traditional language system behavior; dump core ;-)

     Exception

	emergencyHandler:

	    [:ex | Smalltalk exitWithCoreDump. ]

    "

    "Modified: 15.1.1997 / 20:49:06 / cg"

! !

!Exception class methodsFor:'useful handlers'!

abortingEmergencyHandler

    "return a block (usable as an emergency handler), 

     which aborts after showing a warnBox.

     This is useful for endUser applications"

    ^ [:ex | self warn:'Error: ' , ex errorString.

	     AbortSignal raise 

      ]

    "test with (try a few halts or CTRL-C's):

     Exception emergencyHandler:(Exception abortingEmergencyHandler)

    "

    "back with:

     Exception emergencyHandler:(Exception notifyingEmergencyHandler)

     Exception emergencyHandler:nil

    "

    "Created: 15.1.1997 / 20:13:06 / cg"

    "Modified: 15.1.1997 / 20:15:02 / cg"

!

dumpingEmergencyHandler

    "return a block (usable as an emergency handler), 

     which dumps the stackBacktrace to a trace file and

     aborts after showing a warnBox.

     This is useful, for endUser application, which are still being

     debugged (i.e. the programmers may have a look at the traceFile

     from time to time).

     Notice:

         The code below is just an example; you may want to change the

         name of the error-file in your application

         (but please: copy the code; do not modify here)"

    ^ [:ex | 

             |str printedException|

             ex signal == Signal noHandlerSignal ifTrue:[

                printedException := ex parameter.

             ] ifFalse:[

                printedException := ex

             ].

             "/ user interruption is handled specially:

             "/ allow user to choose between proceeding or aborting

             "/ but never dump that information to the file.

             printedException signal == Object userInterruptSignal ifTrue:[

                  (self confirm:'abort current action ?') ifTrue:[

                      AbortSignal raise

                  ].

                  ex proceed

             ].

             "/

             "/ dump it to 'errorTrace.stx'

             "/

             str := 'errorTrace.stx' asFilename appendingWriteStream.

             str nextPutLine:('******************************* '

                              , AbsoluteTime now printString

                              , ' *******************************').

             str cr.

             str nextPutLine:('** Error: ' , printedException errorString).

             str nextPutLine:('** Signal: ' , printedException signal printString).

             str nextPutLine:('** Parameter: ' , printedException parameter printString).

             str nextPutLine:('** Process: ' , Processor activeProcess printString).

             str nextPutLine:('** Backtrace:').

             str cr.

             printedException suspendedContext fullPrintAllOn:str.

             str cr.

             str cr.

             str close.

             "/ send a line to stdErr

             ('[warning]: ignored error: ' , printedException errorString) errorPrintCR.

             ('[warning]:    error information appended to ''errorTrace.stx''') errorPrintCR.

             AbortSignal raise 

      ]

    "test with (try a few halts or CTRL-C's):

     Exception emergencyHandler:(Exception dumpingEmergencyHandler)

    "

    "back with:

     Exception emergencyHandler:(Exception notifyingEmergencyHandler)

     Exception emergencyHandler:nil

    "

    "Created: 15.1.1997 / 20:14:52 / cg"

    "Modified: 24.1.1997 / 20:36:21 / cg"

!

mailingEmergencyHandler

    "return a block (usable as an emergency handler), 

     which shows a warnBox and optionally mails a stackBacktrace to a maintainer.

     This is useful, for endUser application, which are still being

     debugged (i.e. the programmers may have a look at the errors).

     Notice: the stuff here is a demonstration only; it should be modified

	     for your particular environment ...

	     ... but please: copy the code and modify there;

	     leave the stuff below as it is."

    ^ [:ex | 

	    |str printedException doMail emergencyMailReceiver pipe|

	    ex signal == Signal noHandlerSignal ifTrue:[

	       printedException := ex parameter.

	    ] ifFalse:[

	       printedException := ex

	    ].

	     "/ user interruption is handled specially:

	     "/ allow user to choose between proceeding or aborting

	     "/ but never dump that information to the file.

	     printedException signal == Object userInterruptSignal ifTrue:[

		  (self confirm:'abort current action ?') ifTrue:[

		      AbortSignal raise

		  ].

		  ex proceed

	     ].

	    "/ somehow get the name of the guy to receive the mail

	    "/ you have to implement that yourself.

	    "/ emergencyMailReceiver := OneOfYourClass getEmergencyMailReceiver.

	    emergencyMailReceiver := OperatingSystem getLoginName.

	    emergencyMailReceiver isNil ifTrue:[

		self warn:(printedException errorString 

			   , '\\No mailing to service people possible.') withCRs.

		doMail := false.

	    ] ifFalse:[

		doMail := self confirm:(printedException errorString 

					, '\\Mail error information to the service people (' 

					, emergencyMailReceiver , ') ?') withCRs

	    ].

	    doMail ifTrue:[

		str := '' writeStream.

		str nextPutLine:('Error notification from '

				, OperatingSystem getLoginName

				, '@'

				, OperatingSystem getHostName).

		str cr.

		str nextPutLine:('Time: ' , AbsoluteTime now printString).

		str nextPutLine:('Error: ', printedException errorString).

		str nextPutLine:('Signal: ', printedException signal printString).

		str nextPutLine:('Parameter: ', printedException parameter printString).

		str nextPutLine:('Process: ', Processor activeProcess printString).

		str nextPutLine:'Backtrace:'.

		str cr.

		printedException suspendedContext fullPrintAllOn:str.

		str cr;cr.

		str close.

		pipe := PipeStream 

			    writingTo:'mail ', emergencyMailReceiver.

		pipe notNil ifTrue:[

		    pipe nextPutLine:'Subject: automatic error report'.

		    pipe nextPutAll:str contents.

		    pipe cr.

		    pipe close.

		]

	     ].

	     AbortSignal raise 

      ]

    "test with (try a few halts or CTRL-C's):

     Exception emergencyHandler:(Exception mailingEmergencyHandler)

    "

    "back with:

     Exception emergencyHandler:(Exception notifyingEmergencyHandler)

     Exception emergencyHandler:nil

    "

    "Created: 15.1.1997 / 20:14:52 / cg"