ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/README
(Generate patch)

Comparing Coro/README (file contents):
Revision 1.14 by root, Sat May 10 22:32:40 2008 UTC vs.
Revision 1.16 by root, Wed Oct 22 16:34:07 2008 UTC

… …
14 cede; # yield to coroutine 14 cede; # yield to coroutine
15 print "3\n"; 15 print "3\n";
16 cede; # and again 16 cede; # and again
17 17
18 # use locking 18 # use locking
19 use Coro::Semaphore;
19 my $lock = new Coro::Semaphore; 20 my $lock = new Coro::Semaphore;
20 my $locked; 21 my $locked;
21 22
22 $lock->down; 23 $lock->down;
23 $locked = 1; 24 $locked = 1;
… …
53 54
54 $Coro::main 55 $Coro::main
55 This variable stores the coroutine object that represents the main 56 This variable stores the coroutine object that represents the main
56 program. While you cna "ready" it and do most other things you can 57 program. While you cna "ready" it and do most other things you can
57 do to coroutines, it is mainly useful to compare again 58 do to coroutines, it is mainly useful to compare again
58 $Coro::current, to see wether you are running in the main program or 59 $Coro::current, to see whether you are running in the main program
59 not. 60 or not.
60 61
61 $Coro::current 62 $Coro::current
62 The coroutine object representing the current coroutine (the last 63 The coroutine object representing the current coroutine (the last
63 coroutine that the Coro scheduler switched to). The initial value is 64 coroutine that the Coro scheduler switched to). The initial value is
64 $main (of course). 65 $main (of course).
… …
126 call terminate or join on it (although you are allowed to), and you 127 call terminate or join on it (although you are allowed to), and you
127 get a coroutine that might have executed other code already (which 128 get a coroutine that might have executed other code already (which
128 can be good or bad :). 129 can be good or bad :).
129 130
130 On the plus side, this function is faster than creating (and 131 On the plus side, this function is faster than creating (and
131 destroying) a completely new coroutine, so if you need a lot of 132 destroying) a completly new coroutine, so if you need a lot of
132 generic coroutines in quick successsion, use "async_pool", not 133 generic coroutines in quick successsion, use "async_pool", not
133 "async". 134 "async".
134 135
135 The code block is executed in an "eval" context and a warning will 136 The code block is executed in an "eval" context and a warning will
136 be issued in case of an exception instead of terminating the 137 be issued in case of an exception instead of terminating the
… …
141 142
142 The priority will be reset to 0 after each run, tracing will be 143 The priority will be reset to 0 after each run, tracing will be
143 disabled, the description will be reset and the default output 144 disabled, the description will be reset and the default output
144 filehandle gets restored, so you can change all these. Otherwise the 145 filehandle gets restored, so you can change all these. Otherwise the
145 coroutine will be re-used "as-is": most notably if you change other 146 coroutine will be re-used "as-is": most notably if you change other
146 per-coroutine global stuff such as $/ you *must needs* to revert 147 per-coroutine global stuff such as $/ you *must needs* revert that
147 that change, which is most simply done by using local as in: " local 148 change, which is most simply done by using local as in: "local $/".
148 $/ ".
149 149
150 The pool size is limited to 8 idle coroutines (this can be adjusted 150 The idle pool size is limited to 8 idle coroutines (this can be
151 by changing $Coro::POOL_SIZE), and there can be as many non-idle 151 adjusted by changing $Coro::POOL_SIZE), but there can be as many
152 coros as required. 152 non-idle coros as required.
153 153
154 If you are concerned about pooled coroutines growing a lot because a 154 If you are concerned about pooled coroutines growing a lot because a
155 single "async_pool" used a lot of stackspace you can e.g. 155 single "async_pool" used a lot of stackspace you can e.g.
156 "async_pool { terminate }" once per second or so to slowly replenish 156 "async_pool { terminate }" once per second or so to slowly replenish
157 the pool. In addition to that, when the stacks used by a handler 157 the pool. In addition to that, when the stacks used by a handler
… …
177 This makes "schedule" *the* generic method to use to block the 177 This makes "schedule" *the* generic method to use to block the
178 current coroutine and wait for events: first you remember the 178 current coroutine and wait for events: first you remember the
179 current coroutine in a variable, then arrange for some callback of 179 current coroutine in a variable, then arrange for some callback of
180 yours to call "->ready" on that once some event happens, and last 180 yours to call "->ready" on that once some event happens, and last
181 you call "schedule" to put yourself to sleep. Note that a lot of 181 you call "schedule" to put yourself to sleep. Note that a lot of
182 things can wake your coroutine up, so you need to check wether the 182 things can wake your coroutine up, so you need to check whether the
183 event indeed happened, e.g. by storing the status in a variable. 183 event indeed happened, e.g. by storing the status in a variable.
184 184
185 The canonical way to wait on external events is this: 185 The canonical way to wait on external events is this:
186 186
187 { 187 {
… …
223 Kills/terminates/cancels all coroutines except the currently running 223 Kills/terminates/cancels all coroutines except the currently running
224 one. This is useful after a fork, either in the child or the parent, 224 one. This is useful after a fork, either in the child or the parent,
225 as usually only one of them should inherit the running coroutines. 225 as usually only one of them should inherit the running coroutines.
226 226
227 Note that while this will try to free some of the main programs 227 Note that while this will try to free some of the main programs
228 resources, you cnanot free all of them, so if a coroutine that is 228 resources, you cannot free all of them, so if a coroutine that is
229 not the main program calls this function, there will be some 229 not the main program calls this function, there will be some
230 one-time resource leak. 230 one-time resource leak.
231 231
232 COROUTINE METHODS 232 COROUTINE METHODS
233 These are the methods you can call on coroutine objects (or to create 233 These are the methods you can call on coroutine objects (or to create
… …
251 automatically once all the coroutines of higher priority and all 251 automatically once all the coroutines of higher priority and all
252 coroutines of the same priority that were put into the ready queue 252 coroutines of the same priority that were put into the ready queue
253 earlier have been resumed. 253 earlier have been resumed.
254 254
255 $is_ready = $coroutine->is_ready 255 $is_ready = $coroutine->is_ready
256 Return wether the coroutine is currently the ready queue or not, 256 Return whether the coroutine is currently the ready queue or not,
257 257
258 $coroutine->cancel (arg...) 258 $coroutine->cancel (arg...)
259 Terminates the given coroutine and makes it return the given 259 Terminates the given coroutine and makes it return the given
260 arguments as status (default: the empty list). Never returns if the 260 arguments as status (default: the empty list). Never returns if the
261 coroutine is the current coroutine. 261 coroutine is the current coroutine.

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines