Class: Signal

• Inheritance
• Description
• Class protocol
  • Signal constants
  • instance creation
• Instance protocol
  • Compatibility-ANSI
  • Compatibility-VW
  • JavaScript support
  • accessing
  • converting
  • copying
  • exception creation
  • instance creation
  • printing & storing
  • queries
  • raising
  • save evaluation

Inheritance:

   Object
   |
   +--Signal
      |
      +--QuerySignal
      |
      +--VAST::VastSignal

Package:

stx:libbasic

Category:

Kernel-Exceptions

Version:

rev: 1.135 date: 2024/03/26 12:54:28

user: cg

file: Signal.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

Note:
    The instance based Signal framework is being replaced by class based exceptions.
    I.e. what used to be instances of Signal/QuerySignal is being
    rewritten into subclasses of Exception/Error/Query and Warning.

    Although the functionality is basically unchanged, the new
    class based exceptions are easier to instantiate (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 it's 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.

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.

Class protocol:

 genericSignal

return the generic signal - that's the parent of all signals
in the system.

 noHandlerSignal

return the signal used to handle unhandled signals

 new

return a new signal

Usage example(s):

Signal new

Instance protocol:

 signal

ANSI compatibility

 signalWith: messageText

ANSI compatibility

 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.

 js_add: anExceptionHandler
( an extension from the stx:libjavascript package )

For JavaScript only:
Alternative error concatenation.
Generated for +-operator in javascript.

 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.
This used to be called 'signal' in earlier versions,
but due to the conflict with VSE, Squeak and others,
where 'signal' means 'raise', 'signal' was obsoleted by this method.

 errorString

errorString is deprecated, use description instead

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 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: aOneArgBlock

set the handlerblock - this will be evaluated with the exception
object as argument, if no #handle:do: context was found on the stack.

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

 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 ;-)

 notifierString

return the notifier string

 notifierString: aString

set the notifier string

 originalSignal

return the signal/exception which was originally raised.
For noHandler, that is my unhandled signal; for others, that's the exception itself.

 parent

return the parent-signal of the receiver

 parent: aSignal

set the parent-signal of the receiver.

 parent: aSignal mayProceed: aBoolean

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

 , anExceptionHandler

return a SignalSet with myself and anExceptionHandler

 deepCopyUsing: aDictionary postCopySelector: postCopySelector

raise an error - deepCopy is not allowed for signals

 newException

answer a new exception object for this signal.
Subclasses may redefine this method

 newSignal

create a new signal, using the receiver as a prototype and
setting the parent of the new signal to the receiver.

 newSignalMayProceed: aBoolean

create a new signal, using the receiver as a prototype and
setting the parent of the new signal to the receiver.

 description

return the notifier string.
If the notifier string starts with space, prepend
the parents notifier string

Usage example(s):

Error description

 descriptionForDebugger

return the description string of the signal;
this is used in the debugger's title area

 printOn: aStream

append a printed representation of the receiver on aStream

 accepts: aSignalOrExceptionClass

return true, if the receiver accepts the argument, aSignal.
(i.e. the receiver is aSignal or a parent of it). False otherwise.

 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)

 exceptionHandlerFor: anException in: aContext

answer the exceptionHandler for anException from aContext.

 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

 handlerProtectedBlock: doBlock inContext: context

set the handlerProtectedBlock in context

 handles: anException

return true, if the receiver handles the argument, anException.
(i.e. the receiver is anExceptions signal or a parent of it)

 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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 isAbortOperationRequest

 isAcceptedBy: aHandlerSignalOrHandlerExceptionClass

return true, if the aHandlerSignalOrHandlerExceptionClass accepts the receiver.

 isBridgeException

 isControlInterrupt

true if this is a breakpoint or user-interrupt (CTRL-c)

 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

 isExceptionHandler

return true, if the receiver responds to the exception handler protocol,
especially to the #accepts: and #handles: messages

 isHaltInterrupt

 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.

 isHandledIn: aContext

return true, if there is a handler for the receiver signal in the
contextChain starting with aContext.

 isMessageNotUnderstood

 isNotification

 isQuery

return true, if this is a query

 isQuerySignal

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

 isTimeoutException

 isUserInterrupt

 raise

raise a signal nonproceedable.
The signals notifierString is used as messageText.

 raiseErrorString: aString

raise a signal nonproceedable.
The argument is used as messageText.

 raiseErrorString: aString in: aContext

raise a signal nonproceedable.
The argument is used as messageText.

 raiseFrom: something

raise a signal nonproceedable.
The argument, something is passed both as parameter and originator.

 raiseRequest

raise a signal proceedable.
The signals notifierString is used as messageText.

 raiseRequestErrorString: aString

raise a signal proceedable.
The argument, aString is used as messageText.

 raiseRequestFrom: something

raise a signal proceedable.
The argument, something is passed both as parameter and originator.

 raiseRequestWith: aParameter

raise a signal proceedable.
The signals notifierString is used as messageText.

 raiseRequestWith: aParameter errorString: aString

raise a signal proceedable.
The argument, aString is used as messageText.

 raiseRequestWith: aParameter errorString: aString in: aContext

raise a signal proceedable.
The argument, aString is used as messageText.
The additional context is passed as the context responsible for the raise,
allowing a raise to mimicri the exception happened somewhere else.

 raiseRequestWith: aParameter in: aContext

raise a signal proceedable.
The additional context is passed as the context responsible for the raise,
allowing a raise to mimicri the exception happened somewhere else.

 raiseSignal

raise a signal (proceedable or not, whatever the proceedability is).
The signals notifierString is used as messageText.

 raiseSignal: errorMessage

ANSI: raise a signal (proceedable or not, whatever the proceedability is).
The argument, errorMessage is used as messageText.

 raiseSignal: errorMessage with: aParameter

ANSI: raise a signal (proceedable or not, whatever the proceedability is).
The argument, errorMessage is used as messageText.

 raiseSignalErrorString: aString

raise a signal (proceedable or not, whatever the proceedability is).
The argument, aString is used as messageText.

 raiseSignalWith: aParameter

raise a signal (proceedable or not, whatever the proceedability is).
The argument, aParameter is passed as parameter.

 raiseSignalWith: aParameter errorString: aString

raise a signal (proceedable or not, whatever the proceedability is).
The argument, aString is used as messageText,
aParameter is passed as exception parameter.

 raiseWith: aParameter

raise a signal nonproceedable.
The argument, aParameter is passed as parameter.

 raiseWith: aParameter errorString: aString

raise a signal nonproceedable.
The argument, aString is used as messageText,
aParameter is passed as exception parameter.

 raiseWith: aParameter errorString: aString in: aContext

raise a signal nonproceedable.
The argument, aString is used as messageText, 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.

 raiseWith: aParameter in: aContext

raise a signal nonproceedable.
The argument, aParameter is passed as parameter.
The additional context is passed as the context responsible for the raise,
allowing a raise to mimicri the exception happened somewhere else.

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

Usage example(s):

Object messageNotUnderstoodSignal catch:[ 123 size open ]

 deferAfter: aBlock

evaluate the argument, aBlock.
Ignore the receiver-signal during evaluation - i.e. simply continue,
but remember if the signal was raised.
After the block evaluation, finally raise the signal - if it was raised in the block.
If the signal is raised multiple times, only the first raises parameter is remembered,
and only a single raise is performed after the block's evaluation.

Deferring makes sense for some signals, such as UserInterrupt or AbortSignal,
which must occasionally be delayed temporarily until a save place is reached
(especially when packages are sent across a communication channel, and you don't want
partial packages to be generated by user interruptions).

Usage example(s):

|s| s := Signal new mayProceed:true. s deferAfter:[ s raiseRequestWith:'hello' errorString:'eeee' ]

 evaluate: aBlock ifRaised: exceptionValue

evaluate the argument, aBlock and return its value.
If the receiver-signal is raised during evaluation, abort
the evaluation and return the value from exceptionValue.
This is similar to the catch & throw mechanism found in other languages

Usage example(s):

Object messageNotUnderstoodSignal evaluate:[ 123 size open ] ifRaised:[ self halt ]

 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.

Usage example(s):

Object messageNotUnderstoodSignal handle:[:ex | 'oops' printNL. ex return ] do:[ 123 size open ]

Usage example(s):

|num| num := 0. Number divisionByZeroSignal handle:[:ex | 'oops' printNL. ex return ] do:[ 123 / num ]

 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.

 ignoreIn: aBlock

evaluate the argument, aBlock.
Ignore the receiver-signal during evaluation - i.e. simply continue with the default resume value.
This makes only sense for some signals, such as UserInterrupt
or AbortOperationRequest, because continuing after an exception without any cleanup
often leads to followup-errors.

Usage example(s):

Object messageNotUnderstoodSignal ignoreIn:[ 123 size open ]