Smalltalk/X Webserver

Documentation of class 'GenericException':

Class: GenericException

Inheritance
Description
Class protocol
Instance protocol
Examples

Inheritance:

   Object
   |
   +--GenericException
      |
      +--ControlInterrupt
      |
      +--Exception
      |
      +--NoHandlerError
      |
      +--Notification

Package:: stx:libbasic

Category:: Kernel-Exceptions

Version:: rev: 1.242 date: 2024/03/26 12:51:14; user: cg; file: GenericException.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).

GenericException and its subclasses implement the same protocol as Signal.
So class based exceptions may be implemented as subclasses of GenericException.

Normally all exceptions are subclasses of Exception. Exceptions, that are
used for debugging or that are signalling errors in the exception system itself
are direct 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 handler's 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 messageText 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)

    messageText      <String>     an messageText
                                  (usually the signals own messageText, but sometimes
                                   changed explicitely in #raiseWith:errorString:)

    suspendedContext <Context>    the context in which the raise occurred

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

    raiseXXXWith:           - pass additional parameter;
                              default messageText

    raiseXXXErrorString:    - do not pass any additional parameter;
                              given errorString

    raiseXXXWith:errorString:
                            - pass any additional parameter;
                              AND given errorString

copyrightCOPYRIGHT (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:

Compatibility-ANSI

signal: raise a signal proceedable or nonproceedable (whichever is right).
ANSI compatibility.
signalWith: messageText: raise a signal proceedable or nonproceedable (whichever is right).
The argument is used as messageText.
ANSI compatibility.

Compatibility-Dolphin

signal: messageText: raise a signal proceedable or nonproceedable (whichever is right).
The argument is used as messageText.

Javascript support

js_add: anExceptionHandler
( an extension from the stx:libjavascript package ): For JavaScript only:
Alternative error concatenation.
Generated for +-operator in javascript.

accessing

defaultNotifierString
errorString: #errorString is deprecated, use description instead

** This is an obsolete interface - do not use it (it may vanish in future versions) **
handlerBlock: Compatibility with Signal. Class based exceptions do not have a handler
block. They redefine the #action method instead
notifierString: return my notifier string.
This used to be defined via a classVar,
but is now actually provided by a default getter
notifierString: aString

backward compatibility

abortingEmergencyHandler: WARNING: this method belongs to NoHandlerError, and has been moved there

** This is an obsolete interface - do not use it (it may vanish in future versions) **
dumpingEmergencyHandler: WARNING: this method belongs to NoHandlerError, and has been moved there

** This is an obsolete interface - do not use it (it may vanish in future versions) **
emergencyHandler: WARNING: this method belongs to NoHandlerError, and has been moved there

** This is an obsolete interface - do not use it (it may vanish in future versions) **
emergencyHandler: aOneArgBlock: WARNING: this method belongs to NoHandlerError, and has been moved there

** This is an obsolete interface - do not use it (it may vanish in future versions) **
mailingEmergencyHandler: WARNING: this method belongs to NoHandlerError, and has been moved there

** This is an obsolete interface - do not use it (it may vanish in future versions) **
notifyingEmergencyHandler: WARNING: this method belongs to NoHandlerError, and has been moved there

** This is an obsolete interface - do not use it (it may vanish in future versions) **
notifyingEmergencyHandlerForUserProcesses: WARNING: this method belongs to NoHandlerError, and has been moved there

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

child signal creation

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

converting

, anExceptionHandler

return a Handler (SignalSet) that accepts myself and anExceptionHandler

Usage example(s):

        ArithmeticError, ContextError
        Error, OsError
        OsError, Error

initialization

initialize: force strict signal checking in Smalltalk development - nobody cares otherwise

instance creation

js_new: errorString
( an extension from the stx:libjavascript package )

sent from js in:
throw new Error(msg)

Usage example(s):

     (Error js_new:'hello') raise

new

(comment from inherited method)
return an instance of myself without indexed variables

newException

misc ui support

iconInBrowserSymbol
( an extension from the stx:libtool package ): the browser will use this as index into the toolbariconlibrary

printing

description

return the notifier string.
If the notifier string starts with space,
then prepend the parent's notifier string.
Subclasses may redefine this method.

Usage example(s):

     Object errorSignal description

nameForDescription

if no notifierString is specified, this is used.
Can be redfined to hide the namespace in subclasses

printBadExceptionHandler: badExceptionHandler in: aContext

if anyone does:
[ xxx ] on: foo do:[ ... ]
with a bad foo (i.e. nil or not an Exception, ExceptionSet, Signal or HandlerSet
this method is called to print a warning.
Usually, this happens when foo is misspelled or when porting code
from Squeak, and there is no such exception-class in ST/X.
A typical situation is:
[ xxx ] on: NetworkError do:[ ... ]

queries

accepts: aSignalOrExceptionClass: return true, if the receiver accepts the argument, aSignalOrExceptionClass.
(i.e. the receiver is aSignal or a parent of it). False otherwise.
defaultAnswer
exception: anExceptionClass isHandledIn: aContext: utility:
return true, if there is a handler for anException in the
contextChain starting with aContext.
exceptionHandlerFor: anException in: aContext: answer the exceptionHandler-block for anException from aContext.
handlerContextForException: anExceptionClass in: aContext: utility:
return a handlerContext for anException in the
contextChain starting with aContext.
Returns nil, if there is no handler.
handlerForSignal: exceptionCreator 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)
isAcceptedBy: aHandlerSignalOrExceptionClass: return true, if aHandlerSignal accepts the receiver.
isHandled: return true, if there is a handler for the receiver signal/exception class.
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.
parent: return the parent Signal/Exception of myself.
Subclasses may redefine this to install themself as child of
existing Signals.

raising

raise: raise a signal nonproceedable.
The signals notifierString is used as messageText.
raiseAsQuery: utility to avoid code duplication.
raise the exception as a query. This means, that if it is unhandled,
a default value is returned (i.e. an implicit resume).
Return the handler's value (if there is one), or the default value, if not.
Invoking the handler is exactly the functionality of Signal>>raiseRequest,
but we can do it faster here (avoiding the construction of an exception instance).

This should normally go into the Notification class, but some of my
subclasess that do not inherit from Notification simulate themself as Queries
(e.g. GraphicsDevice::GraphicResourceAllocationFailure class >> #query)
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.
raiseIn: aContext: raise a signal nonproceedable.
The signals notifierString is used as messageText.
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.
raiseRequestIn: aContext: raise a signal proceedable.
The signals notifierString is used as messageText.
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 exception parameter.
The additional context is passed as the context responsible for the raise,
allowing a raise to mimicri the exception happened somewhere else.

save evaluation

catch: aBlock

evaluate the argument, aBlock.
If the receiver-exception 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
     ]) ifTrue:[
        Transcript showCR:'an error was caught'
     ].

deferAfter: aBlock

evaluate the argument, aBlock.
Ignore the receiver-exception during evaluation - i.e. simply continue,
but remember if an exception was raised.
After the block evaluation, finally raise the exception - if it was raised in the block.
If the exception is raised multiple times, only the first raise's 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):

     UserInterrupt
         handle:[:ex |
             Transcript showCR:'X - here is a returning handler.'.
         ]
         do:[
             UserInterrupt deferAfter:[
                 Transcript showCR:'1 - now raising, but will be deferred.'.
                 UserInterrupt raiseRequestWith:'hello'.
                 Transcript showCR:'2 - after the raise, deferred exception will be handled soon.'.
             ].
             Transcript showCR:'3 - here after the protected block.'.
         ]

Usage example(s):

     UserInterrupt
         handle:[:ex |
             Transcript showCR:'X - here is a proceeding handler.'.
             ex proceed
         ]
         do:[
             UserInterrupt deferAfter:[
                 Transcript showCR:'1 - now raising, but will be deferred.'.
                 UserInterrupt raiseRequestWith:'hello'.
                 Transcript showCR:'2 - after the raise, deferred exception will be handled soon.'.
             ].
             Transcript showCR:'3 - here after the protected block.'.
         ]

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

     MessageNotUnderstood
        evaluate:[ 123 size open ]
        ifRaised:345

     MessageNotUnderstood
        evaluate:[ 123 size ]
        ifRaised:345

handle: handleBlock do: aBlock

evaluate the argument, aBlock.
If the receiver-exception 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-exception 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-exception 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
     ]

     DomainError ignoreIn:[ -1.0 log10 ]

testing

isAbstract: (comment from inherited method)
Return if this class is an abstract class.
True is returned for Object here; false for subclasses.
Abstract subclasses must redefine this again.
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
isProgramError: redefined in all exceptions which are programmer's errors,
and which should probably not be ignored.
I.e. a global error handler should reject and let a debugger get control.
isQuery: return true, if this is a query - always return false here
isQuerySignal: return true, if this is a querySignal - always return false here
isUserInterrupt: true if this is a user-interrupt (CTRL-c)
mayProceed: return true, if the exception handler is allowed to proceed
the execution where the exception occurred.

Subclasses may redefine this.

Instance protocol:

Compatibility-ANSI

pass

same as reject - for ANSI compatibility

retry

same as #restart - ANSI & VW compatibility

retryUsing: alternativeBlock

Abort an exception handler and evaluate a new block in place of the handler's protected block.

signal: aString

signalWith: messageTextArg

raise a signal proceedable or nonproceedable (whichever is right).
The argument is used as messageText.
ANSI compatibility.

tag

[
Error raise
] on:Error do:[:ex |
ex tag transcribeCR.
self assert:(ex tag isNil)
]

Usage example(s):

     [
        Error raiseErrorString:'foo'
     ] on:Error do:[:ex |
        ex tag transcribeCR.
        self assert:(ex tag = 'foo')
     ]

Usage example(s):

     [
        Error raiseWith:#foo errorString:'foobar'
     ] on:Error do:[:ex |
        ex tag transcribeCR.
        self assert:(ex tag == #'foo')
     ]

Compatibility-Dolphin

stackTrace: numberOfFrames

return a backtrace information string

Usage example(s):

     Error handle:[:ex |
        (ex stackTrace:20) inspect.
     ] do:[
        self error
     ].

Compatibility-Squeak

signaler: Return the object that is the subject involving me.
This is set automatically to my #receiver during #signal
but could be overwritten when I am signaled
signalerContext: return the context in which the raise occurred.
Same as suspendedContext, for squeak compatibility

Compatibility-V'Age

exitWith: value: return with a value.
V'AGE compatibility.

Compatibility-VW

message: same as description - VW compatibility
searchFrom: raisingContext

accessing

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).
Dummy here

catchInDebugger: aBoolean

creator

return the creator of the exception.
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

return the errorString passsed with the signal raise
(or nil, if there was none).
#errorString is the same as description,
which returns the messageText plain or appended or prepended to the
classes description string.

errorString: aString

set the messageText.
If it starts with a space, the signal's messageText is prepended,
if it ends with a space, it is appended.

#errorString: does the same as messageText:,
but should be used for errors and exceptions,
whereas messageText: should be used for notifications and queries
(for documentation only)

handler

return the exception handler (Signal or SignalSet or ExceptionHandlerSet or Exception)
that handles the exception.
This is only valid during handler evaluation, and answers
the object which accepted the actual exception.

Usage example(s):

      [
          2 // 0
      ] on:Error do:[:ex| ex handler inspect]

      [
          2 // 0
      ] on:ArithmeticError, Error do:[:ex| ex handler inspect]

      [
          2 // 0
      ] on:MessageNotUnderstood do:[:ex| ex handler inspect]
        on:Error do:[:ex| ex handler inspect]

handlerContext

return the context of the handler.
The handlerContext's home or methodHome is the usually the context where the interesting code is found

handlingException

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

isResumable

return true, if the exception is resumable

isResumable: aBoolean

messageText

return the explicit given messageText - nil, if signaler did not provide one.

messageText: aString

set the messageText.
If it starts with a space, the signal's original messageText is prepended,
if it ends with a space, it is appended.

messageText: does the same as errorString:,
but should be used for notifications and queries,
whereas errorString: should be used for errors and exceptions
(for documentation only)

originalSignal

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

originator

return the originator passsed with the signal raise
(or nil, if there was none)

originator: anObject

set the originator

parameter

return the parameter passsed with the signal raise
(or nil, if there was none)

parameter: anObject

set the parameter of the exception

parameter: anObject errorString: errorString

set the parameter and errorString of the exception

proceedable: aBoolean

explicitly change the proceedability.
Normally this gets initialized from the classes idea of whether this makes sense

raiseContext

return the context of the raise.
That is usually one above the suspended context
(however if one raise calls another raise-helper, there might be intermediate contexts in between)

rejected

return true, if any other of the exception's handlers has rejected
Uncertain, if this is really interesting to anybody.
This is only valid during handler execution.
(i.e. an outer handler can find out, if any other handler has already rejected).
Currently only used to change the 'unhandled-exception' messageText
into 'rejected-exception' for the information, that there was a handler which rejected.

returnableSuspendedContext

return a nearest returnable context above suspendedContext in the sender chain.
We know, that raiseContext is always returnable, so if suspendedContext
is non-returnable, start there

setHandlerContext: aContextOrNil

Modified (comment): / 11-05-2020 / 10:49:01 / cg

setRaiseContext: aContextOrNil

Modified (comment): / 11-05-2020 / 10:48:46 / cg

setSuspendedContext: aContextOrNil

Modified (comment): / 11-05-2020 / 10:48:49 / cg

suspendedContext

return the context in which the raise occurred.
That is usually one below the raise context
(however if one raise calls another raise-helper, there might be intermediate contexts in between)

suspendedContext: something

set the value of the instance variable 'suspendedContext' (automatically generated)

willProceed

return true, if the exception is proceedable

copying-private

copyWithWalkbackUpTo: aContextOrNil: generate a (dead) copy of myself with a dead copy of my calling chain.
This is no longer alive, so it cannot be resumed or restarted.
Only useful to copy a walkback inside a handler for later
presentation
(eg. when copying for reraise in another thread, eg. in a promise)
postCopy: set the internal state to nil
postDeepCopy: set the internal state to nil

default actions

defaultAction: perform a action for the exception if it hasn't been catched
We arrive here, if either no handler was found, or none of the
handlers did a return (i.e. every handler rejected).

The default is to evaluate the signal's handlerBlock or
to raise the noHandlerSignal.
Subclasses may redefine this.
mayProceed: return true, if the exception handler is allowed to proceed
the execution where the exception occurred.

Subclasses may redefine this.
noHandler: raise the NoHandlerError.
NohandlerError redefines this method to avoid recursive invocations

default values

defaultMessageText: by default, the description found on the class side
defaultResumeValue: the default answer, if no one handles the query and the exception is resumed
defaultReturnValue

handler actions

exit

either resume or return - depending on the receiver's resumability.
VW compatibility.

exit: value

either resume or return - depending on the receiver's resumability.
VW compatibility.

proceed

Continue after the raise - the raise returns nil

proceedWith: value

Continue after the raise - the raise returns value

reject

handler decided not to handle this signal -
system will look for another handler

Usage example(s):

returning from the doCallXX: signals a reject

Usage example(s):

     Error handle:[:ex |
        '1' printCR.
        ex reject
     ] do:[
        Error handle:[:ex |
            '2' printCR.
            ex reject
        ] do:[
            #() at:1
        ]
     ]

resignalAs: anotherException

resignal anotherException, as if it was raised in the first place.
Only to be sent inside an exception handler block!

Usage example(s):

     |rslt|

     MessageNotUnderstood handle:[:ex |
        ex resignalAs:Number domainErrorSignal
     ] do:[
        rslt := 1 perform:#foo
     ].
     rslt

restart

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

Usage example(s):

con restart

Usage example(s):

     |rslt n|

     Error handle:[:ex |
        Transcript showCR:'fixing divisor ...'.
        n := 1.
        ex restart.
     ] do:[
        rslt := 5 / n.
     ].
     rslt

restartDo: aBlock

restart the handle:do: but execute the argument, aBlock instead of the
original do-block - usually after some repair work is done in handler

Usage example(s):

     |sig rslt|

     sig := Signal new.

     sig handle:[:ex |
        Transcript showCR:'exchanging do-block ...'.
        ex restartDo:[ rslt := 999 ]
     ] do:[
        rslt := 0.
        sig raise
     ].
     Transcript showCR:rslt

Usage example(s):

     |sig rslt|

     Object errorSignal handle:[:ex |
        ex restartDo:[ rslt := 999 ]
     ] do:[
        rslt := nil foo.

     ].
     Transcript showCR:rslt

Usage example(s):

     |sig rslt|

     Object errorSignal handle:[:ex |
        ex restartDo:[ 'handler' printCR. rslt := nil foo ]
     ] do:[
        rslt := nil foo.

     ].
     Transcript showCR:rslt

resume

Continue after the raise - the raise returns defaultResumeValue - ANSI

resume: value

Continue after the raise - the raise returns value - ANSI

resumeWith: value

Continue after the raise - the raise returns value - ANSI

return

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

Usage example(s):

when a normal return is done. As unwind actions are called,

return: value

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

returnDoing: aBlock

Continue after the handle:do: - the handle:do: returns aBlock value
Be careful when debugging. You cannot see the context with #returnDoing:
in the debugger if aBlock raises a signal

Usage example(s):

        [
            5 // 0
        ] on:Error do:[:ex|
            ex returnDoing:[self halt. 47*11].
        ]

returnWith: value

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

printing & storing

description

return the description string of the signal/exception.
If a messageText has been set, that is returned,
appended or prepended to the classes description string.
MessageText can be a computed value or anything which converts to a string

Usage example(s):

      (Error new messageText:'bla') description   
      (Error new messageText:' bla') description  
      (Error new messageText:'bla ') description 
      (Error new messageText:[Time now]) description

descriptionForDebugger

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

displayOn: aStream

show a printed representation of myself for debugging

printOn: aStream

(comment from inherited method)
append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

The default here is to output the receiver's class name.
BUT: this method is heavily redefined for objects which
can print prettier.

private

checkProceedable: helper for all raiseRequest methods
doCallAction: call the action proper
- needed an extra method to have a raise-marked context around
i.e. do not inline this into #doRaise !
(see implementation of #reject and #proceed).
doCallHandler: aHandlerBlock: call the handler proper - if the handler falls through, return the handler's value
- an extra method is needed to have a raise-marked context around.
i.e. do not inline this into #doRaise !
(see implementation of #reject and #proceed).
- also redefinable (see CascadingNotification)
doRaise: search through the context-calling chain for a handle-context
to the raising signal, a parent of it, or a SignalSet which includes
the raising signal.
If found, ask the receiver for the handler and evaluate
it with the receiver exception as argument.
If no handler is found, perform the default #action method.

ATTENTION: the code below depends on being called by #raise or
#raiseRequest for proper operation (it skips the sending context).

queries

isAcceptedBy: aHandlerSignalOrExceptionClass

return true, if aHandlerSignal accepts the receiver.

Usage example(s):

     MessageNotUnderstood new isAcceptedBy:Exception 
     MessageNotUnderstood isAcceptedBy:Exception 

     Exception accepts:MessageNotUnderstood

isHandledBy: anExceptionCreator

answer true, if the exception is handles by anExceptionCreator.
This is the inverse if GenericException>>#handles:
This method is immune to anExceptionCreator being nil.

raising

raise: actually raise a non-proceedable exception
raiseErrorString: aString: raise the signal nonproceedable.
The argument, aString is used as messageText
raiseErrorString: aString in: aContext: raise the signal nonproceedable.
The argument, aString is used as messageText
raiseIn: aContext: actually raise a non-proceedable exception
raiseRequest: actually raise a proceedable exception.
raiseRequestErrorString: errorString: actually raise a proceedable exception.
raiseRequestErrorString: errorString in: aContext: actually raise a proceedable exception.
raiseRequestIn: aContext: actually raise a proceedable exception.
raiseRequestWith: aParameter: actually raise a proceedable exception.
raiseRequestWith: aParameter errorString: aString: raise the signal proceedable.
The argument, aString is used as messageText,
aParameter is passed as exception parameter.
raiseRequestWith: aParameter errorString: aString in: aContext: actually raise a proceedable exception.
raiseRequestWith: aParameter in: aContext: actually raise a proceedable exception.
raiseSignal: actually raise an exception (whatever the proceedability is).
raiseSignalIn: aContext: actually raise an exception (whatever the proceedability is).
raiseWith: aParameter errorString: aString: raise the signal nonproceedable.
The argument, aString is used as messageText,
aParameter is passed as exception parameter.
raiseWith: aParameter errorString: aString in: aContext: raise the signal nonproceedable.
The argument, aString is used as messageText
raiseWith: aParameter in: aContext: raise the signal nonproceedable.
The argument, aString is used as messageText
reRaise: reraise a previously caught exception (on the current context)

setup

creator: aSignal: set the fields usable for inspection by the handler
- only to be sent from the signal when raising.
suspendedContext: sContext errorString: aString: set required fields
- only to be sent from the signal when raising
suspendedContext: aContext messageText: aString parameter: aParameter originator: anOriginator
suspendedContext: sContext parameter: aParameter: set required fields
- only to be sent from the signal when raising
suspendedContext: sContext parameter: aParameter errorString: aString: set required fields
- only to be sent from the signal when raising
suspendedContext: aContext parameter: aParameter originator: anOriginator

testing

isAbortOperationRequest
isBridgeException: do not make this an extension method of the Bridge-package
isControlInterrupt: true if this is a breakpoint or user-interrupt (CTRL-c)
isError
isException: (comment from inherited method)
answer true, if this is an Exception
isHaltInterrupt
isMessageNotUnderstood
isNotification
isProgramError: redefined in all exceptions which are programmer's errors,
and which should probably not be ignored.
I.e. a global error handler should reject and let a debugger get control.
isQuery
isTimeoutException
isUserInterrupt

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.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Thu, 21 Nov 2024 12:04:27 GMT