1coroutine(n)                 Tcl Built-In Commands                coroutine(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       coroutine, yield, yieldto - Create and produce values from coroutines
9

SYNOPSIS

11       coroutine name command ?arg...?
12       yield ?value?
13       yieldto command ?arg...?                                                │
14       name ?value...?                                                         │
15______________________________________________________________________________
16

DESCRIPTION

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
24       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
34       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
47       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
51              proc yieldm {value} {                                            │
52                  yieldto return -level 0 $value                               │
53              }                                                                │
54
55       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
62       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

EXAMPLES

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
71              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
85       In  this  example, the coroutine acts to add up the arguments passed to
86       it.
87
88              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
98       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
102              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
124       This example shows how a value can be passed around a  group  of  three │
125       coroutines that yield to each other:                                    │
126
127              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
141   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
146              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
165       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
172              making from 2
173              made inner 1 context=:: name=::demo::coroEg
174

SEE ALSO

176       apply(n), info(n), proc(n), return(n)
177

KEYWORDS

179       coroutine, generator
180
181
182
183Tcl                                   8.6                         coroutine(n)
Impressum