"
 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
    (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 up-Queries 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.

    [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]
  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:'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 class methodsFor:'documentation'!

version
    ^ '$Header: /cvs/stx/stx/libbasic/QuerySignal.st,v 1.13 1996-05-18 15:29:41 cg Exp $'
! !