… | |
… | |
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 | $Coro::main (of course). |
65 | |
66 | |
66 | This variable is strictly *read-only*. You can take copies of the |
67 | This variable is strictly *read-only*. You can take copies of the |
67 | value stored in it and use it as any other coroutine object, but you |
68 | value stored in it and use it as any other coroutine object, but you |
68 | must not otherwise modify the variable itself. |
69 | must not otherwise modify the variable itself. |
69 | |
70 | |
… | |
… | |
125 | Similar to "async", but uses a coroutine pool, so you should not |
126 | Similar to "async", but uses a coroutine pool, so you should not |
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 about twice as fast as creating |
131 | destroying) a completely new coroutine, so if you need a lot of |
132 | (and destroying) a completely 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 | See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for |
186 | |
186 | callbacks. |
187 | { |
|
|
188 | # remember current coroutine |
|
|
189 | my $current = $Coro::current; |
|
|
190 | |
|
|
191 | # register a hypothetical event handler |
|
|
192 | on_event_invoke sub { |
|
|
193 | # wake up sleeping coroutine |
|
|
194 | $current->ready; |
|
|
195 | undef $current; |
|
|
196 | }; |
|
|
197 | |
|
|
198 | # call schedule until event occurred. |
|
|
199 | # in case we are woken up for other reasons |
|
|
200 | # (current still defined), loop. |
|
|
201 | Coro::schedule while $current; |
|
|
202 | } |
|
|
203 | |
187 | |
204 | cede |
188 | cede |
205 | "Cede" to other coroutines. This function puts the current coroutine |
189 | "Cede" to other coroutines. This function puts the current coroutine |
206 | into the ready queue and calls "schedule", which has the effect of |
190 | into the ready queue and calls "schedule", which has the effect of |
207 | giving up the current "timeslice" to other coroutines of the same or |
191 | giving up the current "timeslice" to other coroutines of the same or |
… | |
… | |
223 | Kills/terminates/cancels all coroutines except the currently running |
207 | Kills/terminates/cancels all coroutines except the currently running |
224 | one. This is useful after a fork, either in the child or the parent, |
208 | 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. |
209 | as usually only one of them should inherit the running coroutines. |
226 | |
210 | |
227 | Note that while this will try to free some of the main programs |
211 | 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 |
212 | 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 |
213 | not the main program calls this function, there will be some |
230 | one-time resource leak. |
214 | one-time resource leak. |
231 | |
215 | |
232 | COROUTINE METHODS |
216 | COROUTINE METHODS |
233 | These are the methods you can call on coroutine objects (or to create |
217 | These are the methods you can call on coroutine objects (or to create |
… | |
… | |
251 | automatically once all the coroutines of higher priority and all |
235 | automatically once all the coroutines of higher priority and all |
252 | coroutines of the same priority that were put into the ready queue |
236 | coroutines of the same priority that were put into the ready queue |
253 | earlier have been resumed. |
237 | earlier have been resumed. |
254 | |
238 | |
255 | $is_ready = $coroutine->is_ready |
239 | $is_ready = $coroutine->is_ready |
256 | Return wether the coroutine is currently the ready queue or not, |
240 | Return whether the coroutine is currently the ready queue or not, |
257 | |
241 | |
258 | $coroutine->cancel (arg...) |
242 | $coroutine->cancel (arg...) |
259 | Terminates the given coroutine and makes it return the given |
243 | Terminates the given coroutine and makes it return the given |
260 | arguments as status (default: the empty list). Never returns if the |
244 | arguments as status (default: the empty list). Never returns if the |
261 | coroutine is the current coroutine. |
245 | coroutine is the current coroutine. |
|
|
246 | |
|
|
247 | $coroutine->schedule_to |
|
|
248 | Puts the current coroutine to sleep (like "Coro::schedule"), but |
|
|
249 | instead of continuing with the next coro from the ready queue, |
|
|
250 | always switch to the given coroutine object (regardless of priority |
|
|
251 | etc.). The readyness state of that coroutine isn't changed. |
|
|
252 | |
|
|
253 | This is an advanced method for special cases - I'd love to hear |
|
|
254 | about any uses for this one. |
|
|
255 | |
|
|
256 | $coroutine->cede_to |
|
|
257 | Like "schedule_to", but puts the current coroutine into the ready |
|
|
258 | queue. This has the effect of temporarily switching to the given |
|
|
259 | coroutine, and continuing some time later. |
|
|
260 | |
|
|
261 | This is an advanced method for special cases - I'd love to hear |
|
|
262 | about any uses for this one. |
|
|
263 | |
|
|
264 | $coroutine->throw ([$scalar]) |
|
|
265 | If $throw is specified and defined, it will be thrown as an |
|
|
266 | exception inside the coroutine at the next convenient point in time. |
|
|
267 | Otherwise clears the exception object. |
|
|
268 | |
|
|
269 | Coro will check for the exception each time a schedule-like-function |
|
|
270 | returns, i.e. after each "schedule", "cede", |
|
|
271 | "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of |
|
|
272 | these functions detect this case and return early in case an |
|
|
273 | exception is pending. |
|
|
274 | |
|
|
275 | The exception object will be thrown "as is" with the specified |
|
|
276 | scalar in $@, i.e. if it is a string, no line number or newline will |
|
|
277 | be appended (unlike with "die"). |
|
|
278 | |
|
|
279 | This can be used as a softer means than "cancel" to ask a coroutine |
|
|
280 | to end itself, although there is no guarantee that the exception |
|
|
281 | will lead to termination, and if the exception isn't caught it might |
|
|
282 | well end the whole program. |
|
|
283 | |
|
|
284 | You might also think of "throw" as being the moral equivalent of |
|
|
285 | "kill"ing a coroutine with a signal (in this case, a scalar). |
262 | |
286 | |
263 | $coroutine->join |
287 | $coroutine->join |
264 | Wait until the coroutine terminates and return any values given to |
288 | Wait until the coroutine terminates and return any values given to |
265 | the "terminate" or "cancel" functions. "join" can be called |
289 | the "terminate" or "cancel" functions. "join" can be called |
266 | concurrently from multiple coroutines, and all will be resumed and |
290 | concurrently from multiple coroutines, and all will be resumed and |
… | |
… | |
303 | this coroutine. This is just a free-form string you can associate |
327 | this coroutine. This is just a free-form string you can associate |
304 | with a coroutine. |
328 | with a coroutine. |
305 | |
329 | |
306 | This method simply sets the "$coroutine->{desc}" member to the given |
330 | This method simply sets the "$coroutine->{desc}" member to the given |
307 | string. You can modify this member directly if you wish. |
331 | string. You can modify this member directly if you wish. |
308 | |
|
|
309 | $coroutine->throw ([$scalar]) |
|
|
310 | If $throw is specified and defined, it will be thrown as an |
|
|
311 | exception inside the coroutine at the next convinient point in time |
|
|
312 | (usually after it gains control at the next schedule/transfer/cede). |
|
|
313 | Otherwise clears the exception object. |
|
|
314 | |
|
|
315 | The exception object will be thrown "as is" with the specified |
|
|
316 | scalar in $@, i.e. if it is a string, no line number or newline will |
|
|
317 | be appended (unlike with "die"). |
|
|
318 | |
|
|
319 | This can be used as a softer means than "cancel" to ask a coroutine |
|
|
320 | to end itself, although there is no guarentee that the exception |
|
|
321 | will lead to termination, and if the exception isn't caught it might |
|
|
322 | well end the whole program. |
|
|
323 | |
332 | |
324 | GLOBAL FUNCTIONS |
333 | GLOBAL FUNCTIONS |
325 | Coro::nready |
334 | Coro::nready |
326 | Returns the number of coroutines that are currently in the ready |
335 | Returns the number of coroutines that are currently in the ready |
327 | state, i.e. that can be switched to by calling "schedule" directory |
336 | state, i.e. that can be switched to by calling "schedule" directory |
… | |
… | |
380 | when you use a module that uses AnyEvent (and you use |
389 | when you use a module that uses AnyEvent (and you use |
381 | Coro::AnyEvent) and it provides callbacks that are the result of |
390 | Coro::AnyEvent) and it provides callbacks that are the result of |
382 | some event callback, then you must not block either, or use |
391 | some event callback, then you must not block either, or use |
383 | "unblock_sub". |
392 | "unblock_sub". |
384 | |
393 | |
|
|
394 | $cb = Coro::rouse_cb |
|
|
395 | Create and return a "rouse callback". That's a code reference that, |
|
|
396 | when called, will save its arguments and notify the owner coroutine |
|
|
397 | of the callback. |
|
|
398 | |
|
|
399 | See the next function. |
|
|
400 | |
|
|
401 | @args = Coro::rouse_wait [$cb] |
|
|
402 | Wait for the specified rouse callback (or the last one tht was |
|
|
403 | created in this coroutine). |
|
|
404 | |
|
|
405 | As soon as the callback is invoked (or when the calback was invoked |
|
|
406 | before "rouse_wait"), it will return a copy of the arguments |
|
|
407 | originally passed to the rouse callback. |
|
|
408 | |
|
|
409 | See the section HOW TO WAIT FOR A CALLBACK for an actual usage |
|
|
410 | example. |
|
|
411 | |
|
|
412 | HOW TO WAIT FOR A CALLBACK |
|
|
413 | It is very common for a coroutine to wait for some callback to be |
|
|
414 | called. This occurs naturally when you use coroutines in an otherwise |
|
|
415 | event-based program, or when you use event-based libraries. |
|
|
416 | |
|
|
417 | These typically register a callback for some event, and call that |
|
|
418 | callback when the event occured. In a coroutine, however, you typically |
|
|
419 | want to just wait for the event, simplyifying things. |
|
|
420 | |
|
|
421 | For example "AnyEvent->child" registers a callback to be called when a |
|
|
422 | specific child has exited: |
|
|
423 | |
|
|
424 | my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... }); |
|
|
425 | |
|
|
426 | But from withina coroutine, you often just want to write this: |
|
|
427 | |
|
|
428 | my $status = wait_for_child $pid; |
|
|
429 | |
|
|
430 | Coro offers two functions specifically designed to make this easy, |
|
|
431 | "Coro::rouse_cb" and "Coro::rouse_wait". |
|
|
432 | |
|
|
433 | The first function, "rouse_cb", generates and returns a callback that, |
|
|
434 | when invoked, will save it's arguments and notify the coroutine that |
|
|
435 | created the callback. |
|
|
436 | |
|
|
437 | The second function, "rouse_wait", waits for the callback to be called |
|
|
438 | (by calling "schedule" to go to sleep) and returns the arguments |
|
|
439 | originally passed to the callback. |
|
|
440 | |
|
|
441 | Using these functions, it becomes easy to write the "wait_for_child" |
|
|
442 | function mentioned above: |
|
|
443 | |
|
|
444 | sub wait_for_child($) { |
|
|
445 | my ($pid) = @_; |
|
|
446 | |
|
|
447 | my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb); |
|
|
448 | |
|
|
449 | my ($rpid, $rstatus) = Coro::rouse_wait; |
|
|
450 | $rstatus |
|
|
451 | } |
|
|
452 | |
|
|
453 | In the case where "rouse_cb" and "rouse_wait" are not flexible enough, |
|
|
454 | you can roll your own, using "schedule": |
|
|
455 | |
|
|
456 | sub wait_for_child($) { |
|
|
457 | my ($pid) = @_; |
|
|
458 | |
|
|
459 | # store the current coroutine in $current, |
|
|
460 | # and provide result variables for the closure passed to ->child |
|
|
461 | my $current = $Coro::current; |
|
|
462 | my ($done, $rstatus); |
|
|
463 | |
|
|
464 | # pass a closure to ->child |
|
|
465 | my $watcher = AnyEvent->child (pid => $pid, cb => sub { |
|
|
466 | $rstatus = $_[1]; # remember rstatus |
|
|
467 | $done = 1; # mark $rstatus as valud |
|
|
468 | }); |
|
|
469 | |
|
|
470 | # wait until the closure has been called |
|
|
471 | schedule while !$done; |
|
|
472 | |
|
|
473 | $rstatus |
|
|
474 | } |
|
|
475 | |
385 | BUGS/LIMITATIONS |
476 | BUGS/LIMITATIONS |
|
|
477 | fork with pthread backend |
|
|
478 | When Coro is compiled using the pthread backend (which isn't |
|
|
479 | recommended but required on many BSDs as their libcs are completely |
|
|
480 | broken), then coroutines will not survive a fork. There is no known |
|
|
481 | workaround except to fix your libc and use a saner backend. |
|
|
482 | |
|
|
483 | perl process emulation ("threads") |
386 | This module is not perl-pseudo-thread-safe. You should only ever use |
484 | This module is not perl-pseudo-thread-safe. You should only ever use |
387 | this module from the same thread (this requirement might be removed in |
485 | this module from the same thread (this requirement might be removed |
388 | the future to allow per-thread schedulers, but Coro::State does not yet |
486 | in the future to allow per-thread schedulers, but Coro::State does |
389 | allow this). I recommend disabling thread support and using processes, |
487 | not yet allow this). I recommend disabling thread support and using |
390 | as this is much faster and uses less memory. |
488 | processes, as having the windows process emulation enabled under |
|
|
489 | unix roughly halves perl performance, even when not used. |
|
|
490 | |
|
|
491 | coroutine switching not signal safe |
|
|
492 | You must not switch to another coroutine from within a signal |
|
|
493 | handler (only relevant with %SIG - most event libraries provide safe |
|
|
494 | signals). |
|
|
495 | |
|
|
496 | That means you *MUST NOT* call any function that might "block" the |
|
|
497 | current coroutine - "cede", "schedule" "Coro::Semaphore->down" or |
|
|
498 | anything that calls those. Everything else, including calling |
|
|
499 | "ready", works. |
391 | |
500 | |
392 | SEE ALSO |
501 | SEE ALSO |
393 | Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. |
502 | Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. |
394 | |
503 | |
395 | Debugging: Coro::Debug. |
504 | Debugging: Coro::Debug. |