"

 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:#Signal

	instanceVariableNames:'mayProceed notifierString nameClass message handlerBlock parent'

	classVariableNames:''

	poolDictionaries:''

	category:'Kernel-Exceptions'

!

!Signal 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).

	However, the old Signal hierarchy will remain in existance, since it allows

	funny instance-specific and anonymous exception handling schemes to be

	implemented, which are hard to built using class-based exceptions.

    Signal and Exception provide a framework for exception handling.

    A Signal object is usually defined somewhere up in the calling chain

    and associated with some abnormal event. Many signals are also

    created at startup time and reused.

    When the event is raised (by Signal>>raise) the control will be either

    given to a debugger or - if a handler was defined - to the handler.

    The handler will get a description of what (and where) happened in an

    Exception object and can decide how to react on the situation (i.e.

    proceed, return or restart).

    There is also a companion class called SignalSet, which allows handling

    multiple signals with one handler (for example all arithmetic signals).

    And, finally there is a very special SignalSet which allows catching

    any signal (SignalSet>>anySignal).

    Since there is no official documentation on signal handling (i.e. none

    of the books describes it), this Signal implementation has been modeled

    after what some PD programs seem to expect and what alpha/beta testers told

    me it should look like.

    It may not be perfect and undergo minor changes.

    special:

    In addition to the nested catch & throw mechanism, signals can also be

    used when no such handler scope exists. To support this, signals can be

    assigned a handlerBlock, which gets evaluated with the exception as argument

    in case no handler was found (on the stack).

    If no handler was found (i.e. neither a handler context on the stack, nor

    a static handler block), the NoHandlerSignal will be raised instead,

    passing it the original exception in its exception-parameter.

    This NoHandlerSignal can be handled just like any other signal.

    (therefore, it is possible to catch any error by catching NoHandlerSignal.

    When the NoHandler signal is raised, and neither a handler-context, nor

    a handler block is defined for it, an emergencyHandler(-block) is evaluated.

    This block is either provided by the current process

    (see Process>>emergencySignalHandler) or as a global default by the Exception

    class (see Exception>>emergencyHandler).

    The default emergencyHandlerBlock (from Exception) will bring up a debugger.

    HandlerBlocks allow a global (if its the EmergencyHandler in Exception)

    or per-process signal handling to be added. Even to code which was never

    planned to handle signals.

    See samples in 'doc/coding' and actual raise code in Exception.

    [Instance variables:]

	mayProceed      <Boolean>       hint for the debugger - program may

					proceed (currently not honored by the

					debugger)

	notifierString  <String>        error message to be output

	nameClass       <Class>         for the printOn-implementation; nameClass

					is the class, to which message (below)

					should be sent to create the receiver.

	message         <Symbol>        for the printOn-implementation; message

					is the selector, which should be sent to

					nameClass (above) to create the receiver.

	handlerBlock    <Block>         if nonNil, a 1-arg block to be

					evaluated when no handler context is

					found. The block gets the exception

					object as argument. This will play the role

					of an on-stack handler.

    [author:]

	Claus Gittinger

    [see also:]

	GenericException

	SignalSet QuerySignal

	Object

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

"

! !

!Signal class methodsFor:'instance creation'!

new

    "return a new signal"

    ^ (self basicNew) notifierString:'signal'; mayProceed:true

    "

     Signal new

    "

    "Modified: 8.10.1997 / 11:51:39 / cg"

! !

!Signal class methodsFor:'Signal constants'!

genericSignal

    "return the generic signal - thats the parent of all signals

     in the system."

    ^ GenericException

    "Created: / 8.10.1997 / 11:46:28 / cg"

    "Modified: / 8.10.1997 / 11:47:08 / cg"

    "Modified: / 4.8.1999 / 08:54:33 / stefan"

!

noHandlerSignal

    "return the signal used to handle unhandled signals"

    ^ NoHandlerError

    "Modified: / 4.8.1999 / 08:10:09 / stefan"

! !

!Signal methodsFor:'Compatibility-ANSI'!

signalWith:messageText

    "ANSI compatibility"

    self raiseErrorString:messageText

! !

!Signal methodsFor:'Compatibility-VW'!

messageText:aString

    ^ self notifierString:aString

!

new

    "create a new signal, using the receiver as a prototype and

     setting the parent of the new signal to the receiver."

    ^ self newSignal

! !

!Signal methodsFor:'accessing'!

creator

    "return the creator of the exception (for exception protocol compatibilty).

     For class based exceptions, that is the exception class;

     for signals, that is the signal itself."

    ^ self

!

errorString

    "errorString is deprecated, use description instead"

    <resource:#obsolete>

    ^ self description

!

handlerBlock

    "return the handlerblock - if non-nil, this will be evaluated with the exception

     object as argument, if no #handle:do: context was found on the stack."

    ^ handlerBlock

!

handlerBlock:aOneArgBlock

    "set the handlerblock - this will be evaluated with the exception

     object as argument, if no #handle:do: context was found on the stack."

    handlerBlock := aOneArgBlock

!

mayProceed

    "return the signals ability to proceed.

     This flag is (currently) not checked by the system;

     be prepared for changes here, to eventually have nonProceedable

     signals refuse to let you continue execution."

    ^ mayProceed

!

mayProceed:aBoolean

    "set/clear the signals ability to proceed.

     This flag is (currently) not checked by the system;

     be prepared for changes here, to eventually have nonProceedable

     signals refuse to let you continue execution."

    mayProceed := aBoolean

!

nameClass:aClass message:aSelector

    "this sets the class & selector of a method which returns

     that signal - this is simply for documentation purposes -

     see Signal>>printOn: implementation.

     (took me a while to find that one out ;-)"

    nameClass := aClass.

    message := aSelector

!

notifierString

    "return the notifier string"

    ^ notifierString

!

notifierString:aString

    "set the notifier string"

    notifierString := aString

!

originalSignal

    "return the signal/exception which was originally raised.

     For noHandler, that is my unhandled signal; for others, thats the exception itself."

    ^ self.

!

parent

    "return the parent-signal of the receiver"

    ^ parent

!

parent:aSignal

    "set the parent-signal of the receiver."

    parent := aSignal

!

parent:aSignal mayProceed:aBoolean

    "set the parent-signal and the mayProceed flag of the receiver."

    parent := aSignal.

    mayProceed := aBoolean.

    "Modified: 8.10.1997 / 11:56:11 / cg"

! !

!Signal methodsFor:'converting'!

, anExceptionHandler

    "return a SignalSet with myself and anExceptionHandler"

    ^ SignalSet with:self with:anExceptionHandler

! !

!Signal methodsFor:'copying'!

deepCopyUsing:aDictionary postCopySelector:postCopySelector

    "raise an error - deepCopy is not allowed for signals"

    ^ self deepCopyError

    "Created: / 31.3.1998 / 15:43:01 / cg"

! !

!Signal methodsFor:'exception creation'!

newException

    "{ Pragma: +inlineNew }"

    "answer a new exception object for this signal.

     Subclasses may redefine this method"

    ^ Exception basicNew creator:self

    "Created: / 26.2.1998 / 19:53:56 / stefan"

    "Modified: / 23.7.1999 / 13:41:00 / stefan"

! !

!Signal methodsFor:'instance creation'!

newSignal

    "create a new signal, using the receiver as a prototype and

     setting the parent of the new signal to the receiver."

    ^ (self copy) parent:self

    "Modified: 8.10.1997 / 11:53:06 / cg"

!

newSignalMayProceed:aBoolean

    "create a new signal, using the receiver as a prototype and

     setting the parent of the new signal to the receiver."

    ^ (self copy) parent:self mayProceed:aBoolean

    "Modified: 8.10.1997 / 11:57:13 / cg"

! !

!Signal methodsFor:'printing & storing'!

description

    "return the notifier string.

     If the notifier string starts with space, prepend

     the parents notifier string"

    |s|

    notifierString isNil ifTrue:[

	^ parent description

    ].

    s := notifierString asString.

    (s startsWith:Character space) ifTrue:[

	^ parent description, s

    ].

    ^ s

    "

     Error description

    "

    "Modified: / 12.3.1998 / 15:04:41 / stefan"

!

descriptionForDebugger

    "return the description string of the signal which is used in the

     debugger title area"

    ^ self description.

!

printOn:aStream

    "append a printed representation of the receiver on aStream"

    nameClass notNil ifTrue:[

	nameClass isBehavior ifTrue:[

	    aStream nextPutAll:nameClass name.

	] ifFalse:[

	    nameClass printOn:aStream.

	].

	aStream space.

	aStream nextPutAll:message.

	^ self

    ].

    ^ super printOn:aStream

! !

!Signal methodsFor:'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 parent.

    [s notNil] whileTrue:[

	self == s ifTrue:[^ true].

	s := s parent

    ].

    ^ false

    "Modified: / 22.3.1999 / 12:45:42 / stefan"

!

catchInDebugger

    "if set, the debugger will handle this signal in its event loop and will close itself

     without asking for close-confirmation.

     This allows for debugged processes to be terminated without a user confirmation dialog

     (for now, this is used in expecco's hard-terminate function to shut down any open debuggers

      together with the test-process)"

    ^ false

!

exceptionHandlerFor:anException in:aContext

    "answer the exceptionHandler for anException from aContext."

    ^ self

!

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]

	]

    ].

    ^ nil

    "Created: / 25.7.1999 / 19:55:43 / stefan"

!

handlerProtectedBlock:doBlock inContext:context

    "set the handlerProtectedBlock in context"

    context selector == #handle:do: ifTrue:[

	context argAt:2 put:doBlock.

    ] ifFalse:[context selector == #handle:from:do: ifTrue:[

	context argAt:3 put:doBlock.

    ]].

!

handles:anException

    "return true, if the receiver handles the argument, anException.

     (i.e. the receiver is anExceptions signal or a parent of it)"

    |signal|

    signal := anException creator.

    self == signal ifTrue:[^ true].               "quick check"

    anException isNotification ifTrue:[^ false].  "speed up queries by not traversing the parent chain"

    [(signal := signal parent) notNil] whileTrue:[

	self == signal ifTrue:[^ true].

    ].

    ^ false

!

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."

    <resource: #obsolete>

    self == anotherSignal ifTrue:[^ false].