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

Comparing Coro/README (file contents):
Revision 1.19 by root, Mon Nov 24 07:55:28 2008 UTC vs.
Revision 1.24 by root, Tue Jun 23 23:40:06 2009 UTC

1NAME 1NAME
2 Coro - the only real threads in perl 2 Coro - the only real threads in perl
3 3
4SYNOPSIS 4SYNOPSIS
5 use Coro; 5 use Coro;
6 6
7 async { 7 async {
8 # some asynchronous thread of execution 8 # some asynchronous thread of execution
9 print "2\n"; 9 print "2\n";
10 cede; # yield back to main 10 cede; # yield back to main
11 print "4\n"; 11 print "4\n";
12 }; 12 };
13 print "1\n"; 13 print "1\n";
14 cede; # yield to coroutine 14 cede; # yield to coro
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 use Coro::Semaphore;
20 my $lock = new Coro::Semaphore; 20 my $lock = new Coro::Semaphore;
21 my $locked; 21 my $locked;
22 22
23 $lock->down; 23 $lock->down;
24 $locked = 1; 24 $locked = 1;
25 $lock->up; 25 $lock->up;
26 26
27DESCRIPTION 27DESCRIPTION
28 For a tutorial-style introduction, please read the Coro::Intro manpage. 28 For a tutorial-style introduction, please read the Coro::Intro manpage.
29 This manpage mainly contains reference information. 29 This manpage mainly contains reference information.
30 30
31 This module collection manages continuations in general, most often in 31 This module collection manages continuations in general, most often in
32 the form of cooperative threads (also called coroutines in the 32 the form of cooperative threads (also called coros, or simply "coro" in
33 documentation). They are similar to kernel threads but don't (in 33 the documentation). They are similar to kernel threads but don't (in
34 general) run in parallel at the same time even on SMP machines. The 34 general) run in parallel at the same time even on SMP machines. The
35 specific flavor of thread offered by this module also guarantees you 35 specific flavor of thread offered by this module also guarantees you
36 that it will not switch between threads unless necessary, at 36 that it will not switch between threads unless necessary, at
37 easily-identified points in your program, so locking and parallel access 37 easily-identified points in your program, so locking and parallel access
38 are rarely an issue, making thread programming much safer and easier 38 are rarely an issue, making thread programming much safer and easier
39 than using other thread models. 39 than using other thread models.
40 40
41 Unlike the so-called "Perl threads" (which are not actually real threads 41 Unlike the so-called "Perl threads" (which are not actually real threads
42 but only the windows process emulation ported to unix), Coro provides a 42 but only the windows process emulation ported to unix, and as such act
43 full shared address space, which makes communication between threads 43 as processes), Coro provides a full shared address space, which makes
44 very easy. And threads are fast, too: disabling the Windows process 44 communication between threads very easy. And Coro's threads are fast,
45 emulation code in your perl and using Coro can easily result in a two to 45 too: disabling the Windows process emulation code in your perl and using
46 four times speed increase for your programs. 46 Coro can easily result in a two to four times speed increase for your
47 programs. A parallel matrix multiplication benchmark runs over 300 times
48 faster on a single core than perl's pseudo-threads on a quad core using
49 all four cores.
47 50
48 Coro achieves that by supporting multiple running interpreters that 51 Coro achieves that by supporting multiple running interpreters that
49 share data, which is especially useful to code pseudo-parallel processes 52 share data, which is especially useful to code pseudo-parallel processes
50 and for event-based programming, such as multiple HTTP-GET requests 53 and for event-based programming, such as multiple HTTP-GET requests
51 running concurrently. See Coro::AnyEvent to learn more on how to 54 running concurrently. See Coro::AnyEvent to learn more on how to
52 integrate Coro into an event-based environment. 55 integrate Coro into an event-based environment.
53 56
54 In this module, a thread is defined as "callchain + lexical variables + 57 In this module, a thread is defined as "callchain + lexical variables +
55 @_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain, 58 some package variables + C stack), that is, a thread has its own
56 its own set of lexicals and its own set of perls most important global 59 callchain, its own set of lexicals and its own set of perls most
57 variables (see Coro::State for more configuration and background info). 60 important global variables (see Coro::State for more configuration and
61 background info).
58 62
59 See also the "SEE ALSO" section at the end of this document - the Coro 63 See also the "SEE ALSO" section at the end of this document - the Coro
60 module family is quite large. 64 module family is quite large.
61 65
62GLOBAL VARIABLES 66GLOBAL VARIABLES
63 $Coro::main 67 $Coro::main
64 This variable stores the coroutine object that represents the main 68 This variable stores the Coro object that represents the main
65 program. While you cna "ready" it and do most other things you can 69 program. While you cna "ready" it and do most other things you can
66 do to coroutines, it is mainly useful to compare again 70 do to coro, it is mainly useful to compare again $Coro::current, to
67 $Coro::current, to see whether you are running in the main program 71 see whether you are running in the main program or not.
68 or not.
69 72
70 $Coro::current 73 $Coro::current
71 The coroutine object representing the current coroutine (the last 74 The Coro object representing the current coro (the last coro that
72 coroutine that the Coro scheduler switched to). The initial value is 75 the Coro scheduler switched to). The initial value is $Coro::main
73 $Coro::main (of course). 76 (of course).
74 77
75 This variable is strictly *read-only*. You can take copies of the 78 This variable is strictly *read-only*. You can take copies of the
76 value stored in it and use it as any other coroutine object, but you 79 value stored in it and use it as any other Coro object, but you must
77 must not otherwise modify the variable itself. 80 not otherwise modify the variable itself.
78 81
79 $Coro::idle 82 $Coro::idle
80 This variable is mainly useful to integrate Coro into event loops. 83 This variable is mainly useful to integrate Coro into event loops.
81 It is usually better to rely on Coro::AnyEvent or Coro::EV, as this 84 It is usually better to rely on Coro::AnyEvent or Coro::EV, as this
82 is pretty low-level functionality. 85 is pretty low-level functionality.
83 86
84 This variable stores either a coroutine or a callback. 87 This variable stores either a Coro object or a callback.
85 88
86 If it is a callback, the it is called whenever the scheduler finds 89 If it is a callback, the it is called whenever the scheduler finds
87 no ready coroutines to run. The default implementation prints 90 no ready coros to run. The default implementation prints "FATAL:
88 "FATAL: deadlock detected" and exits, because the program has no 91 deadlock detected" and exits, because the program has no other way
89 other way to continue. 92 to continue.
90 93
91 If it is a coroutine object, then this object will be readied 94 If it is a coro object, then this object will be readied (without
92 (without invoking any ready hooks, however) when the scheduler finds 95 invoking any ready hooks, however) when the scheduler finds no other
93 no other ready coroutines to run. 96 ready coros to run.
94 97
95 This hook is overwritten by modules such as "Coro::EV" and 98 This hook is overwritten by modules such as "Coro::EV" and
96 "Coro::AnyEvent" to wait on an external event that hopefully wake up 99 "Coro::AnyEvent" to wait on an external event that hopefully wake up
97 a coroutine so the scheduler can run it. 100 a coro so the scheduler can run it.
98 101
99 Note that the callback *must not*, under any circumstances, block 102 Note that the callback *must not*, under any circumstances, block
100 the current coroutine. Normally, this is achieved by having an "idle 103 the current coro. Normally, this is achieved by having an "idle
101 coroutine" that calls the event loop and then blocks again, and then 104 coro" that calls the event loop and then blocks again, and then
102 readying that coroutine in the idle handler, or by simply placing 105 readying that coro in the idle handler, or by simply placing the
103 the idle coroutine in this variable. 106 idle coro in this variable.
104 107
105 See Coro::Event or Coro::AnyEvent for examples of using this 108 See Coro::Event or Coro::AnyEvent for examples of using this
106 technique. 109 technique.
107 110
108 Please note that if your callback recursively invokes perl (e.g. for 111 Please note that if your callback recursively invokes perl (e.g. for
109 event handlers), then it must be prepared to be called recursively 112 event handlers), then it must be prepared to be called recursively
110 itself. 113 itself.
111 114
112SIMPLE COROUTINE CREATION 115SIMPLE CORO CREATION
113 async { ... } [@args...] 116 async { ... } [@args...]
114 Create a new coroutine and return it's coroutine object (usually 117 Create a new coro and return its Coro object (usually unused). The
115 unused). The coroutine will be put into the ready queue, so it will 118 coro will be put into the ready queue, so it will start running
116 start running automatically on the next scheduler run. 119 automatically on the next scheduler run.
117 120
118 The first argument is a codeblock/closure that should be executed in 121 The first argument is a codeblock/closure that should be executed in
119 the coroutine. When it returns argument returns the coroutine is 122 the coro. When it returns argument returns the coro is automatically
120 automatically terminated. 123 terminated.
121 124
122 The remaining arguments are passed as arguments to the closure. 125 The remaining arguments are passed as arguments to the closure.
123 126
124 See the "Coro::State::new" constructor for info about the coroutine 127 See the "Coro::State::new" constructor for info about the coro
125 environment in which coroutines are executed. 128 environment in which coro are executed.
126 129
127 Calling "exit" in a coroutine will do the same as calling exit 130 Calling "exit" in a coro will do the same as calling exit outside
128 outside the coroutine. Likewise, when the coroutine dies, the 131 the coro. Likewise, when the coro dies, the program will exit, just
129 program will exit, just as it would in the main program. 132 as it would in the main program.
130 133
131 If you do not want that, you can provide a default "die" handler, or 134 If you do not want that, you can provide a default "die" handler, or
132 simply avoid dieing (by use of "eval"). 135 simply avoid dieing (by use of "eval").
133 136
134 Example: Create a new coroutine that just prints its arguments. 137 Example: Create a new coro that just prints its arguments.
135 138
136 async { 139 async {
137 print "@_\n"; 140 print "@_\n";
138 } 1,2,3,4; 141 } 1,2,3,4;
139 142
140 async_pool { ... } [@args...] 143 async_pool { ... } [@args...]
141 Similar to "async", but uses a coroutine pool, so you should not 144 Similar to "async", but uses a coro pool, so you should not call
142 call terminate or join on it (although you are allowed to), and you 145 terminate or join on it (although you are allowed to), and you get a
143 get a coroutine that might have executed other code already (which 146 coro that might have executed other code already (which can be good
144 can be good or bad :). 147 or bad :).
145 148
146 On the plus side, this function is about twice as fast as creating 149 On the plus side, this function is about twice as fast as creating
147 (and destroying) a completely new coroutine, so if you need a lot of 150 (and destroying) a completely new coro, so if you need a lot of
148 generic coroutines in quick successsion, use "async_pool", not 151 generic coros in quick successsion, use "async_pool", not "async".
149 "async".
150 152
151 The code block is executed in an "eval" context and a warning will 153 The code block is executed in an "eval" context and a warning will
152 be issued in case of an exception instead of terminating the 154 be issued in case of an exception instead of terminating the
153 program, as "async" does. As the coroutine is being reused, stuff 155 program, as "async" does. As the coro is being reused, stuff like
154 like "on_destroy" will not work in the expected way, unless you call 156 "on_destroy" will not work in the expected way, unless you call
155 terminate or cancel, which somehow defeats the purpose of pooling 157 terminate or cancel, which somehow defeats the purpose of pooling
156 (but is fine in the exceptional case). 158 (but is fine in the exceptional case).
157 159
158 The priority will be reset to 0 after each run, tracing will be 160 The priority will be reset to 0 after each run, tracing will be
159 disabled, the description will be reset and the default output 161 disabled, the description will be reset and the default output
160 filehandle gets restored, so you can change all these. Otherwise the 162 filehandle gets restored, so you can change all these. Otherwise the
161 coroutine will be re-used "as-is": most notably if you change other 163 coro will be re-used "as-is": most notably if you change other
162 per-coroutine global stuff such as $/ you *must needs* revert that 164 per-coro global stuff such as $/ you *must needs* revert that
163 change, which is most simply done by using local as in: "local $/". 165 change, which is most simply done by using local as in: "local $/".
164 166
165 The idle pool size is limited to 8 idle coroutines (this can be 167 The idle pool size is limited to 8 idle coros (this can be adjusted
166 adjusted by changing $Coro::POOL_SIZE), but there can be as many 168 by changing $Coro::POOL_SIZE), but there can be as many non-idle
167 non-idle coros as required. 169 coros as required.
168 170
169 If you are concerned about pooled coroutines growing a lot because a 171 If you are concerned about pooled coros growing a lot because a
170 single "async_pool" used a lot of stackspace you can e.g. 172 single "async_pool" used a lot of stackspace you can e.g.
171 "async_pool { terminate }" once per second or so to slowly replenish 173 "async_pool { terminate }" once per second or so to slowly replenish
172 the pool. In addition to that, when the stacks used by a handler 174 the pool. In addition to that, when the stacks used by a handler
173 grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also 175 grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also
174 be destroyed. 176 be destroyed.
175 177
176STATIC METHODS 178STATIC METHODS
177 Static methods are actually functions that implicitly operate on the 179 Static methods are actually functions that implicitly operate on the
178 current coroutine. 180 current coro.
179 181
180 schedule 182 schedule
181 Calls the scheduler. The scheduler will find the next coroutine that 183 Calls the scheduler. The scheduler will find the next coro that is
182 is to be run from the ready queue and switches to it. The next 184 to be run from the ready queue and switches to it. The next coro to
183 coroutine to be run is simply the one with the highest priority that 185 be run is simply the one with the highest priority that is longest
184 is longest in its ready queue. If there is no coroutine ready, it 186 in its ready queue. If there is no coro ready, it will clal the
185 will clal the $Coro::idle hook. 187 $Coro::idle hook.
186 188
187 Please note that the current coroutine will *not* be put into the 189 Please note that the current coro will *not* be put into the ready
188 ready queue, so calling this function usually means you will never 190 queue, so calling this function usually means you will never be
189 be called again unless something else (e.g. an event handler) calls 191 called again unless something else (e.g. an event handler) calls
190 "->ready", thus waking you up. 192 "->ready", thus waking you up.
191 193
192 This makes "schedule" *the* generic method to use to block the 194 This makes "schedule" *the* generic method to use to block the
193 current coroutine and wait for events: first you remember the 195 current coro and wait for events: first you remember the current
194 current coroutine in a variable, then arrange for some callback of 196 coro in a variable, then arrange for some callback of yours to call
195 yours to call "->ready" on that once some event happens, and last 197 "->ready" on that once some event happens, and last you call
196 you call "schedule" to put yourself to sleep. Note that a lot of 198 "schedule" to put yourself to sleep. Note that a lot of things can
197 things can wake your coroutine up, so you need to check whether the 199 wake your coro up, so you need to check whether the event indeed
198 event indeed happened, e.g. by storing the status in a variable. 200 happened, e.g. by storing the status in a variable.
199 201
200 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for 202 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
201 callbacks. 203 callbacks.
202 204
203 cede 205 cede
204 "Cede" to other coroutines. This function puts the current coroutine 206 "Cede" to other coros. This function puts the current coro into the
205 into the ready queue and calls "schedule", which has the effect of 207 ready queue and calls "schedule", which has the effect of giving up
206 giving up the current "timeslice" to other coroutines of the same or 208 the current "timeslice" to other coros of the same or higher
207 higher priority. Once your coroutine gets its turn again it will 209 priority. Once your coro gets its turn again it will automatically
208 automatically be resumed. 210 be resumed.
209 211
210 This function is often called "yield" in other languages. 212 This function is often called "yield" in other languages.
211 213
212 Coro::cede_notself 214 Coro::cede_notself
213 Works like cede, but is not exported by default and will cede to 215 Works like cede, but is not exported by default and will cede to
214 *any* coroutine, regardless of priority. This is useful sometimes to 216 *any* coro, regardless of priority. This is useful sometimes to
215 ensure progress is made. 217 ensure progress is made.
216 218
217 terminate [arg...] 219 terminate [arg...]
218 Terminates the current coroutine with the given status values (see 220 Terminates the current coro with the given status values (see
219 cancel). 221 cancel).
220 222
223 Coro::on_enter BLOCK, Coro::on_leave BLOCK
224 These function install enter and leave winders in the current scope.
225 The enter block will be executed when on_enter is called and
226 whenever the current coro is re-entered by the scheduler, while the
227 leave block is executed whenever the current coro is blocked by the
228 scheduler, and also when the containing scope is exited (by whatever
229 means, be it exit, die, last etc.).
230
231 *Neither invoking the scheduler, nor exceptions, are allowed within
232 those BLOCKs*. That means: do not even think about calling "die"
233 without an eval, and do not even think of entering the scheduler in
234 any way.
235
236 Since both BLOCKs are tied to the current scope, they will
237 automatically be removed when the current scope exits.
238
239 These functions implement the same concept as "dynamic-wind" in
240 scheme does, and are useful when you want to localise some resource
241 to a specific coro.
242
243 They slow down thread switching considerably for coros that use them
244 (about 40% for a BLOCK with a single assignment, so thread switching
245 is still reasonably fast if the handlers are fast).
246
247 These functions are best understood by an example: The following
248 function will change the current timezone to
249 "Antarctica/South_Pole", which requires a call to "tzset", but by
250 using "on_enter" and "on_leave", which remember/change the current
251 timezone and restore the previous value, respectively, the timezone
252 is only changed for the coro that installed those handlers.
253
254 use POSIX qw(tzset);
255
256 async {
257 my $old_tz; # store outside TZ value here
258
259 Coro::on_enter {
260 $old_tz = $ENV{TZ}; # remember the old value
261
262 $ENV{TZ} = "Antarctica/South_Pole";
263 tzset; # enable new value
264 };
265
266 Coro::on_leave {
267 $ENV{TZ} = $old_tz;
268 tzset; # restore old value
269 };
270
271 # at this place, the timezone is Antarctica/South_Pole,
272 # without disturbing the TZ of any other coro.
273 };
274
275 This can be used to localise about any resource (locale, uid,
276 current working directory etc.) to a block, despite the existance of
277 other coros.
278
279 Another interesting example implements time-sliced multitasking
280 using interval timers (this could obviously be optimised, but does
281 the job):
282
283 # "timeslice" the given block
284 sub timeslice(&) {
285 use Time::HiRes ();
286
287 Coro::on_enter {
288 # on entering the thread, we set an VTALRM handler to cede
289 $SIG{VTALRM} = sub { cede };
290 # and then start the interval timer
291 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
292 };
293 Coro::on_leave {
294 # on leaving the thread, we stop the interval timer again
295 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
296 };
297
298 &{+shift};
299 }
300
301 # use like this:
302 timeslice {
303 # The following is an endless loop that would normally
304 # monopolise the process. Since it runs in a timesliced
305 # environment, it will regularly cede to other threads.
306 while () { }
307 };
308
221 killall 309 killall
222 Kills/terminates/cancels all coroutines except the currently running 310 Kills/terminates/cancels all coros except the currently running one.
223 one. This is useful after a fork, either in the child or the parent,
224 as usually only one of them should inherit the running coroutines.
225 311
226 Note that while this will try to free some of the main programs 312 Note that while this will try to free some of the main interpreter
227 resources, you cannot free all of them, so if a coroutine that is 313 resources if the calling coro isn't the main coro, but one cannot
228 not the main program calls this function, there will be some 314 free all of them, so if a coro that is not the main coro calls this
229 one-time resource leak. 315 function, there will be some one-time resource leak.
230 316
231COROUTINE OBJECT METHODS 317CORO OBJECT METHODS
232 These are the methods you can call on coroutine objects (or to create 318 These are the methods you can call on coro objects (or to create them).
233 them).
234 319
235 new Coro \&sub [, @args...] 320 new Coro \&sub [, @args...]
236 Create a new coroutine and return it. When the sub returns, the 321 Create a new coro and return it. When the sub returns, the coro
237 coroutine automatically terminates as if "terminate" with the 322 automatically terminates as if "terminate" with the returned values
238 returned values were called. To make the coroutine run you must 323 were called. To make the coro run you must first put it into the
239 first put it into the ready queue by calling the ready method. 324 ready queue by calling the ready method.
240 325
241 See "async" and "Coro::State::new" for additional info about the 326 See "async" and "Coro::State::new" for additional info about the
242 coroutine environment. 327 coro environment.
243 328
244 $success = $coroutine->ready 329 $success = $coro->ready
245 Put the given coroutine into the end of its ready queue (there is 330 Put the given coro into the end of its ready queue (there is one
246 one queue for each priority) and return true. If the coroutine is 331 queue for each priority) and return true. If the coro is already in
247 already in the ready queue, do nothing and return false. 332 the ready queue, do nothing and return false.
248 333
249 This ensures that the scheduler will resume this coroutine 334 This ensures that the scheduler will resume this coro automatically
250 automatically once all the coroutines of higher priority and all 335 once all the coro of higher priority and all coro of the same
251 coroutines of the same priority that were put into the ready queue 336 priority that were put into the ready queue earlier have been
252 earlier have been resumed. 337 resumed.
253 338
339 $coro->suspend
340 Suspends the specified coro. A suspended coro works just like any
341 other coro, except that the scheduler will not select a suspended
342 coro for execution.
343
344 Suspending a coro can be useful when you want to keep the coro from
345 running, but you don't want to destroy it, or when you want to
346 temporarily freeze a coro (e.g. for debugging) to resume it later.
347
348 A scenario for the former would be to suspend all (other) coros
349 after a fork and keep them alive, so their destructors aren't
350 called, but new coros can be created.
351
352 $coro->resume
353 If the specified coro was suspended, it will be resumed. Note that
354 when the coro was in the ready queue when it was suspended, it might
355 have been unreadied by the scheduler, so an activation might have
356 been lost.
357
358 To avoid this, it is best to put a suspended coro into the ready
359 queue unconditionally, as every synchronisation mechanism must
360 protect itself against spurious wakeups, and the one in the Coro
361 family certainly do that.
362
254 $is_ready = $coroutine->is_ready 363 $is_ready = $coro->is_ready
255 Return whether the coroutine is currently the ready queue or not, 364 Returns true iff the Coro object is in the ready queue. Unless the
365 Coro object gets destroyed, it will eventually be scheduled by the
366 scheduler.
256 367
368 $is_running = $coro->is_running
369 Returns true iff the Coro object is currently running. Only one Coro
370 object can ever be in the running state (but it currently is
371 possible to have multiple running Coro::States).
372
373 $is_suspended = $coro->is_suspended
374 Returns true iff this Coro object has been suspended. Suspended
375 Coros will not ever be scheduled.
376
257 $coroutine->cancel (arg...) 377 $coro->cancel (arg...)
258 Terminates the given coroutine and makes it return the given 378 Terminates the given Coro and makes it return the given arguments as
259 arguments as status (default: the empty list). Never returns if the 379 status (default: the empty list). Never returns if the Coro is the
260 coroutine is the current coroutine. 380 current Coro.
261 381
262 $coroutine->schedule_to 382 $coro->schedule_to
263 Puts the current coroutine to sleep (like "Coro::schedule"), but 383 Puts the current coro to sleep (like "Coro::schedule"), but instead
264 instead of continuing with the next coro from the ready queue, 384 of continuing with the next coro from the ready queue, always switch
265 always switch to the given coroutine object (regardless of priority 385 to the given coro object (regardless of priority etc.). The
266 etc.). The readyness state of that coroutine isn't changed. 386 readyness state of that coro isn't changed.
267 387
268 This is an advanced method for special cases - I'd love to hear 388 This is an advanced method for special cases - I'd love to hear
269 about any uses for this one. 389 about any uses for this one.
270 390
271 $coroutine->cede_to 391 $coro->cede_to
272 Like "schedule_to", but puts the current coroutine into the ready 392 Like "schedule_to", but puts the current coro into the ready queue.
273 queue. This has the effect of temporarily switching to the given 393 This has the effect of temporarily switching to the given coro, and
274 coroutine, and continuing some time later. 394 continuing some time later.
275 395
276 This is an advanced method for special cases - I'd love to hear 396 This is an advanced method for special cases - I'd love to hear
277 about any uses for this one. 397 about any uses for this one.
278 398
279 $coroutine->throw ([$scalar]) 399 $coro->throw ([$scalar])
280 If $throw is specified and defined, it will be thrown as an 400 If $throw is specified and defined, it will be thrown as an
281 exception inside the coroutine at the next convenient point in time. 401 exception inside the coro at the next convenient point in time.
282 Otherwise clears the exception object. 402 Otherwise clears the exception object.
283 403
284 Coro will check for the exception each time a schedule-like-function 404 Coro will check for the exception each time a schedule-like-function
285 returns, i.e. after each "schedule", "cede", 405 returns, i.e. after each "schedule", "cede",
286 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of 406 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
… …
289 409
290 The exception object will be thrown "as is" with the specified 410 The exception object will be thrown "as is" with the specified
291 scalar in $@, i.e. if it is a string, no line number or newline will 411 scalar in $@, i.e. if it is a string, no line number or newline will
292 be appended (unlike with "die"). 412 be appended (unlike with "die").
293 413
294 This can be used as a softer means than "cancel" to ask a coroutine 414 This can be used as a softer means than "cancel" to ask a coro to
295 to end itself, although there is no guarantee that the exception 415 end itself, although there is no guarantee that the exception will
296 will lead to termination, and if the exception isn't caught it might 416 lead to termination, and if the exception isn't caught it might well
297 well end the whole program. 417 end the whole program.
298 418
299 You might also think of "throw" as being the moral equivalent of 419 You might also think of "throw" as being the moral equivalent of
300 "kill"ing a coroutine with a signal (in this case, a scalar). 420 "kill"ing a coro with a signal (in this case, a scalar).
301 421
302 $coroutine->join 422 $coro->join
303 Wait until the coroutine terminates and return any values given to 423 Wait until the coro terminates and return any values given to the
304 the "terminate" or "cancel" functions. "join" can be called 424 "terminate" or "cancel" functions. "join" can be called concurrently
305 concurrently from multiple coroutines, and all will be resumed and 425 from multiple coro, and all will be resumed and given the status
306 given the status return once the $coroutine terminates. 426 return once the $coro terminates.
307 427
308 $coroutine->on_destroy (\&cb) 428 $coro->on_destroy (\&cb)
309 Registers a callback that is called when this coroutine gets 429 Registers a callback that is called when this coro gets destroyed,
310 destroyed, but before it is joined. The callback gets passed the 430 but before it is joined. The callback gets passed the terminate
311 terminate arguments, if any, and *must not* die, under any 431 arguments, if any, and *must not* die, under any circumstances.
312 circumstances.
313 432
314 $oldprio = $coroutine->prio ($newprio) 433 $oldprio = $coro->prio ($newprio)
315 Sets (or gets, if the argument is missing) the priority of the 434 Sets (or gets, if the argument is missing) the priority of the coro.
316 coroutine. Higher priority coroutines get run before lower priority 435 Higher priority coro get run before lower priority coro. Priorities
317 coroutines. Priorities are small signed integers (currently -4 .. 436 are small signed integers (currently -4 .. +3), that you can refer
318 +3), that you can refer to using PRIO_xxx constants (use the import 437 to using PRIO_xxx constants (use the import tag :prio to get then):
319 tag :prio to get then):
320 438
321 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 439 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
322 3 > 1 > 0 > -1 > -3 > -4 440 3 > 1 > 0 > -1 > -3 > -4
323 441
324 # set priority to HIGH 442 # set priority to HIGH
325 current->prio(PRIO_HIGH); 443 current->prio (PRIO_HIGH);
326 444
327 The idle coroutine ($Coro::idle) always has a lower priority than 445 The idle coro ($Coro::idle) always has a lower priority than any
328 any existing coroutine. 446 existing coro.
329 447
330 Changing the priority of the current coroutine will take effect 448 Changing the priority of the current coro will take effect
331 immediately, but changing the priority of coroutines in the ready 449 immediately, but changing the priority of coro in the ready queue
332 queue (but not running) will only take effect after the next 450 (but not running) will only take effect after the next schedule (of
333 schedule (of that coroutine). This is a bug that will be fixed in 451 that coro). This is a bug that will be fixed in some future version.
334 some future version.
335 452
336 $newprio = $coroutine->nice ($change) 453 $newprio = $coro->nice ($change)
337 Similar to "prio", but subtract the given value from the priority 454 Similar to "prio", but subtract the given value from the priority
338 (i.e. higher values mean lower priority, just as in unix). 455 (i.e. higher values mean lower priority, just as in unix).
339 456
340 $olddesc = $coroutine->desc ($newdesc) 457 $olddesc = $coro->desc ($newdesc)
341 Sets (or gets in case the argument is missing) the description for 458 Sets (or gets in case the argument is missing) the description for
342 this coroutine. This is just a free-form string you can associate 459 this coro. This is just a free-form string you can associate with a
343 with a coroutine. 460 coro.
344 461
345 This method simply sets the "$coroutine->{desc}" member to the given 462 This method simply sets the "$coro->{desc}" member to the given
346 string. You can modify this member directly if you wish. 463 string. You can modify this member directly if you wish.
347 464
348GLOBAL FUNCTIONS 465GLOBAL FUNCTIONS
349 Coro::nready 466 Coro::nready
350 Returns the number of coroutines that are currently in the ready 467 Returns the number of coro that are currently in the ready state,
351 state, i.e. that can be switched to by calling "schedule" directory 468 i.e. that can be switched to by calling "schedule" directory or
352 or indirectly. The value 0 means that the only runnable coroutine is 469 indirectly. The value 0 means that the only runnable coro is the
353 the currently running one, so "cede" would have no effect, and 470 currently running one, so "cede" would have no effect, and
354 "schedule" would cause a deadlock unless there is an idle handler 471 "schedule" would cause a deadlock unless there is an idle handler
355 that wakes up some coroutines. 472 that wakes up some coro.
356 473
357 my $guard = Coro::guard { ... } 474 my $guard = Coro::guard { ... }
358 This creates and returns a guard object. Nothing happens until the 475 This function still exists, but is deprecated. Please use the
359 object gets destroyed, in which case the codeblock given as argument 476 "Guard::guard" function instead.
360 will be executed. This is useful to free locks or other resources in
361 case of a runtime error or when the coroutine gets canceled, as in
362 both cases the guard block will be executed. The guard object
363 supports only one method, "->cancel", which will keep the codeblock
364 from being executed.
365
366 Example: set some flag and clear it again when the coroutine gets
367 canceled or the function returns:
368
369 sub do_something {
370 my $guard = Coro::guard { $busy = 0 };
371 $busy = 1;
372
373 # do something that requires $busy to be true
374 }
375 477
376 unblock_sub { ... } 478 unblock_sub { ... }
377 This utility function takes a BLOCK or code reference and "unblocks" 479 This utility function takes a BLOCK or code reference and "unblocks"
378 it, returning a new coderef. Unblocking means that calling the new 480 it, returning a new coderef. Unblocking means that calling the new
379 coderef will return immediately without blocking, returning nothing, 481 coderef will return immediately without blocking, returning nothing,
380 while the original code ref will be called (with parameters) from 482 while the original code ref will be called (with parameters) from
381 within another coroutine. 483 within another coro.
382 484
383 The reason this function exists is that many event libraries (such 485 The reason this function exists is that many event libraries (such
384 as the venerable Event module) are not coroutine-safe (a weaker form 486 as the venerable Event module) are not thread-safe (a weaker form of
385 of reentrancy). This means you must not block within event 487 reentrancy). This means you must not block within event callbacks,
386 callbacks, otherwise you might suffer from crashes or worse. The 488 otherwise you might suffer from crashes or worse. The only event
387 only event library currently known that is safe to use without 489 library currently known that is safe to use without "unblock_sub" is
388 "unblock_sub" is EV. 490 EV.
389 491
390 This function allows your callbacks to block by executing them in 492 This function allows your callbacks to block by executing them in
391 another coroutine where it is safe to block. One example where 493 another coro where it is safe to block. One example where blocking
392 blocking is handy is when you use the Coro::AIO functions to save 494 is handy is when you use the Coro::AIO functions to save results to
393 results to disk, for example. 495 disk, for example.
394 496
395 In short: simply use "unblock_sub { ... }" instead of "sub { ... }" 497 In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
396 when creating event callbacks that want to block. 498 when creating event callbacks that want to block.
397 499
398 If your handler does not plan to block (e.g. simply sends a message 500 If your handler does not plan to block (e.g. simply sends a message
399 to another coroutine, or puts some other coroutine into the ready 501 to another coro, or puts some other coro into the ready queue),
400 queue), there is no reason to use "unblock_sub". 502 there is no reason to use "unblock_sub".
401 503
402 Note that you also need to use "unblock_sub" for any other callbacks 504 Note that you also need to use "unblock_sub" for any other callbacks
403 that are indirectly executed by any C-based event loop. For example, 505 that are indirectly executed by any C-based event loop. For example,
404 when you use a module that uses AnyEvent (and you use 506 when you use a module that uses AnyEvent (and you use
405 Coro::AnyEvent) and it provides callbacks that are the result of 507 Coro::AnyEvent) and it provides callbacks that are the result of
… …
407 "unblock_sub". 509 "unblock_sub".
408 510
409 $cb = Coro::rouse_cb 511 $cb = Coro::rouse_cb
410 Create and return a "rouse callback". That's a code reference that, 512 Create and return a "rouse callback". That's a code reference that,
411 when called, will remember a copy of its arguments and notify the 513 when called, will remember a copy of its arguments and notify the
412 owner coroutine of the callback. 514 owner coro of the callback.
413 515
414 See the next function. 516 See the next function.
415 517
416 @args = Coro::rouse_wait [$cb] 518 @args = Coro::rouse_wait [$cb]
417 Wait for the specified rouse callback (or the last one that was 519 Wait for the specified rouse callback (or the last one that was
418 created in this coroutine). 520 created in this coro).
419 521
420 As soon as the callback is invoked (or when the callback was invoked 522 As soon as the callback is invoked (or when the callback was invoked
421 before "rouse_wait"), it will return the arguments originally passed 523 before "rouse_wait"), it will return the arguments originally passed
422 to the rouse callback. 524 to the rouse callback.
423 525
424 See the section HOW TO WAIT FOR A CALLBACK for an actual usage 526 See the section HOW TO WAIT FOR A CALLBACK for an actual usage
425 example. 527 example.
426 528
427HOW TO WAIT FOR A CALLBACK 529HOW TO WAIT FOR A CALLBACK
428 It is very common for a coroutine to wait for some callback to be 530 It is very common for a coro to wait for some callback to be called.
429 called. This occurs naturally when you use coroutines in an otherwise 531 This occurs naturally when you use coro in an otherwise event-based
430 event-based program, or when you use event-based libraries. 532 program, or when you use event-based libraries.
431 533
432 These typically register a callback for some event, and call that 534 These typically register a callback for some event, and call that
433 callback when the event occured. In a coroutine, however, you typically 535 callback when the event occured. In a coro, however, you typically want
434 want to just wait for the event, simplyifying things. 536 to just wait for the event, simplyifying things.
435 537
436 For example "AnyEvent->child" registers a callback to be called when a 538 For example "AnyEvent->child" registers a callback to be called when a
437 specific child has exited: 539 specific child has exited:
438 540
439 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... }); 541 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
440 542
441 But from withina coroutine, you often just want to write this: 543 But from within a coro, you often just want to write this:
442 544
443 my $status = wait_for_child $pid; 545 my $status = wait_for_child $pid;
444 546
445 Coro offers two functions specifically designed to make this easy, 547 Coro offers two functions specifically designed to make this easy,
446 "Coro::rouse_cb" and "Coro::rouse_wait". 548 "Coro::rouse_cb" and "Coro::rouse_wait".
447 549
448 The first function, "rouse_cb", generates and returns a callback that, 550 The first function, "rouse_cb", generates and returns a callback that,
449 when invoked, will save it's arguments and notify the coroutine that 551 when invoked, will save its arguments and notify the coro that created
450 created the callback. 552 the callback.
451 553
452 The second function, "rouse_wait", waits for the callback to be called 554 The second function, "rouse_wait", waits for the callback to be called
453 (by calling "schedule" to go to sleep) and returns the arguments 555 (by calling "schedule" to go to sleep) and returns the arguments
454 originally passed to the callback. 556 originally passed to the callback.
455 557
… …
469 you can roll your own, using "schedule": 571 you can roll your own, using "schedule":
470 572
471 sub wait_for_child($) { 573 sub wait_for_child($) {
472 my ($pid) = @_; 574 my ($pid) = @_;
473 575
474 # store the current coroutine in $current, 576 # store the current coro in $current,
475 # and provide result variables for the closure passed to ->child 577 # and provide result variables for the closure passed to ->child
476 my $current = $Coro::current; 578 my $current = $Coro::current;
477 my ($done, $rstatus); 579 my ($done, $rstatus);
478 580
479 # pass a closure to ->child 581 # pass a closure to ->child
… …
490 592
491BUGS/LIMITATIONS 593BUGS/LIMITATIONS
492 fork with pthread backend 594 fork with pthread backend
493 When Coro is compiled using the pthread backend (which isn't 595 When Coro is compiled using the pthread backend (which isn't
494 recommended but required on many BSDs as their libcs are completely 596 recommended but required on many BSDs as their libcs are completely
495 broken), then coroutines will not survive a fork. There is no known 597 broken), then coro will not survive a fork. There is no known
496 workaround except to fix your libc and use a saner backend. 598 workaround except to fix your libc and use a saner backend.
497 599
498 perl process emulation ("threads") 600 perl process emulation ("threads")
499 This module is not perl-pseudo-thread-safe. You should only ever use 601 This module is not perl-pseudo-thread-safe. You should only ever use
500 this module from the first thread (this requirement might be removed 602 this module from the first thread (this requirement might be removed
501 in the future to allow per-thread schedulers, but Coro::State does 603 in the future to allow per-thread schedulers, but Coro::State does
502 not yet allow this). I recommend disabling thread support and using 604 not yet allow this). I recommend disabling thread support and using
503 processes, as having the windows process emulation enabled under 605 processes, as having the windows process emulation enabled under
504 unix roughly halves perl performance, even when not used. 606 unix roughly halves perl performance, even when not used.
505 607
506 coroutine switching not signal safe 608 coro switching is not signal safe
507 You must not switch to another coroutine from within a signal 609 You must not switch to another coro from within a signal handler
508 handler (only relevant with %SIG - most event libraries provide safe 610 (only relevant with %SIG - most event libraries provide safe
509 signals). 611 signals).
510 612
511 That means you *MUST NOT* call any function that might "block" the 613 That means you *MUST NOT* call any function that might "block" the
512 current coroutine - "cede", "schedule" "Coro::Semaphore->down" or 614 current coro - "cede", "schedule" "Coro::Semaphore->down" or
513 anything that calls those. Everything else, including calling 615 anything that calls those. Everything else, including calling
514 "ready", works. 616 "ready", works.
515 617
516SEE ALSO 618SEE ALSO
517 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. 619 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.

Diff Legend

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