## defered through the event-loop.
#
## Programing with futures is explicit continuation-passing-style.

# ### ### ### ######### ######### #########
## Requisites

package require Debug
package require Debug::snit
package require snit

# ### ### ### ######### ######### #########
## Narrative tracing

Debug off    future
#Debug on     future
Debug prefix future {[list [Debug::snit::call]] }

# ### ### ### ######### ######### #########
## Implementation

snit::type future {
    # ### ### ### ######### ######### #########
    ## Class API
    ## Simplified construction with integrated setup

    # Provide new future configured with arguments. See `on ..`,
    # `nop`, `empty`, and `chain`.
    typemethod new {args} {
	Debug.future {}
	set future [$type create %AUTO%]
	if {[llength $args]} { $future {*}$args }
	return $future
    }

    # Provide a new future in default configuration and trigger it to
    # return the args and the next idle point. Further configuration
    # can be done on the result object.
    typemethod return {args} {
	Debug.future {}
	set f [$type new]
	after idle [list $f return {*}$args]
	return $f
    }

    # ### ### ### ######### ######### #########
    ## API. Various configuration methods. Chainable.

    # Configure callback to invoke on `return`.
    method {on return} {cmdprefix args} {
	Debug.future {}
	set myOkCmdPrefix $cmdprefix
	if {[llength $args]} { $self {*}$args }
	return $self
    }

    # Configure callback to invoke on `error`.
    method {on error} {cmdprefix args} {
	Debug.future {}
	set myErrorCmdPrefix $cmdprefix
	if {[llength $args]} { $self {*}$args }
	return $self
    }

    # Clear all callbacks. The future will now swallow all its invokations.
    method nop {} {
	Debug.future {}
	set myOkCmdPrefix    {}
	set myErrorCmdPrefix {}
	return
    }

    # Same as nop.
    method empty {} {
	Debug.future {}
	set myOkCmdPrefix    {}
	set myErrorCmdPrefix {}
	return
    }

    # Configure callbacks to post invokations to the other future.
    method chain {future args} {
	Debug.future {}
	# Inlined on return on error configuration chaining to another
	# future.

	set myOkCmdPrefix    [list $future return]
	set myErrorCmdPrefix [list $future error]
	if {[llength $args]} { $self {*}$args }
	return $self
    }

    # ### ### ### ######### ######### #########
    ## API. Invoke the future. This will destroy the instance as well.

    method error {message} {
	Debug.future {}
	$self Error $message
	return
    }

    method return {args} {
	Debug.future {}
	# Syntax:             | 0
	#       : -code x     | 2
	#       : -code x val | 3
	#       :         val | 4
	# Allowing multiple -code settings, last one is taken.

	set rcode  0

    # ### ### ### ######### ######### #########
    ## Destruction. A user is not allowed to destroy instances. Can
    ## only be done by invoking it (return or error), as part of which
    ## it destroys itself.

    destructor  {
	Debug.future {}
	if {$myIsDone} return
	return -code error "Illegal attempt to destroy unresolved future \"$self\""
    }

    # ### ### ### ######### ######### #########
    ## State

    variable myIsDone         0
    variable myOkCmdPrefix    {return -code return}
    variable myErrorCmdPrefix {return -code error}

    # ### ### ### ######### ######### #########
    ## Helper commands. Invoke the configured callbacks, if any. This
    ## is also where the instance destroys itself. Note that callback
    ## execution is defered to the event loop.

    method Ok {result} {
	Debug.future {[list ==> $myOkCmdPrefix]}

	set cmdprefix $myOkCmdPrefix
	DestroySelf

	if {![llength $cmdprefix]} return
	after 0 [list {*}$cmdprefix $result]
	return
    }

    method Error {message} {
	Debug.future {[list ==> $myErrorCmdPrefix]}

	set cmdprefix $myErrorCmdPrefix
	DestroySelf

	if {![llength $cmdprefix]} return
	after 0 [list {*}$cmdprefix $message]
	return
    }

    proc DestroySelf {} {

	upvar 1 self self myIsDone myIsDone
	set myIsDone 1
	$self destroy
	return
    }

    ##