1coroutine(n) Tcl Built-In Commands coroutine(n)
2______________________________________________________________________________
6
8 coroutine, yield, yieldto - Create and produce values from coroutines
9
11 coroutine name command ?arg...?
12 yield ?value?
13 yieldto command ?arg...? │
14 name ?value...? │
15______________________________________________________________________________
16
18 The coroutine command creates a new coroutine context (with associated
19 command) named name and executes that context by calling command, pass‐
20 ing in the other remaining arguments without further interpretation.
21 Once command returns normally or with an exception (e.g., an error) the
22 coroutine context name is deleted.
23 Within the context, values may be generated as results by using the
25 yield command; if no value is supplied, the empty string is used. When
26 that is called, the context will suspend execution and the coroutine
27 command will return the argument to yield. The execution of the context
28 can then be resumed by calling the context command, optionally passing
29 in the single value to use as the result of the yield call that caused
30 the context to be suspended. If the coroutine context never yields and
31 instead returns conventionally, the result of the coroutine command
32 will be the result of the evaluation of the context.
33 The coroutine may also suspend its execution by use of the yieldto com‐ │
35 mand, which instead of returning, cedes execution to some command │
36 called command (resolved in the context of the coroutine) and to which │
37 any number of arguments may be passed. Since every coroutine has a con‐ │
38 text command, yieldto can be used to transfer control directly from one │
39 coroutine to another (this is only advisable if the two coroutines are │
40 expecting this to happen) but any command may be the target. If a │
41 coroutine is suspended by this mechanism, the coroutine processing can │
42 be resumed by calling the context command optionally passing in an │
43 arbitrary number of arguments. The return value of the yieldto call │
44 will be the list of arguments passed to the context command; it is up │
45 to the caller to decide what to do with those values. │
46 The recommended way of writing a version of yield that allows resump‐ │
48 tion with multiple arguments is by using yieldto and the return com‐ │
49 mand, like this: │
50 proc yieldm {value} { │
52 yieldto return -level 0 $value │
53 } │
54 The coroutine can also be deleted by destroying the command name, and
56 the name of the current coroutine can be retrieved by using info corou‐
57 tine. If there are deletion traces on variables in the coroutine's
58 implementation, they will fire at the point when the coroutine is
59 explicitly deleted (or, naturally, if the command returns convention‐
60 ally).
61 At the point when command is called, the current namespace will be the
63 global namespace and there will be no stack frames above it (in the
64 sense of upvar and uplevel). However, which command to call will be
65 determined in the namespace that the coroutine command was called from.
66
68 This example shows a coroutine that will produce an infinite sequence
69 of even values, and a loop that consumes the first ten of them.
70 proc allNumbers {} {
72 yield
73 set i 0
74 while 1 {
75 yield $i
76 incr i 2
77 }
78 }
79 coroutine nextNumber allNumbers
80 for {set i 0} {$i < 10} {incr i} {
81 puts "received [nextNumber]"
82 }
83 rename nextNumber {}
84 In this example, the coroutine acts to add up the arguments passed to
86 it.
87 coroutine accumulator apply {{} {
89 set x 0
90 while 1 {
91 incr x [yield $x]
92 }
93 }}
94 for {set i 0} {$i < 10} {incr i} {
95 puts "$i -> [accumulator $i]"
96 }
97 This example demonstrates the use of coroutines to implement the clas‐
99 sic Sieve of Eratosthenes algorithm for finding prime numbers. Note the
100 creation of coroutines inside a coroutine.
101 proc filterByFactor {source n} {
103 yield [info coroutine]
104 while 1 {
105 set x [$source]
106 if {$x % $n} {
107 yield $x
108 }
109 }
110 }
111 coroutine allNumbers apply {{} {while 1 {yield [incr x]}}}
112 coroutine eratosthenes apply {c {
113 yield
114 while 1 {
115 set n [$c]
116 yield $n
117 set c [coroutine prime$n filterByFactor $c $n]
118 }
119 }} allNumbers
120 for {set i 1} {$i <= 20} {incr i} {
121 puts "prime#$i = [eratosthenes]"
122 }
123 This example shows how a value can be passed around a group of three │
125 coroutines that yield to each other: │
126 proc juggler {name target {value ""}} { │
128 if {$value eq ""} { │
129 set value [yield [info coroutine]] │
130 } │
131 while {$value ne ""} { │
132 puts "$name : $value" │
133 set value [string range $value 0 end-1] │
134 lassign [yieldto $target $value] value │
135 } │
136 } │
137 coroutine j1 juggler Larry [ │
138 coroutine j2 juggler Curly [ │
139 coroutine j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!" │
140 DETAILED SEMANTICS
142 This example demonstrates that coroutines start from the global names‐
143 pace, and that command resolution happens before the coroutine stack is
144 created.
145 proc report {where level} {
147 # Where was the caller called from?
148 set ns [uplevel 2 {namespace current}]
149 yield "made $where $level context=$ns name=[info coroutine]"
150 }
151 proc example {} {
152 report outer [info level]
153 }
154 namespace eval demo {
155 proc example {} {
156 report inner [info level]
157 }
158 proc makeExample {} {
159 puts "making from [info level]"
160 puts [coroutine coroEg example]
161 }
162 makeExample
163 }
164 Which produces the output below. In particular, we can see that stack
166 manipulation has occurred (comparing the levels from the first and sec‐
167 ond line) and that the parent level in the coroutine is the global
168 namespace. We can also see that coroutine names are local to the cur‐
169 rent namespace if not qualified, and that coroutines may yield at depth
170 (e.g., in called procedures).
171 making from 2
173 made inner 1 context=:: name=::demo::coroEg
174
176 apply(n), info(n), proc(n), return(n)
177
179 coroutine, generator
180Tcl 8.6 coroutine(n)