"

 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

                                resumeBlock rejectBlock'

         classVariableNames:'EmergencyHandler'

         poolDictionaries:''

         category:'Kernel-Exceptions'

!

Exception comment:'

COPYRIGHT (c) 1993 by Claus Gittinger

              All Rights Reserved

'!

!Exception class methodsFor:'documentation'!

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 handler. The following actions are possible:

        reject          - dont handle this signal;

                          another handler will be searched for, 

                          upper in the calling hierarchy

        proceed         - continue after the Signal>>raise, returning nil as value

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

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

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

        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:

instance variables:

        signal          - the signal which caused the exception

        parameter       - a parameter (if any) which was passed when raising

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

        errorString     - an errorString (only if raised wiith #raiseWith:errorString:)

        suspendedContext- the context where the signal raise occured

        handlerContext  - the context of the handler itself

        resumeBlock     - private to the exception; needed to perform resume action

        rejectBlock     - private to the exception; needed to perfomr reject action

No Emergency mechanism is currently implemented - an unhandled signal currently

goes always into the debugger; the method found dealing with it exist only

for compatibility reasons only.

"

! !

!Exception class methodsFor:'initialization'!

initialize

    EmergencyHandler := [:ex :con |

        (ex signal) error:('unhandled exception: ' , ex signal notifierString)

    ]

! !

!Exception class methodsFor:'defaults'!

emergencyHandler

    "return the handler used for unhandled exceptions"

    ^ EmergencyHandler

!

emergencyHandler:aTwoArgBlock

    "set the handler used for unhandled exceptions"

    EmergencyHandler := aTwoArgBlock

! !

!Exception methodsFor:'accessing'!

signal

    "return the signal, that caused the exception"

    ^ signal

!

parameter

    "return the parameter passsed with the signal raise

     (or nil, if there was none)"

    ^ parameter

!

errorString 

    "return the errorString passsed with the signal raise

     (or nil, if there was none)"

    ^ errorString

!

handlerContext

    "return the context of the handler"

    ^ handlerContext

!

suspendedContext

    "return the context in which the raise occured"

    ^ suspendedContext

! !

!Exception methodsFor:'setup'!

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

    "set the fields usable for inspection by the handler

     - only to be sent from the signal when raising"

    signal := aSignal.

    parameter := aParameter.

    errorString := aString.

    suspendedContext := sContext.

!

handlerContext:aContext

    "set the context of the handler.

     - only to be sent from the signal when raising"

    handlerContext := aContext

!

rejectBlock:aBlock

    "this is meant to be sent by Signal only"

    rejectBlock := aBlock

!

resumeBlock:aBlock

    "this is meant to be sent by Signal only"

    resumeBlock := aBlock

! !

!Exception methodsFor:'handler actions'!

reject

    "handler decided not to handle this signal -

     system will look for another handler"

    rejectBlock value

!

resume

    "Continue after the raise - the raise returns nil"

    resumeBlock value:nil

!

resumeWith:value

    "Continue after the raise - the raise returns value"

    resumeBlock value:value

!

proceed

    "Continue after the raise - the raise returns nil"

    resumeBlock value:nil

!

proceedWith:value

    "Continue after the raise - the raise returns value"

    resumeBlock value:value

!

return

    "Continue after the handle:do: - the handle:do: returns nil"

    handlerContext resume

!

returnWith:value

    "Continue after the handle:do: - the handle:do: returns value"

    handlerContext resume:value

!

restart

    "restart the handle:do: - usually after some repair work is done

     in handler"

    handlerContext restart

! !