Just stating what I understand and where I stand.

- A - Experimental coroutines are in HEAD and 8.6a2

     * they do allow new and simpler ways to express things
     * what's in there is experimental infrastructure
     * please play with code and concept, help us make it better

- B - Some design decisions I consider necessary, where the alternatives I saw
fall in one or more of the following categories:

     (a) semantics not clear (to me and/or generally)
     (b) no hope in hell to have it in 8.6 (compat)
     (c) no hope in hell to have it in 8.6 (time)

    Among these:
     * the coroutine bodies run in [uplevel #0]
     * coroutines are not serializable
     * coroutines are like one-shot continuations, not restartable

- C - Some design decisions where made with possibly insufficient info:

    (0a) [coroutine] creates a command and not a special object with subcommands
         Justification:
           (a) provides all that is needed
           (b) does not require new (sub)commands to resume, delete, ...
           (c) leverages Tcl's command management code (for instance, automatic cleanup
               on namespace deletion)
           (d) implementation simplicity
    (0b) [coroutine] runs the body up to the first [yield] instead of just creating the
         command
         Justification:
           (a) this is not really restrictive
           (b) it does not create commands that take different arguments at first and
               successive calls
           (c) implementation simplicity
    (1)  coroutines are self-cleaning
    (2)  [coroutine] requires a command name ([cmd] in the rest of this post]
    (3)  [cmd] takes a single argument: [yield]'s inside return value
    (4)  [yield] takes a single argument: the outside return value
    (5)  [yield] always return an "ok" code, both inside and outside

    Of these, only (5) restricts functionality; it was taken because *I* can
not see how to make the alternative (a) useful, (b) semantically clear, (c) play
nicely with (1). I may be wrong, eager to learn.

     (1) I think is valuable: when the coroutine is exhausted there's nothing
else that can be done with it, so let the command disappear instead of burdening
the caller to clean up.

     The other three are ... irrelevant at this stage! Simple script wrappers
can provide alternative syntax at minimal perf cost. They do not constrain
experimentation in any way. Should we want more than one available, standard
wrappers could be in tcllib or TIPped and "builtin". Should the perf penalty be
too large, they can at any time be coded in C (or even bytecompiled!) as solving
perf bugs.

- D - I am eager to get help making this better

     (a) Looking mostly for "mental bugs", things that are stopping me from
writing a TIP right away:
       * does it make sense? are there inconsistencies and semantic snafus?
       * are there B-type restrictions that could be lifted in time for 8.6?
       * is there more C-type stuff that I am missing, and that is losing
generality?

     (b) Looking for arguments that would tip C-decisions one way or the other;
this includes primarily real use cases. Mainly interested in (1) and (5), and
possibly other decisions that I may have made unconsciously (help me find them!).

% coroutine foo [interp create] eval yield
yield can only be called in a coroutine
% coroutine foo info coroutine
::foo
% coroutine foo [interp create] eval info coroutine
% # returns empty string

set i [interp create]
$i eval coroutine foo mycmd ...
interp alias {} foo $i foo

proc splitscript {input} {
    set slave [interp create -safe]
    $slave eval {unset {*}[info vars]}
    foreach command [$slave eval {info commands}] {
        $slave hide $command
    }
    $slave alias unknown apply {{args} {yield $args}}
    coroutine nextline apply {{slave input} {
        yield
        $slave eval $input
    }} $slave $input
    set result {}
    while {1} {
        set line [nextline]
        if {$line ne ""} {
            lappend result $line
        } else {
            interp delete $slave
            return $result
        }
    }
}

proc splitscript {input} {
    set slave [interp create -safe]
    $slave eval {unset {*}[info vars]}
    foreach command [$slave eval {info commands}] {
        $slave hide $command
    }
    $slave expose lappend lappend*
    $slave invokehidden proc unknown* {args} {
        lappend* ::script* $args
    }
    $slave invokehidden namespace unknown unknown*
    $slave invokehidden set script* {}
    $slave eval $input
    set script [$slave invokehidden set script*]
    interp delete $slave
    return $script
}

coroutine foo eval {yield "in the coro 1"; yield "in the coro 2"; return "finishing"}

coroutine foo apply {{} { yield "in the coro 1"; ... }}

proc filterByFactor {source n} {
    yield [info coroutine]
    while 1 {
        set x [$source]
        if {$x % $n} {
            yield $x
        }
    }
}
coroutine allNumbers apply {{} {while 1 {yield [incr x]}}}
coroutine eratosthenes apply {c {
    yield
    while 1 {
        set n [$c]
        yield $n
        set c [coroutine prime$n filterByFactor $c $n]
    }
}} allNumbers
for {set i 1} {$i <= 20} {incr i} {
    puts "prime#$i = [eratosthenes]"
}