"
COPYRIGHT (c) 1995 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.
"
Signal subclass:#QuerySignal
instanceVariableNames:''
classVariableNames:''
poolDictionaries:''
category:'Kernel-Exceptions'
!
!QuerySignal class methodsFor:'documentation'!
copyright
"
COPYRIGHT (c) 1995 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
"
QuerySignals are like signals, except that they are not accepted
by handlers for ordinary signals.
I.e. a signal handler for a normal signal will not handle a query
signal. Thus, these bypass anySignal handlers.
If unhandled, no error is raised, instead they are simply ignored
and nil is returned from the raise
(as opposed to normal signals, which raise an unhandled signal exception).
QuerySignals are also ignored, if a handler exists, but rejects.
Their main use is to implement upQueries via signals, that work even
if intermediate errorSignal handlers are present
(which is not possible with ordinary signals, since errorSignal handlers
would catch those signals).
Code deep down in the calling hierarchy can post such an up-Query to ask
for some information in return or to pass some information upward.
For example, the activityNotification mechanism is built on top of this:
everyone can send such a notification which is either handled by someone
up in the hierarchy (to show it in the windows info area) or simply
ignored.
Using QuerySignals for this (instead of regular Signals) helps in documenting
the intended usage of those signals.
Another use of querySignals is to provide additional information to
deeply nested methods, which is only required in the uncommon case;
or if another parameter is required by some method, which was not planned
for in the beginning, and you do not want to hand this value (via an
additional argument) through all intermediate levels.
A highly elegant solution to this problem is to provide a handler somewhere
at the top of the calling hierarchy, and raise an upQuery from whereever
that value is required.
A concrete application can be found in the windowGroup- and lastEvent-
queries, provided by the windowGroup object. If anyone is interrested
in the event which was responible for the anyone to be called, all he needs
to do is to raise the lastEventQuerySignal, which returns that event.
No intermediate methods are required to know anything about that.
A final note (to C++ and Java fans):
such upQueries are only possible, if the exception handling mechanism
does not automatically unwind the stack for the handler invokation.
Since the handler must be able to proceed the execution and return
a value to the raiser ....
[see also:]
Signal SignalSet Exception
Object
(``Exception handling and signals'': programming/exceptions.html)
[author:]
Claus Gittinger
"
!
examples
"
an up-query from a deeply nested operation to a higher level:
[exBegin]
|querySignal zero|
zero := 0.
querySignal := QuerySignal new.
querySignal handle:[:ex |
Transcript showCR:'query'.
ex proceedWith:true
] do:[
'nesting'.
[
[
Object errorSignal handle:[:ex |
Transcript showCR:'some error: ' , ex errorString.
ex proceed
] do:[
[
1 // zero. 'an error which is cought in the handler'.
(querySignal raise) == true ifTrue:[
Transcript showCR:'query says: ok'.
] ifFalse:[
Transcript showCR:'query says: no'
]
] value
]
] value
] value
]
[exEnd]
for lazy typists, a more compact interface is also provided
(which is also easier to read):
[exBegin]
|querySignal|
querySignal := QuerySignal new.
querySignal answer:true do:[
'nesting'.
[
[
(querySignal raise) == true ifTrue:[
Transcript showCR:'query says: ok'.
] ifFalse:[
Transcript showCR:'query says: no'
]
] value
] value
]
[exEnd]
an up-query from a deeply nested operation, for which there
is no handler:
(notice, this would not work with normal signals, which would raise
another unhandled exception-exception;
also notice the == check #raise's return value being true,
instead of a simple ifTrue; this handles a nil-value from
the unhandled query)
[exBegin]
|querySignal zero|
zero := 0.
querySignal := QuerySignal new.
[
'nesting'.
[
[
Object errorSignal handle:[:ex |
Transcript showCR:'some error: ' , ex errorString.
ex proceed
] do:[
[
1 // zero. 'an error which is cought in the handler'.
(querySignal raise) == true ifTrue:[
Transcript showCR:'query says: ok'.
] ifFalse:[
Transcript showCR:'query says: no'
]
] value
]
] value
] value
] value
[exEnd]
counter-example, just to show that things would not work this way
with regular signals:
[exBegin]
|signal|
signal := Signal new.
'nesting deeply'.
[
[
[
[
[
(signal raise) == true ifTrue:[
Transcript showCR:'query says: ok'.
] ifFalse:[
Transcript showCR:'query says: no'
]
] value
] value
] value
] value
] value
[exEnd]
except, by handling the unhandled exception
(but we think, that querySignals are easier to use and
better document the intent):
[exBegin]
|signal|
signal := Signal new.
'nesting deeply'.
[
[
[
[
[
Signal noHandlerSignal handle:[:ex |
ex proceedWith:nil
] do:[
(signal raise) == true ifTrue:[
Transcript showCR:'query says: ok'.
] ifFalse:[
Transcript showCR:'query says: no'
]
]
] value
] value
] value
] value
] value
[exEnd]
"
! !
!QuerySignal methodsFor:'initialization'!
defaultAnswer:someValue
"define the queries defaultAnswer to be someValue.
This is the same as defining an appropriate handlerBlock."
|handler|
"/ avoid creating a fullBlock, in the most common cases
someValue == true ifTrue:[
handler := [:ex | ex proceedWith:true]
] ifFalse:[
someValue == false ifTrue:[
handler := [:ex | ex proceedWith:false]
] ifFalse:[
handler := [:ex | ex proceedWith:someValue].
]
].
self handlerBlock:handler.
"
QuerySignal new raise
(QuerySignal new defaultAnswer:true) raise
(QuerySignal new defaultAnswer:false) raise
"
"
|sig rslt|
sig := QuerySignal new.
sig defaultAnswer:false.
rslt := sig raise.
Transcript showCR:rslt.
"
"
|sig rslt|
sig := QuerySignal new.
sig defaultAnswer:false.
sig answer:true
do:[
rslt := sig raise
].
Transcript showCR:rslt.
"
"Modified: 3.1.1997 / 15:14:40 / cg"
! !
!QuerySignal 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|
aSignal isQuerySignal ifFalse:[^ false].
s := aSignal.
[s notNil] whileTrue:[
self == s ifTrue:[^ true].
s := s parent
].
^ false
!
isQuerySignal
"return true, if this is a querySignal - always return true here"
^ true
"Modified: 22.4.1996 / 13:45:10 / cg"
! !
!QuerySignal methodsFor:'save evaluation'!
answer:someAnswer do:aBlock
"evaluate the argument, aBlock.
If the receiver is queried during evaluation, answer with someAnswer.
This is a wrapper for #handle:do: for lazy typists; no new functionality."
^ self handle:[:ex | ex proceedWith:someAnswer] do:aBlock.
"
|q|
q := QuerySignal new.
q answer:true do:[
Transcript showCR:'query answers: ' , (q raise printString).
]
"
"
|q|
q := QuerySignal new.
q answer:false do:[
Transcript showCR:'first query answers: ' , (q raise printString).
q answer:true do:[
Transcript showCR:'second query answers: ' , (q raise printString).
]
]
"
"Created: 10.7.1996 / 15:08:20 / cg"
"Modified: 14.10.1996 / 16:59:18 / cg"
! !
!QuerySignal class methodsFor:'documentation'!
version
^ '$Header: /cvs/stx/stx/libbasic/QuerySignal.st,v 1.17 1997-01-03 14:14:53 cg Exp $'
! !