+++ /dev/null
-'\"
-'\" Copyright (c) 2009 Donal K. Fellows.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH coroutine n 8.6 Tcl "Tcl Built-In Commands"
-.so man.macros
-.BS
-'\" Note: do not modify the .SH NAME line immediately below!
-.SH NAME
-coroutine, yield, yieldto \- Create and produce values from coroutines
-.SH SYNOPSIS
-.nf
-\fBcoroutine \fIname command\fR ?\fIarg...\fR?
-\fByield\fR ?\fIvalue\fR?
-.VS TIP396
-\fByieldto\fR \fIcommand\fR ?\fIarg...\fR?
-\fIname\fR ?\fIvalue...\fR?
-.VE TIP396
-.fi
-.BE
-.SH DESCRIPTION
-.PP
-The \fBcoroutine\fR command creates a new coroutine context (with associated
-command) named \fIname\fR and executes that context by calling \fIcommand\fR,
-passing in the other remaining arguments without further interpretation. Once
-\fIcommand\fR returns normally or with an exception (e.g., an error) the
-coroutine context \fIname\fR is deleted.
-.PP
-Within the context, values may be generated as results by using the
-\fByield\fR command; if no \fIvalue\fR is supplied, the empty string is used.
-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 \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.
-If there are deletion traces on variables in the coroutine's
-implementation, they will fire at the point when the coroutine is explicitly
-deleted (or, naturally, if the command returns conventionally).
-.PP
-At the point when \fIcommand\fR is called, the current namespace will be the
-global namespace and there will be no stack frames above it (in the sense of
-\fBupvar\fR and \fBuplevel\fR). However, which command to call will be
-determined in the namespace that the \fBcoroutine\fR command was called from.
-.SH EXAMPLES
-.PP
-This example shows a coroutine that will produce an infinite sequence of
-even values, and a loop that consumes the first ten of them.
-.PP
-.CS
-proc allNumbers {} {
- \fByield\fR
- set i 0
- while 1 {
- \fByield\fR $i
- incr i 2
- }
-}
-\fBcoroutine\fR nextNumber allNumbers
-for {set i 0} {$i < 10} {incr i} {
- puts "received [\fInextNumber\fR]"
-}
-rename nextNumber {}
-.CE
-.PP
-In this example, the coroutine acts to add up the arguments passed to it.
-.PP
-.CS
-\fBcoroutine\fR accumulator apply {{} {
- set x 0
- while 1 {
- incr x [\fByield\fR $x]
- }
-}}
-for {set i 0} {$i < 10} {incr i} {
- puts "$i -> [\fIaccumulator\fR $i]"
-}
-.CE
-.PP
-This example demonstrates the use of coroutines to implement the classic Sieve
-of Eratosthenes algorithm for finding prime numbers. Note the creation of
-coroutines inside a coroutine.
-.PP
-.CS
-proc filterByFactor {source n} {
- \fByield\fR [info coroutine]
- while 1 {
- set x [\fI$source\fR]
- if {$x % $n} {
- \fByield\fR $x
- }
- }
-}
-\fBcoroutine\fR allNumbers apply {{} {while 1 {\fByield\fR [incr x]}}}
-\fBcoroutine\fR eratosthenes apply {c {
- \fByield\fR
- while 1 {
- set n [\fI$c\fR]
- \fByield\fR $n
- set c [\fBcoroutine\fR prime$n filterByFactor $c $n]
- }
-}} allNumbers
-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
-that \fIcommand\fR resolution happens before the coroutine stack is created.
-.PP
-.CS
-proc report {where level} {
- # Where was the caller called from?
- set ns [uplevel 2 {namespace current}]
- \fByield\fR "made $where $level context=$ns name=[info coroutine]"
-}
-proc example {} {
- report outer [info level]
-}
-namespace eval demo {
- proc example {} {
- report inner [info level]
- }
- proc makeExample {} {
- puts "making from [info level]"
- puts [\fBcoroutine\fR coroEg example]
- }
- makeExample
-}
-.CE
-.PP
-Which produces the output below. In particular, we can see that stack
-manipulation has occurred (comparing the levels from the first and second
-line) and that the parent level in the coroutine is the global namespace. We
-can also see that coroutine names are local to the current namespace if not
-qualified, and that coroutines may yield at depth (e.g., in called
-procedures).
-.PP
-.CS
-making from 2
-made inner 1 context=:: name=::demo::coroEg
-.CE
-.SH "SEE ALSO"
-apply(n), info(n), proc(n), return(n)
-.SH KEYWORDS
-coroutine, generator
-'\" Local Variables:
-'\" mode: nroff
-'\" fill-column: 78
-'\" End:
OSDN Git Service
