Implementation of TIP #396

1 files changed, 53 insertions, 3 deletions

diff --git a/doc/coroutine.n b/doc/coroutine.n
index f4b5d5b..035d58a 100644
--- a/doc/coroutine.n
+++ b/doc/coroutine.n
@@ -9,12 +9,15 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-coroutine, yield \- Create and produce values from coroutines
+coroutine, yield, yieldto \- Create and produce values from coroutines
 .SH SYNOPSIS
 .nf
 \fBcoroutine \fIname command\fR ?\fIarg...\fR?
 \fByield\fR ?\fIvalue\fR?
-\fIname\fR ?\fIvalue\fR?
+.VS TIP396
+\fByieldto\fR \fIcommand\fR ?\fIarg...\fR?
+\fIname\fR ?\fIvalue...\fR?
+.VE TIP396
 .fi
 .BE
 .SH DESCRIPTION
@@ -30,11 +33,37 @@ Within the context, values may be generated as results by using the
 When that is called, the context will suspend execution and the
 \fBcoroutine\fR command will return the argument to \fByield\fR. The execution
 of the context can then be resumed by calling the context command, optionally
-passing in the value to use as the result of the \fByield\fR call that caused
+passing in the \fIsingle\fR value to use as the result of the \fByield\fR call
+that caused
 the context to be suspended. If the coroutine context never yields and instead
 returns conventionally, the result of the \fBcoroutine\fR command will be the
 result of the evaluation of the context.
 .PP
+.VS TIP396
+The coroutine may also suspend its execution by use of the \fByieldto\fR
+command, which instead of returning, cedes execution to some command called
+\fIcommand\fR (resolved in the context of the coroutine) and to which \fIany
+number\fR of arguments may be passed. Since every coroutine has a context
+command, \fByieldto\fR can be used to transfer control directly from one
+coroutine to another (this is only advisable if the two coroutines are
+expecting this to happen) but \fIany\fR command may be the target. If a
+coroutine is suspended by this mechanism, the coroutine processing can be
+resumed by calling the context command optionally passing in an arbitrary
+number of arguments. The return value of the \fByieldto\fR call will be the
+list of arguments passed to the context command; it is up to the caller to
+decide what to do with those values.
+.PP
+The recommended way of writing a version of \fByield\fR that allows resumption
+with multiple arguments is by using \fByieldto\fR and the \fBreturn\fR
+command, like this:
+.PP
+.CS
+proc yieldm {value} {
+    \fByieldto\fR return -level 0 $value
+}
+.CE
+.VE TIP396
+.PP
 The coroutine can also be deleted by destroying the command \fIname\fR, and
 the name of the current coroutine can be retrieved by using
 \fBinfo coroutine\fR.
@@ -108,6 +137,27 @@ for {set i 1} {$i <= 20} {incr i} {
     puts "prime#$i = [\fIeratosthenes\fR]"
 }
 .CE
+.PP
+.VS TIP396
+This example shows how a value can be passed around a group of three
+coroutines that yield to each other:
+.PP
+.CS
+proc juggler {name target {value ""}} {
+    if {$value eq ""} {
+        set value [\fByield\fR [info coroutine]]
+    }
+    while {$value ne ""} {
+        puts "$name : $value"
+        set value [string range $value 0 end-1]
+        lassign [\fByieldto\fR $target $value] value
+    }
+}
+\fBcoroutine\fR j1 juggler Larry [
+    \fBcoroutine\fR j2 juggler Curly [
+        \fBcoroutine\fR j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!"
+.CE
+.VE TIP396
 .SS "DETAILED SEMANTICS"
 .PP
 This example demonstrates that coroutines start from the global namespace, and