"{ Encoding: utf8 }"

"

 COPYRIGHT (c) 2019 by eXept Software AG

              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.

"

"{ Package: 'stx:libbasic2' }"

"{ NameSpace: Smalltalk }"

ProtoObject subclass:#DelayedValue

	instanceVariableNames:'result semaphore'

	classVariableNames:''

	poolDictionaries:''

	category:'Kernel-Processes'

!

!DelayedValue class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 2019 by eXept Software AG

              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

"

    I am similar to a Future, in that I represent an execution in progress, 

    whose value will be required some time in the future.

    In contrast to a future, which itself spawns a thread to perform the computation,

    my value comes from an external source (typically, an event or incoming message from an

    interprocess communication channel).

    In contrast to a Promise, instances of me can be used interchangable with the promised value

    (i.e. I will catch DNU, wait for the value and forward the message automatically)

    I will delay any messages sent to me, until the execution has completed (i.e. the value was provided).

    This is useful to return values from external sources (print jobs, compile jobs etc.),

    which can be done in the background and the user can do something else

    in the meantime. 

    If the computation is finished before the user needs its value, he is not forced to wait.

    If the computation is unfinished, he has to wait for the remaining time only.

    [author:]

        cg

    [see also:]

        Block Lazy LazyValue Future Promise

"

!

examples

"

  Waits for someon else to provide a value after some time-consuming computation

  (could be a remote process, sending me an event):

                                                                    [exBegin]

    | delayedValue |

    delayedValue := DelayedValue new.

    [

        Transcript showCR: 'evaluating factorial...'.

        Delay waitForSeconds:2.

        delayedValue value:(100 factorial).

        Transcript showCR: 'done...'.

    ] fork.    

    Transcript showCR:'The value is: %1' with:delayedValue

                                                                    [exEnd]

"

! !

!DelayedValue class methodsFor:'instance creation'!

new

    "return an initialized instance"

    ^ self basicNew initialize.

! !

!DelayedValue methodsFor:'initialization'!

initialize

    "Invoked when a new instance is created."

    self initializeSemaphore

    "Modified: / 25-06-2019 / 10:35:01 / Claus Gittinger"

!

initializeSemaphore

    "Invoked when a new instance is created."

    semaphore := Semaphore name:'DelayedValue'.

    "Created: / 25-06-2019 / 10:34:55 / Claus Gittinger"

! !

!DelayedValue methodsFor:'printing'!

displayOn:aGCOrStream

    "notice: displayString and displayOn: will not wait for the value (they are for developers and inspectors),

     whereas printString and printOn: will wait (they are for the program to print data)."

    "/ what a kludge - Dolphin and Squeak mean: printOn: a stream;

    "/ ST/X (and some old ST80's) mean: draw-yourself on a GC.

    (aGCOrStream isStream) ifFalse:[

        ^ self value displayOn:aGCOrStream

    ].

    semaphore isNil ifTrue:[

        result displayOn:aGCOrStream.

        aGCOrStream nextPutAll:' ('; nextPutAll:self class name; nextPutAll:' (evaluated)'.

        ^ self.

    ].    

    aGCOrStream nextPutAll:self class name; nextPutAll:' (unevaluated)'

    "Modified (comment): / 25-06-2019 / 10:46:07 / Claus Gittinger"

!

displayString

    "notice: displayString and displayOn: will not wait for the value (they are for developers and inspectors),

     whereas printString and printOn: will wait (they are for the program to print data)."

    "defined here, because I inherit from nobody"

    ^ (Object compiledMethodAt:#displayString)

        valueWithReceiver:self

        arguments:nil

        selector:#displayString

    "Modified (comment): / 25-06-2019 / 10:45:54 / Claus Gittinger"

! !

!DelayedValue methodsFor:'providing value'!

errorValueAlreadyProvided

    self error:'value can only be provided once'

    "Created: / 25-06-2019 / 10:30:25 / Claus Gittinger"

!

value:anyObject

    "value is now provided.

     If anyone is waiting on me, signal the semaphore"

    |sema|

    (sema := semaphore) notNil ifTrue:[

        result := anyObject.

        semaphore := nil.

        sema signal.

    ] ifFalse:[

        self errorValueAlreadyProvided

    ].

    "Created: / 25-06-2019 / 10:22:10 / Claus Gittinger"

! !

!DelayedValue methodsFor:'synchronising'!

doesNotUnderstand:aMessage

    "Any message to a Future will end up here."

    |sema|

    (sema := semaphore) notNil ifTrue:[

        Processor activeProcess isDebuggerProcess ifTrue:[

            "enable debugging / inspecting"

            ^ aMessage sendTo:self usingClass:Object.

        ].

        sema waitUncounted. "Wait for evaluation to complete"

                            "(if not already completed)"

    ].

    ^ aMessage sendTo:result

    "Modified: / 04-10-2011 / 17:37:18 / cg"

    "Modified: / 01-02-2018 / 10:17:48 / stefan"

    "Modified: / 25-06-2019 / 07:52:42 / Claus Gittinger"

!

perform:aSelector withArguments:argArray

    "send the message aSelector with all args taken from argArray

     to the receiver."

    |sema|

    (sema := semaphore) notNil ifTrue:[

        Processor activeProcess isDebuggerProcess ifTrue:[

            "enable debugging / inspecting"

            ^ super perform:aSelector withArguments:argArray.

        ].

        sema waitUncounted.

    ].

    ^ result perform:aSelector withArguments:argArray.

    "Modified (format): / 01-02-2018 / 10:17:44 / stefan"

    "Modified: / 25-06-2019 / 07:53:01 / Claus Gittinger"

!

value

    "retrieve the value, possibly waiting for the result to arrive"

    |sema|

    (sema := semaphore) notNil ifTrue:[

        "Wait for evaluation to complete (if not already completed)"

        sema waitUncounted. 

    ].

    ^ result

    "Created: / 04-10-2011 / 17:36:06 / cg"

    "Modified (comment): / 25-06-2019 / 17:17:47 / Claus Gittinger"

!

valueOnTimeout:secondsOrNilOrTimeDuration do:exceptionalValue

    "retrieve the value, possibly waiting for the result to arrive;

     if a timeout happens, return the value from exceptionalValue."

    |sema|

    (sema := semaphore) notNil ifTrue:[

        "Wait for evaluation to complete (if not already completed)"

        (sema waitUncountedWithTimeout:secondsOrNilOrTimeDuration) isNil ifTrue:[

            ^ exceptionalValue value

        ].    

    ].

    ^ result

    "Created: / 25-06-2019 / 17:19:30 / Claus Gittinger"

!

valueWithTimeout:secondsOrNilOrTimeDuration

    "retrieve the value, possibly waiting for the result to arrive;

     if a timeout happens, return nil."

    |sema|

    (sema := semaphore) notNil ifTrue:[

        "Wait for evaluation to complete (if not already completed)"

        sema waitUncountedWithTimeout:secondsOrNilOrTimeDuration.

    ].

    ^ result

    "Created: / 25-06-2019 / 17:17:34 / Claus Gittinger"

! !

!DelayedValue methodsFor:'testing'!

hasValue

    "true if I have already a value 

     (i.e. would not block when sending me a message)"

    ^ semaphore isNil or:[semaphore wouldBlock not].

    "Modified: / 04-10-2011 / 17:29:36 / cg"

    "Modified (comment): / 25-06-2019 / 10:23:54 / Claus Gittinger"

!

isLazyValue

    "true if I have no value yet 

     (i.e. would block when sending me a message)"

    ^ semaphore notNil and:[semaphore wouldBlock]

    "Modified (comment): / 25-06-2019 / 10:23:48 / Claus Gittinger"

! !

!DelayedValue class methodsFor:'documentation'!

version_CVS

    ^ '$Header$'

! !