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

Comparing Coro/README (file contents):
Revision 1.20 by root, Tue Nov 25 20:48:41 2008 UTC vs.
Revision 1.22 by root, Mon Mar 16 22:22:12 2009 UTC

… …
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;
… …
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 its 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 coro switching considerably for coros that use them
244 (But coro switching is still reasonably fast if the handlers are
245 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 changes 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
221 killall 279 killall
222 Kills/terminates/cancels all coroutines except the currently running 280 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 281
226 Note that while this will try to free some of the main programs 282 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 283 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 284 free all of them, so if a coro that is not the main coro calls this
229 one-time resource leak. 285 function, there will be some one-time resource leak.
230 286
231COROUTINE OBJECT METHODS 287CORO OBJECT METHODS
232 These are the methods you can call on coroutine objects (or to create 288 These are the methods you can call on coro objects (or to create them).
233 them).
234 289
235 new Coro \&sub [, @args...] 290 new Coro \&sub [, @args...]
236 Create a new coroutine and return it. When the sub returns, the 291 Create a new coro and return it. When the sub returns, the coro
237 coroutine automatically terminates as if "terminate" with the 292 automatically terminates as if "terminate" with the returned values
238 returned values were called. To make the coroutine run you must 293 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. 294 ready queue by calling the ready method.
240 295
241 See "async" and "Coro::State::new" for additional info about the 296 See "async" and "Coro::State::new" for additional info about the
242 coroutine environment. 297 coro environment.
243 298
244 $success = $coroutine->ready 299 $success = $coro->ready
245 Put the given coroutine into the end of its ready queue (there is 300 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 301 queue for each priority) and return true. If the coro is already in
247 already in the ready queue, do nothing and return false. 302 the ready queue, do nothing and return false.
248 303
249 This ensures that the scheduler will resume this coroutine 304 This ensures that the scheduler will resume this coro automatically
250 automatically once all the coroutines of higher priority and all 305 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 306 priority that were put into the ready queue earlier have been
252 earlier have been resumed. 307 resumed.
253 308
309 $coro->suspend
310 Suspends the specified coro. A suspended coro works just like any
311 other coro, except that the scheduler will not select a suspended
312 coro for execution.
313
314 Suspending a coro can be useful when you want to keep the coro from
315 running, but you don't want to destroy it, or when you want to
316 temporarily freeze a coro (e.g. for debugging) to resume it later.
317
318 A scenario for the former would be to suspend all (other) coros
319 after a fork and keep them alive, so their destructors aren't
320 called, but new coros can be created.
321
322 $coro->resume
323 If the specified coro was suspended, it will be resumed. Note that
324 when the coro was in the ready queue when it was suspended, it might
325 have been unreadied by the scheduler, so an activation might have
326 been lost.
327
328 To avoid this, it is best to put a suspended coro into the ready
329 queue unconditionally, as every synchronisation mechanism must
330 protect itself against spurious wakeups, and the one in the Coro
331 family certainly do that.
332
254 $is_ready = $coroutine->is_ready 333 $is_ready = $coro->is_ready
255 Return whether the coroutine is currently the ready queue or not, 334 Returns true iff the Coro object is in the ready queue. Unless the
335 Coro object gets destroyed, it will eventually be scheduled by the
336 scheduler.
256 337
338 $is_running = $coro->is_running
339 Returns true iff the Coro object is currently running. Only one Coro
340 object can ever be in the running state (but it currently is
341 possible to have multiple running Coro::States).
342
343 $is_suspended = $coro->is_suspended
344 Returns true iff this Coro object has been suspended. Suspended
345 Coros will not ever be scheduled.
346
257 $coroutine->cancel (arg...) 347 $coro->cancel (arg...)
258 Terminates the given coroutine and makes it return the given 348 Terminates the given Coro and makes it return the given arguments as
259 arguments as status (default: the empty list). Never returns if the 349 status (default: the empty list). Never returns if the Coro is the
260 coroutine is the current coroutine. 350 current Coro.
261 351
262 $coroutine->schedule_to 352 $coro->schedule_to
263 Puts the current coroutine to sleep (like "Coro::schedule"), but 353 Puts the current coro to sleep (like "Coro::schedule"), but instead
264 instead of continuing with the next coro from the ready queue, 354 of continuing with the next coro from the ready queue, always switch
265 always switch to the given coroutine object (regardless of priority 355 to the given coro object (regardless of priority etc.). The
266 etc.). The readyness state of that coroutine isn't changed. 356 readyness state of that coro isn't changed.
267 357
268 This is an advanced method for special cases - I'd love to hear 358 This is an advanced method for special cases - I'd love to hear
269 about any uses for this one. 359 about any uses for this one.
270 360
271 $coroutine->cede_to 361 $coro->cede_to
272 Like "schedule_to", but puts the current coroutine into the ready 362 Like "schedule_to", but puts the current coro into the ready queue.
273 queue. This has the effect of temporarily switching to the given 363 This has the effect of temporarily switching to the given coro, and
274 coroutine, and continuing some time later. 364 continuing some time later.
275 365
276 This is an advanced method for special cases - I'd love to hear 366 This is an advanced method for special cases - I'd love to hear
277 about any uses for this one. 367 about any uses for this one.
278 368
279 $coroutine->throw ([$scalar]) 369 $coro->throw ([$scalar])
280 If $throw is specified and defined, it will be thrown as an 370 If $throw is specified and defined, it will be thrown as an
281 exception inside the coroutine at the next convenient point in time. 371 exception inside the coro at the next convenient point in time.
282 Otherwise clears the exception object. 372 Otherwise clears the exception object.
283 373
284 Coro will check for the exception each time a schedule-like-function 374 Coro will check for the exception each time a schedule-like-function
285 returns, i.e. after each "schedule", "cede", 375 returns, i.e. after each "schedule", "cede",
286 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of 376 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
… …
289 379
290 The exception object will be thrown "as is" with the specified 380 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 381 scalar in $@, i.e. if it is a string, no line number or newline will
292 be appended (unlike with "die"). 382 be appended (unlike with "die").
293 383
294 This can be used as a softer means than "cancel" to ask a coroutine 384 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 385 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 386 lead to termination, and if the exception isn't caught it might well
297 well end the whole program. 387 end the whole program.
298 388
299 You might also think of "throw" as being the moral equivalent of 389 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). 390 "kill"ing a coro with a signal (in this case, a scalar).
301 391
302 $coroutine->join 392 $coro->join
303 Wait until the coroutine terminates and return any values given to 393 Wait until the coro terminates and return any values given to the
304 the "terminate" or "cancel" functions. "join" can be called 394 "terminate" or "cancel" functions. "join" can be called concurrently
305 concurrently from multiple coroutines, and all will be resumed and 395 from multiple coro, and all will be resumed and given the status
306 given the status return once the $coroutine terminates. 396 return once the $coro terminates.
307 397
308 $coroutine->on_destroy (\&cb) 398 $coro->on_destroy (\&cb)
309 Registers a callback that is called when this coroutine gets 399 Registers a callback that is called when this coro gets destroyed,
310 destroyed, but before it is joined. The callback gets passed the 400 but before it is joined. The callback gets passed the terminate
311 terminate arguments, if any, and *must not* die, under any 401 arguments, if any, and *must not* die, under any circumstances.
312 circumstances.
313 402
314 $oldprio = $coroutine->prio ($newprio) 403 $oldprio = $coro->prio ($newprio)
315 Sets (or gets, if the argument is missing) the priority of the 404 Sets (or gets, if the argument is missing) the priority of the coro.
316 coroutine. Higher priority coroutines get run before lower priority 405 Higher priority coro get run before lower priority coro. Priorities
317 coroutines. Priorities are small signed integers (currently -4 .. 406 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 407 to using PRIO_xxx constants (use the import tag :prio to get then):
319 tag :prio to get then):
320 408
321 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 409 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
322 3 > 1 > 0 > -1 > -3 > -4 410 3 > 1 > 0 > -1 > -3 > -4
323 411
324 # set priority to HIGH 412 # set priority to HIGH
325 current->prio(PRIO_HIGH); 413 current->prio (PRIO_HIGH);
326 414
327 The idle coroutine ($Coro::idle) always has a lower priority than 415 The idle coro ($Coro::idle) always has a lower priority than any
328 any existing coroutine. 416 existing coro.
329 417
330 Changing the priority of the current coroutine will take effect 418 Changing the priority of the current coro will take effect
331 immediately, but changing the priority of coroutines in the ready 419 immediately, but changing the priority of coro in the ready queue
332 queue (but not running) will only take effect after the next 420 (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 421 that coro). This is a bug that will be fixed in some future version.
334 some future version.
335 422
336 $newprio = $coroutine->nice ($change) 423 $newprio = $coro->nice ($change)
337 Similar to "prio", but subtract the given value from the priority 424 Similar to "prio", but subtract the given value from the priority
338 (i.e. higher values mean lower priority, just as in unix). 425 (i.e. higher values mean lower priority, just as in unix).
339 426
340 $olddesc = $coroutine->desc ($newdesc) 427 $olddesc = $coro->desc ($newdesc)
341 Sets (or gets in case the argument is missing) the description for 428 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 429 this coro. This is just a free-form string you can associate with a
343 with a coroutine. 430 coro.
344 431
345 This method simply sets the "$coroutine->{desc}" member to the given 432 This method simply sets the "$coro->{desc}" member to the given
346 string. You can modify this member directly if you wish. 433 string. You can modify this member directly if you wish.
347 434
348GLOBAL FUNCTIONS 435GLOBAL FUNCTIONS
349 Coro::nready 436 Coro::nready
350 Returns the number of coroutines that are currently in the ready 437 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 438 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 439 indirectly. The value 0 means that the only runnable coro is the
353 the currently running one, so "cede" would have no effect, and 440 currently running one, so "cede" would have no effect, and
354 "schedule" would cause a deadlock unless there is an idle handler 441 "schedule" would cause a deadlock unless there is an idle handler
355 that wakes up some coroutines. 442 that wakes up some coro.
356 443
357 my $guard = Coro::guard { ... } 444 my $guard = Coro::guard { ... }
358 This creates and returns a guard object. Nothing happens until the 445 This function still exists, but is deprecated. Please use the
359 object gets destroyed, in which case the codeblock given as argument 446 "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 447
376 unblock_sub { ... } 448 unblock_sub { ... }
377 This utility function takes a BLOCK or code reference and "unblocks" 449 This utility function takes a BLOCK or code reference and "unblocks"
378 it, returning a new coderef. Unblocking means that calling the new 450 it, returning a new coderef. Unblocking means that calling the new
379 coderef will return immediately without blocking, returning nothing, 451 coderef will return immediately without blocking, returning nothing,
380 while the original code ref will be called (with parameters) from 452 while the original code ref will be called (with parameters) from
381 within another coroutine. 453 within another coro.
382 454
383 The reason this function exists is that many event libraries (such 455 The reason this function exists is that many event libraries (such
384 as the venerable Event module) are not coroutine-safe (a weaker form 456 as the venerable Event module) are not thread-safe (a weaker form of
385 of reentrancy). This means you must not block within event 457 reentrancy). This means you must not block within event callbacks,
386 callbacks, otherwise you might suffer from crashes or worse. The 458 otherwise you might suffer from crashes or worse. The only event
387 only event library currently known that is safe to use without 459 library currently known that is safe to use without "unblock_sub" is
388 "unblock_sub" is EV. 460 EV.
389 461
390 This function allows your callbacks to block by executing them in 462 This function allows your callbacks to block by executing them in
391 another coroutine where it is safe to block. One example where 463 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 464 is handy is when you use the Coro::AIO functions to save results to
393 results to disk, for example. 465 disk, for example.
394 466
395 In short: simply use "unblock_sub { ... }" instead of "sub { ... }" 467 In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
396 when creating event callbacks that want to block. 468 when creating event callbacks that want to block.
397 469
398 If your handler does not plan to block (e.g. simply sends a message 470 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 471 to another coro, or puts some other coro into the ready queue),
400 queue), there is no reason to use "unblock_sub". 472 there is no reason to use "unblock_sub".
401 473
402 Note that you also need to use "unblock_sub" for any other callbacks 474 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, 475 that are indirectly executed by any C-based event loop. For example,
404 when you use a module that uses AnyEvent (and you use 476 when you use a module that uses AnyEvent (and you use
405 Coro::AnyEvent) and it provides callbacks that are the result of 477 Coro::AnyEvent) and it provides callbacks that are the result of
… …
407 "unblock_sub". 479 "unblock_sub".
408 480
409 $cb = Coro::rouse_cb 481 $cb = Coro::rouse_cb
410 Create and return a "rouse callback". That's a code reference that, 482 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 483 when called, will remember a copy of its arguments and notify the
412 owner coroutine of the callback. 484 owner coro of the callback.
413 485
414 See the next function. 486 See the next function.
415 487
416 @args = Coro::rouse_wait [$cb] 488 @args = Coro::rouse_wait [$cb]
417 Wait for the specified rouse callback (or the last one that was 489 Wait for the specified rouse callback (or the last one that was
418 created in this coroutine). 490 created in this coro).
419 491
420 As soon as the callback is invoked (or when the callback was invoked 492 As soon as the callback is invoked (or when the callback was invoked
421 before "rouse_wait"), it will return the arguments originally passed 493 before "rouse_wait"), it will return the arguments originally passed
422 to the rouse callback. 494 to the rouse callback.
423 495
424 See the section HOW TO WAIT FOR A CALLBACK for an actual usage 496 See the section HOW TO WAIT FOR A CALLBACK for an actual usage
425 example. 497 example.
426 498
427HOW TO WAIT FOR A CALLBACK 499HOW TO WAIT FOR A CALLBACK
428 It is very common for a coroutine to wait for some callback to be 500 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 501 This occurs naturally when you use coro in an otherwise event-based
430 event-based program, or when you use event-based libraries. 502 program, or when you use event-based libraries.
431 503
432 These typically register a callback for some event, and call that 504 These typically register a callback for some event, and call that
433 callback when the event occured. In a coroutine, however, you typically 505 callback when the event occured. In a coro, however, you typically want
434 want to just wait for the event, simplyifying things. 506 to just wait for the event, simplyifying things.
435 507
436 For example "AnyEvent->child" registers a callback to be called when a 508 For example "AnyEvent->child" registers a callback to be called when a
437 specific child has exited: 509 specific child has exited:
438 510
439 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... }); 511 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
440 512
441 But from withina coroutine, you often just want to write this: 513 But from within a coro, you often just want to write this:
442 514
443 my $status = wait_for_child $pid; 515 my $status = wait_for_child $pid;
444 516
445 Coro offers two functions specifically designed to make this easy, 517 Coro offers two functions specifically designed to make this easy,
446 "Coro::rouse_cb" and "Coro::rouse_wait". 518 "Coro::rouse_cb" and "Coro::rouse_wait".
447 519
448 The first function, "rouse_cb", generates and returns a callback that, 520 The first function, "rouse_cb", generates and returns a callback that,
449 when invoked, will save its arguments and notify the coroutine that 521 when invoked, will save its arguments and notify the coro that created
450 created the callback. 522 the callback.
451 523
452 The second function, "rouse_wait", waits for the callback to be called 524 The second function, "rouse_wait", waits for the callback to be called
453 (by calling "schedule" to go to sleep) and returns the arguments 525 (by calling "schedule" to go to sleep) and returns the arguments
454 originally passed to the callback. 526 originally passed to the callback.
455 527
… …
469 you can roll your own, using "schedule": 541 you can roll your own, using "schedule":
470 542
471 sub wait_for_child($) { 543 sub wait_for_child($) {
472 my ($pid) = @_; 544 my ($pid) = @_;
473 545
474 # store the current coroutine in $current, 546 # store the current coro in $current,
475 # and provide result variables for the closure passed to ->child 547 # and provide result variables for the closure passed to ->child
476 my $current = $Coro::current; 548 my $current = $Coro::current;
477 my ($done, $rstatus); 549 my ($done, $rstatus);
478 550
479 # pass a closure to ->child 551 # pass a closure to ->child
… …
490 562
491BUGS/LIMITATIONS 563BUGS/LIMITATIONS
492 fork with pthread backend 564 fork with pthread backend
493 When Coro is compiled using the pthread backend (which isn't 565 When Coro is compiled using the pthread backend (which isn't
494 recommended but required on many BSDs as their libcs are completely 566 recommended but required on many BSDs as their libcs are completely
495 broken), then coroutines will not survive a fork. There is no known 567 broken), then coro will not survive a fork. There is no known
496 workaround except to fix your libc and use a saner backend. 568 workaround except to fix your libc and use a saner backend.
497 569
498 perl process emulation ("threads") 570 perl process emulation ("threads")
499 This module is not perl-pseudo-thread-safe. You should only ever use 571 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 572 this module from the first thread (this requirement might be removed
501 in the future to allow per-thread schedulers, but Coro::State does 573 in the future to allow per-thread schedulers, but Coro::State does
502 not yet allow this). I recommend disabling thread support and using 574 not yet allow this). I recommend disabling thread support and using
503 processes, as having the windows process emulation enabled under 575 processes, as having the windows process emulation enabled under
504 unix roughly halves perl performance, even when not used. 576 unix roughly halves perl performance, even when not used.
505 577
506 coroutine switching not signal safe 578 coro switching is not signal safe
507 You must not switch to another coroutine from within a signal 579 You must not switch to another coro from within a signal handler
508 handler (only relevant with %SIG - most event libraries provide safe 580 (only relevant with %SIG - most event libraries provide safe
509 signals). 581 signals).
510 582
511 That means you *MUST NOT* call any function that might "block" the 583 That means you *MUST NOT* call any function that might "block" the
512 current coroutine - "cede", "schedule" "Coro::Semaphore->down" or 584 current coro - "cede", "schedule" "Coro::Semaphore->down" or
513 anything that calls those. Everything else, including calling 585 anything that calls those. Everything else, including calling
514 "ready", works. 586 "ready", works.
515 587
516SEE ALSO 588SEE ALSO
517 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. 589 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.

Diff Legend

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