"

 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.

"

"{ Package: 'stx:libbasic' }"

Object subclass:#GenericException

	instanceVariableNames:'signal parameter errorString suspendedContext handlerContext

		rejected originator proceedable handlingException'

	classVariableNames:'StrictRaising'

	poolDictionaries:''

	category:'Kernel-Exceptions'

!

GenericException class instanceVariableNames:'NotifierString'

"

 No other class instance variables are inherited by this class.

"

!

!GenericException 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

"

    Note: 

        The instance based Signal framework is being replaced by

        class based exceptions.

        I.e. what used to be instances of Signal/QuerySignal is beeing

        rewritten into subclasses of Exception/Error/Query and Warning.

        Although the functionality is basically unchanged, the new

        class based exceptions are easier to instanciate (no need for

        creation in a classes initialize method), easier to use (no real

        need for SIgnal-constant accessors) and allow for easier parameter

        passing (not only a single parameter, but allows for individual

        exception subclasses to add additional state).

    GenericException and its subclasses implement the same protocol as Signal.

    So class based exceptions may be implemented as subclasses of GenericException.

    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          - don't 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)

    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]

    Raising:

        two different raising messages are to be used, 

        depending on whether the exception is proceedable or not

        For some stupid reason, someone decided that the raise-code checks if

        the raising messages matches to what the signal thinks is its proceedability.

        (i.e. not only do both the sender and the signal itself specify proceedability,

         this is checked by the raise code and a warning is generated if there is a mismatch)

        This used to be even worse (WrongProceedabilityError), but we relaxed this to

        a message sent to stderr.

        That means, that PROCEEDABLE signals must be raised with:

            raiseRequest

        and NON-PROCEEDABLE signals must be raised with:

            raise

        If you dont know/care as a raiser, you can use

            raiseSignal

        which checks for proceedability and sends the appropriate message.

        (sigh)

    all of the 3 messages above come in various flavours:

        raiseXXX                - do not pass any additional parameter;

                                  default errorString

        raiseXXXWith:           - pass additional parameter;

                                  default errorString

        raiseXXXErrorString:    - do not pass any additional parameter;

                                  given errorString

        raiseXXXWith:errorString:

                                - pass any additional parameter;

                                  AND given errorString

    [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. See the examples in NoHandlerError.

"

! !

!GenericException class methodsFor:'initialization'!

initialize 

    NotifierString := 'unknown exception'.

    StrictRaising := false.     "set to true to check weather a signal may be raised proceedable"

    "Modified: / 4.8.1999 / 09:06:26 / stefan"

! !

!GenericException class methodsFor:'instance creation'!

signal:aSignal originator:origin

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

     - only to be sent from the signal when raising"

    "{ Pragma: +inlineNew }"

    ^ (self basicNew) signal:aSignal originator:origin.

    "Created: / 23.7.1999 / 13:40:45 / stefan"

!

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"

    "{ Pragma: +inlineNew }"

    ^ (self basicNew)

        signal:aSignal 

        parameter:aParameter 

        errorString:aString 

        suspendedContext:sContext 

        originator:origin.

! !

!GenericException class methodsFor:'Compatibility - ANSI'!

raiseSignal:errorMessage

    "actually raise an exception (whatever the proceedability is)."

    ^ self raiseSignal:errorMessage with:nil

!

raiseSignal:errorMessage with:aParameter

    "actually raise an exception (whatever the proceedability is)."

    self mayProceed ifFalse:[

        ^ self raiseWith:aParameter errorString:errorMessage

    ].

    ^ self raiseRequestWith:aParameter errorString:errorMessage

!

signalWith:errorString

    self raiseErrorString:errorString

! !

!GenericException class methodsFor:'Compatibility - Dolphin'!

signal:errorString

    "raise a signal proceedable or nonproceedable (whichever is right).

     The argument is used as errorString."

    <context: #return>

    ^ (self newException 

        suspendedContext:thisContext sender

        errorString:errorString)

            raiseSignal.

! !

!GenericException class methodsFor:'Signal constants'!

noHandlerError

    ^ NoHandlerError

    "Created: / 4.8.1999 / 08:33:35 / stefan"

!

proceedError

    ^ ProceedError

    "Created: / 4.8.1999 / 08:34:30 / stefan"

!

recursiveExceptionError

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

    ^ RecursiveExceptionError

    "Created: / 4.8.1999 / 09:05:06 / stefan"

!

recursiveExceptionSignal

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

     This is for backward compatinility. Use recursiveExceptionError"

    ^ RecursiveExceptionError

    "Modified: / 4.8.1999 / 09:05:59 / stefan"

!

wrongProceedabilityError

    ^ WrongProceedabilityError

    "Created: / 4.8.1999 / 08:34:19 / stefan"

! !

!GenericException class methodsFor:'accessing'!

notifierString:aString

    NotifierString := aString

! !

!GenericException class methodsFor:'compatibility - accessing'!

errorString

    "#errorString is deprecated, use description instead"

    <resource:#obsolete>

    ^ self description

!

handlerBlock

    "Compatibility with Signal. Class based exeptions do not have a handler

     block. They redefine the #action method instead"

    ^ nil

    "Created: / 23.7.1999 / 14:43:18 / stefan"

    "Modified: / 24.7.1999 / 20:52:10 / stefan"

! !

!GenericException class methodsFor:'compatibility - defaults'!

emergencyHandler

    ^ NoHandlerError emergencyHandler.

!

emergencyHandler:aOneArgBlock

    "set the handler used for unhandled exceptions.

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

    ^ NoHandlerError 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"

! !

!GenericException class methodsFor:'compatibility - queries'!

accepts:aSignal

    "return true, if the receiver accepts the argument, aSignal.

     (i.e. the receiver is aSignal or a parent of it). False otherwise."

    |s|

    self == aSignal ifTrue:[^ true].

    aSignal isQuerySignal ifTrue:[^ false].

    s := aSignal.

    [s notNil] whileTrue:[

        self == s ifTrue:[^ true].

        s := s parent

    ].

    ^ false

    "Created: / 23.7.1999 / 14:00:47 / stefan"

!

exception:anExceptionOrSignal isHandledIn:aContext

    "return true, if there is a handler for the receiver signal in the 

     contextChain starting with aContext."

    |con r|

    con := Context findFirstSpecialHandle:true raise:false.

    [con notNil] whileTrue:[

        ((r := con receiver) notNil

         and:[(r handlerForSignal:anExceptionOrSignal context:con originator:nil) notNil]

        ) ifTrue:[

            "found a handler context"

            ^ true

        ].

        con := con findSpecialHandle:true raise:false.

    ].

    ^ false

!

handlerForSignal:signal context:theContext originator:originator

    "answer the handler block for the signal from originator.

     The block is retrieved from aContext.

     Answer nil if the signal is not handled"

    (theContext selector ~~ #'handle:from:do:'

     or:[(theContext argAt:2) == originator]) ifTrue:[

        (self == signal or:[self accepts:signal]) ifTrue:[

            ^ theContext argAt:1

        ]

    ].

    ^ nil

    "Created: / 25.7.1999 / 19:52:58 / stefan"

!

handlerProtectedBlock:doBlock inContext:context

    "set the handlerProtectedBlock in context"

    |sel|

    sel := context selector.

    sel == #handle:do: ifTrue:[

        context argAt:2 put:doBlock.

    ] ifFalse:[sel == #handle:from:do: ifTrue:[

        context argAt:3 put:doBlock.

    ]].

!

handlingExceptionInContext:theContext

    "answer the handling exception from aContext."

    |sel|

    sel := theContext selector.

    (sel == #'handle:from:do:'

     or:[sel == #'handle:do:']) ifTrue:[

        ^ theContext receiver

    ].

    ^ nil

!

inheritsFrom:anotherSignal

    "return true, if the receiver is a child of anotherSignal

     (i.e. if handling anotherSignal also handles the receiver)

     This is almost the same as accepts, but returns false, if

     the receiver is identical to anotherSignal."

    self == anotherSignal ifTrue:[^ false].

    ^ anotherSignal accepts:self

    "Created: / 23.7.1999 / 13:59:51 / stefan"

!

isExceptionCreator

    "return true, if the receiver can create exceptions,

     this includes #raise, #raiseRequest as well as the behavior of

     an exception handler, such as the #accepts: and #handles: messages"

    ^ true

!

isExceptionHandler

    "return true, if the receiver responds to the exception handler protocol,

     especially to the #accepts: and #handles: messages"

    ^ true

    "Created: / 23.7.1999 / 13:49:59 / stefan"

!

isHandled

    "return true, if there is a handler for the receiver signal.

     Raising an unhandled signal will usually lead into the debugger,

     but can be caught globally by setting Exceptions EmergencyHandler."

    ^ self exception:self isHandledIn:(thisContext sender).

    "Created: / 23.7.1999 / 14:03:50 / stefan"

!

isHandledIn:aContext

    "return true, if there is a handler for the receiver signal in the 

     contextChain starting with aContext."

    ^ self exception:self isHandledIn:aContext

!

isQuerySignal

    "return true, if this is a querySignal - always return false here"

    ^ false

    "Created: / 23.7.1999 / 13:50:16 / stefan"

!

mayProceed

    "return true, if the exception handler is allowed to proceed

     the execution where the exception occured.

     Subclasses may redefine this."

    ^ true

    "Modified: / 23.7.1999 / 14:50:11 / stefan"