Class: GenericException

• Inheritance
• Description
• Related information
• Class protocol
  • Compatibility-Dolphin
  • Compatibility-Squeak
  • accessing
  • backward compatibility
  • child signal creation
  • converting
  • initialization
  • instance creation
  • misc ui support
  • printing
  • queries
  • raising
  • save evaluation
  • testing
• Instance protocol
  • Compatibility-ANSI
  • Compatibility-Dolphin
  • Compatibility-Squeak
  • accessing
  • copying
  • default actions
  • default values
  • handler actions
  • printing & storing
  • private
  • raising
  • setup
  • testing
• Examples

Inheritance:

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

Package:

stx:libbasic

Category:

Kernel-Exceptions

Version:

rev: 1.124 date: 2009/12/01 20:03:39

user: cg

file: GenericException.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

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

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

Related information:

    Signal
    SignalSet
    QuerySignal
    Context
    Block
    Object
    DebugView
    [``Exception handling and signals'']

Class protocol:

 signal: messageText

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

 signal

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

 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 exeptions do not have a handler
block. They redefine the #action method instead

 notifierString: aString

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

 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.

 , anExceptionHandler

return a SignalSet with myself and anExceptionHandler

 initialize

 new

 newException

 iconInBrowserSymbol

 description

return the notifier string.
If the notifier string starts with space, prepend
the parents notifier string.
Subclasses may redefine this method.

 accepts: aSignal

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

 exception: anException isHandledIn: aContext

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: anException in: aContext

return a handlerContext for anException in the
contextChain starting with aContext.
Returns nil ,if there is no handler.

 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)

 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.

 parent

return the parent Signal/Exception of myself.
Subclasses may redefine this to install themself as child of
existing Signals.

 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 exception parameter.
The additional context is passed as the context responsible for the raise,
allowing a raise to mimicri the exception happened somewhere else.

 signalWith: messageText

ANSI compatibility

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

 deferAfter: aBlock

evaluate the argument, aBlock.
Ignore the receiver-exception 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 blocks 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 dont want
partial packages to be generated by user interruptions).

 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

 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.

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

 isControlInterrupt

 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

 isQuerySignal

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

 mayProceed

return true, if the exception handler is allowed to proceed
the execution where the exception occured.

Subclasses may redefine this.

Instance protocol:

 pass

 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.

 signalWith: messageText

 stackTrace: numberOfFrames

return a backtrace information string

 signalerContext

 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

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

 creator

return the creator of the exception

 errorString

return the errorString passsed with the signal raise
(or nil, if there was none).
#errorString is deprecated, use description instead

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

 errorString: aString

set the messageText.
If it starts with a space, the signals messageText is prepended,
if it ends with a space, it is appended.
#errorString: is deprecated, use messageText: instead

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

 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.

 handlerContext

return the context of the handler

 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 signals messageText is prepended,
if it ends with a space, it is appended.

 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

 proceedable: aBoolean

 raiseContext

 rejected

return true, if any other of the exceptions 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

 searchFrom: raisingContext

 signal

return the signal, that caused the exception

 signal: aSignal

set the signal, that caused the exception

 suspendedContext

return the context in which the raise occured

 suspendedContext: something

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

 willProceed

return true, if the exception is proceedable

 postCopy

set the internal state to nil

 postDeepCopy

set the internal state to nil

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

Subclasses may redefine this.

 noHandler

raise the NoHandlerError.
NohandlerError redefines this method to avoid recursive invocations

 defaultResumeValue

 defaultReturnValue

 exit

either resume or return - depending on the receivers resumability.
VW compatibility.

 exit: value

either resume or return - depending on the receivers 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

 resignalAs: anotherException

resignal anotherException, as if it was raised in the first place

 restart

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

 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

 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

 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

 returnWith: value

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

 description

return the description string of the signal

 descriptionForDebugger

return the description string of the signal which is used in the
debugger title area

 printOn: aStream

 doCallAction

call the action proper
- needed an extra method to have a raise-marked context around
( see implementation of #reject and #proceed).

 doCallHandler: aHandlerBlock

call the handler proper
- an extra method is needed to have a raise-marked context around.
(see implementation of #reject and #proceed).

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

 raise

actually raise a non-proceedable exception

 raiseRequest

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.

 raiseSignal

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.

 setSignal: aSignal

set the fields usable for inspection by the handler
- only to be sent from the signal when raising.
CG: added this one to avoid confusion with dolphin signal: (which raises the ex)

 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

 isError

 isException

 isNotification

Examples: