"
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:#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
"
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"
!
proceedErrorSignal
"return the signal used to indicate that a handler tried to
proceed a signal marked as nonproceedable.
The parameter for the exception raised by this signal is
the exception which tried to proceed."
^ ProceedError
"Created: / 27.2.1998 / 14:36:15 / stefan"
"Modified: / 4.8.1999 / 08:00:20 / stefan"
!
wrongProceedabilitySignal
"return the signal used to indicate that a signaler wants
to raise a nonproceedable signal proceedable.
The parameter for the exception raised by this signal is
the unproceedable signal."
^ WrongProceedabilityError
"Created: / 27.2.1998 / 14:24:19 / stefan"
"Modified: / 4.8.1999 / 08:03:46 / stefan"
! !
!Signal methodsFor:'accessing'!
errorString
"#errorString is deprecated, use description instead"
^ 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
!
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:'copying'!
deepCopyUsing:aDictionary
"raise an error - deepCopy is not allowed for signals"
^ self deepCopyError
"Created: / 31.3.1998 / 15:43:01 / cg"
! !
!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'!
description
"return the notifier string.
If the notifier string starts with space, prepend
the parents notifier string"
notifierString isNil ifTrue:[
^ parent errorString
] ifFalse:[
(notifierString startsWith:Character space) ifTrue:[
^ parent description, notifierString
] ifFalse:[
^ notifierString
].
]
"
Object errorSignal description
"
"Modified: / 12.3.1998 / 15:04:41 / stefan"
!
printOn:aStream
"append a printed representation of the receiver on aStream"
nameClass notNil ifTrue:[
aStream nextPutAll:nameClass name.
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.
[s notNil] whileTrue:[
self == s ifTrue:[^ true].
s := s parent
].
^ false
"Modified: / 22.3.1999 / 12:45:42 / stefan"
!
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: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.
]].
!
handlingExceptionInContext:theContext
"answer the handling signal from aContext."
^ self
!
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
"Modified: / 6.6.1998 / 20:37:47 / cg"
!
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 isHandledIn:(thisContext sender).
!
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:self context:con originator:nil) notNil]
) ifTrue:[
"found a handler context"
^ true
].
con := con findSpecialHandle:true raise:false.
].
^ false
"Created: / 23.7.1999 / 14:03:34 / stefan"
"Modified: / 26.7.1999 / 15:24:34 / stefan"
!
isQuerySignal
"return true, if this is a querySignal - always return false here"
^ false
"Modified: 22.4.1996 / 13:45:06 / cg"
!
isSignal
"return true, if the receiver is some kind of signal;
true returned here - the method is redefined from Object."
^ true
! !
!Signal methodsFor:'raising'!
newException
"answer a new exception object for this signal.
Subclasses may redefine this method"
^ Exception signal:self originator:nil
"Created: / 26.2.1998 / 19:53:56 / stefan"
"Modified: / 23.7.1999 / 13:41:00 / stefan"
!
newExceptionFrom:originator
"answer a new exception object for this signal.
Set the originator.
Subclasses may redefine this method"
^ Exception signal:self originator:originator
"Created: / 27.2.1998 / 09:17:00 / stefan"
"Modified: / 23.7.1999 / 13:41:15 / stefan"
!
raise
"raise a signal nonproceedable.
The signals notifierString is used as errorString."
<context: #return>
^ self newException
suspendedContext:thisContext sender;
raise
"Modified: / 2.5.1996 / 16:36:23 / cg"
"Modified: / 5.3.1998 / 16:44:36 / stefan"
!
raiseErrorString:aString
"raise a signal nonproceedable.
The argument is used as errorString."
<context: #return>
^ self newException
suspendedContext:thisContext sender;
errorString:aString;
raise.
"Modified: / 9.5.1996 / 15:17:59 / cg"
"Modified: / 12.3.1998 / 15:15:22 / stefan"
!
raiseFrom:something
"raise a signal nonproceedable.
The argument, something is passed both as parameter and originator."
<context: #return>
^ (self newExceptionFrom:something)
suspendedContext:thisContext sender;
parameter:something;
raise
"Modified: / 2.5.1996 / 16:36:38 / cg"
"Modified: / 5.3.1998 / 16:49:55 / stefan"
!
raiseRequest
"raise a signal proceedable.
The signals notifierString is used as errorString."
<context: #return>
^ self newException
suspendedContext:thisContext sender;
raiseRequest.
"Modified: / 2.5.1996 / 16:36:52 / cg"
"Modified: / 5.3.1998 / 16:50:46 / stefan"
!
raiseRequestFrom:something
"raise a signal proceedable.
The argument, something is passed both as parameter and originator."
<context: #return>
^ (self newExceptionFrom:something)
suspendedContext:thisContext sender;
parameter:something;
raiseRequest.
"Modified: / 2.5.1996 / 16:36:38 / cg"
"Modified: / 5.3.1998 / 16:52:46 / stefan"
!
raiseRequestWith:aParameter
"raise a signal proceedable.
The signals notifierString is used as errorString."
<context: #return>
^ self newException
suspendedContext:thisContext sender;
parameter:aParameter;
raiseRequest.
"Modified: / 9.5.1996 / 15:13:20 / cg"
"Modified: / 12.3.1998 / 15:16:57 / stefan"
!
raiseRequestWith:aParameter errorString:aString
"raise a signal proceedable.
The argument, aString is used as errorString."
<context: #return>
^ self newException
suspendedContext:thisContext sender;
parameter:aParameter;
errorString:aString;
raiseRequest
"Modified: / 9.5.1996 / 15:13:35 / cg"
"Modified: / 12.3.1998 / 15:17:52 / stefan"
!
raiseRequestWith:aParameter errorString:aString in:aContext
"raise a signal proceedable.
The argument, aString is used as errorString.
The additional context is passed as the context responsible for the raise,
allowing a raise to mimicri the exception happened somewhere else."
^ self newException
parameter:aParameter;
errorString:aString;
suspendedContext:aContext;
raiseRequest
"Modified: / 26.7.1996 / 16:29:27 / cg"
"Modified: / 12.3.1998 / 15:18:34 / stefan"
!
raiseWith:aParameter
"raise a signal nonproceedable.
The argument, aParameter is passed as parameter."
<context: #return>
^ self newException
suspendedContext:thisContext sender;
parameter:aParameter;
raise.
"Modified: / 9.5.1996 / 15:14:24 / cg"
"Modified: / 12.3.1998 / 15:19:11 / stefan"
!
raiseWith:aParameter errorString:aString
"raise a signal nonproceedable.
The argument, aString is used as errorString, aParameter is passed
as exception parameter."
<context: #return>
^ self newException
suspendedContext:thisContext sender;
parameter:aParameter;
errorString:aString;
raise.
"Modified: / 9.5.1996 / 15:14:32 / cg"
"Modified: / 12.3.1998 / 15:19:40 / stefan"
!
raiseWith:aParameter errorString:aString in:aContext
"raise a signal nonproceedable.
The argument, aString is used as errorString, aParameter is passed
as exception parameter.
The additional context is passed as the context responsible for the raise,
allowing a raise to mimicri the exception happened somewhere else."
^ self newException
parameter:aParameter;
errorString:aString;
suspendedContext:aContext;
raise.
"Created: / 2.5.1996 / 16:37:25 / cg"
"Modified: / 26.7.1996 / 16:29:42 / cg"
"Modified: / 12.3.1998 / 15:20:12 / stefan"
! !
!Signal methodsFor:'save evaluation'!
catch:aBlock
"evaluate the argument, aBlock.
If the receiver-signal is raised during evaluation, abort
the evaluation and return true; otherwise return false.
This is the catch & throw mechanism found in other languages,
where the returned value indicates if an exception occured."
|raiseOccurred|
raiseOccurred := false.
self handle:[:ex | raiseOccurred := true. ex return] do:aBlock.
^ raiseOccurred
"
Object messageNotUnderstoodSignal catch:[
123 size open
]
"
!
handle:handleBlock do:aBlock
"evaluate the argument, aBlock.
If the receiver-signal is raised during evaluation,
evaluate the handleBlock passing it an Exception argument.
The handler may decide how to react to the signal by sending
a corresponding message to the exception (see there).
If the signal is not raised, return the value of evaluating
aBlock."
<context: #return>
<exception: #handle>
"/ thisContext markForHandle. -- same as above pragma
^ aBlock value "the real logic is in Exception>>doRaise"
"
Object messageNotUnderstoodSignal handle:[:ex |
'oops' printNL.
ex return
] do:[
123 size open
]
"
"
|num|
num := 0.
Number divisionByZeroSignal handle:[:ex |
'oops' printNL.
ex return
] do:[
123 / num
]
"
"Modified: / 25.7.1999 / 19:43:01 / stefan"
!
handle:handleBlock from:anObject do:aBlock
"evaluate the argument, aBlock.
If the receiver-signal is raised during evaluation,
and the exception originated from anObject,
evaluate the handleBlock passing it an Exception argument.
The handler may decide how to react to the signal by sending
a corresponding message to the exception (see there).
If the signal is not raised, return the value of evaluating
aBlock."
<context: #return>
<exception: #handle>
"/ thisContext markForHandle. -- same as above pragma
^ aBlock value "the real logic is in Exception>>doRaise"
"
the first open will be caught; the second not:
|o1 o2|
o1 := 123.
o2 := nil.
Object messageNotUnderstoodSignal
handle:
[:ex |
'oops' printNL.
ex proceed
]
from:o1
do:
[
o1 open.
o2 open
]
"
"Modified: / 25.7.1999 / 19:43:40 / stefan"
!
ignoreIn:aBlock
"evaluate the argument, aBlock.
Ignore the receiver-signal during evaluation - i.e. simply continue.
This makes only sense for some signals, such as UserInterrupt
or AbortSignal, because continuing after an exception without any cleanup
often leads to followup-errors."
^ self handle:[:ex | ex proceedWith:nil] do:aBlock.
"
Object messageNotUnderstoodSignal ignoreIn:[
123 size open
]
"
! !
!Signal class methodsFor:'documentation'!
version
^ '$Header: /cvs/stx/stx/libbasic/Signal.st,v 1.72 1999-08-04 20:18:39 stefan Exp $'
! !