… | |
… | |
35 | parallel access are rarely an issue, making coroutine programming much |
35 | parallel access are rarely an issue, making coroutine programming much |
36 | safer and easier than threads programming. |
36 | safer and easier than threads programming. |
37 | |
37 | |
38 | Unlike a normal perl program, however, coroutines allow you to have |
38 | Unlike a normal perl program, however, coroutines allow you to have |
39 | multiple running interpreters that share data, which is especially useful |
39 | multiple running interpreters that share data, which is especially useful |
40 | to code pseudo-parallel processes, such as multiple HTTP-GET requests |
40 | to code pseudo-parallel processes and for event-based programming, such as |
41 | running concurrently. |
41 | multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to |
|
|
42 | learn more. |
42 | |
43 | |
43 | Coroutines are also useful because Perl has no support for threads (the so |
44 | Coroutines are also useful because Perl has no support for threads (the so |
44 | called "threads" that perl offers are nothing more than the (bad) process |
45 | called "threads" that perl offers are nothing more than the (bad) process |
45 | emulation coming from the Windows platform: On standard operating systems |
46 | emulation coming from the Windows platform: On standard operating systems |
46 | they serve no purpose whatsoever, except by making your programs slow and |
47 | they serve no purpose whatsoever, except by making your programs slow and |
… | |
… | |
65 | |
66 | |
66 | our $idle; # idle handler |
67 | our $idle; # idle handler |
67 | our $main; # main coroutine |
68 | our $main; # main coroutine |
68 | our $current; # current coroutine |
69 | our $current; # current coroutine |
69 | |
70 | |
70 | our $VERSION = 4.6; |
71 | our $VERSION = 4.745; |
71 | |
72 | |
72 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); |
73 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); |
73 | our %EXPORT_TAGS = ( |
74 | our %EXPORT_TAGS = ( |
74 | prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], |
75 | prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], |
75 | ); |
76 | ); |
… | |
… | |
80 | =item $Coro::main |
81 | =item $Coro::main |
81 | |
82 | |
82 | This variable stores the coroutine object that represents the main |
83 | This variable stores the coroutine object that represents the main |
83 | program. While you cna C<ready> it and do most other things you can do to |
84 | program. While you cna C<ready> it and do most other things you can do to |
84 | coroutines, it is mainly useful to compare again C<$Coro::current>, to see |
85 | coroutines, it is mainly useful to compare again C<$Coro::current>, to see |
85 | wether you are running in the main program or not. |
86 | whether you are running in the main program or not. |
86 | |
87 | |
87 | =cut |
88 | =cut |
88 | |
89 | |
89 | $main = new Coro; |
90 | $main = new Coro; |
90 | |
91 | |
… | |
… | |
265 | _pool_2 $cb; |
266 | _pool_2 $cb; |
266 | &schedule; |
267 | &schedule; |
267 | } |
268 | } |
268 | }; |
269 | }; |
269 | |
270 | |
|
|
271 | if ($@) { |
270 | last if $@ eq "\3async_pool terminate\2\n"; |
272 | last if $@ eq "\3async_pool terminate\2\n"; |
271 | warn $@ if $@; |
273 | warn $@; |
|
|
274 | } |
272 | } |
275 | } |
273 | } |
276 | } |
274 | |
277 | |
275 | sub async_pool(&@) { |
278 | sub async_pool(&@) { |
276 | # this is also inlined into the unlock_scheduler |
279 | # this is also inlined into the unlock_scheduler |
… | |
… | |
306 | This makes C<schedule> I<the> generic method to use to block the current |
309 | This makes C<schedule> I<the> generic method to use to block the current |
307 | coroutine and wait for events: first you remember the current coroutine in |
310 | coroutine and wait for events: first you remember the current coroutine in |
308 | a variable, then arrange for some callback of yours to call C<< ->ready |
311 | a variable, then arrange for some callback of yours to call C<< ->ready |
309 | >> on that once some event happens, and last you call C<schedule> to put |
312 | >> on that once some event happens, and last you call C<schedule> to put |
310 | yourself to sleep. Note that a lot of things can wake your coroutine up, |
313 | yourself to sleep. Note that a lot of things can wake your coroutine up, |
311 | so you need to check wether the event indeed happened, e.g. by storing the |
314 | so you need to check whether the event indeed happened, e.g. by storing the |
312 | status in a variable. |
315 | status in a variable. |
313 | |
316 | |
314 | The canonical way to wait on external events is this: |
317 | The canonical way to wait on external events is this: |
315 | |
318 | |
316 | { |
319 | { |
… | |
… | |
355 | Kills/terminates/cancels all coroutines except the currently running |
358 | Kills/terminates/cancels all coroutines except the currently running |
356 | one. This is useful after a fork, either in the child or the parent, as |
359 | one. This is useful after a fork, either in the child or the parent, as |
357 | usually only one of them should inherit the running coroutines. |
360 | usually only one of them should inherit the running coroutines. |
358 | |
361 | |
359 | Note that while this will try to free some of the main programs resources, |
362 | Note that while this will try to free some of the main programs resources, |
360 | you cnanot free all of them, so if a coroutine that is not the main |
363 | you cannot free all of them, so if a coroutine that is not the main |
361 | program calls this function, there will be some one-time resource leak. |
364 | program calls this function, there will be some one-time resource leak. |
362 | |
365 | |
363 | =cut |
366 | =cut |
364 | |
367 | |
365 | sub terminate { |
368 | sub terminate { |
… | |
… | |
414 | once all the coroutines of higher priority and all coroutines of the same |
417 | once all the coroutines of higher priority and all coroutines of the same |
415 | priority that were put into the ready queue earlier have been resumed. |
418 | priority that were put into the ready queue earlier have been resumed. |
416 | |
419 | |
417 | =item $is_ready = $coroutine->is_ready |
420 | =item $is_ready = $coroutine->is_ready |
418 | |
421 | |
419 | Return wether the coroutine is currently the ready queue or not, |
422 | Return whether the coroutine is currently the ready queue or not, |
420 | |
423 | |
421 | =item $coroutine->cancel (arg...) |
424 | =item $coroutine->cancel (arg...) |
422 | |
425 | |
423 | Terminates the given coroutine and makes it return the given arguments as |
426 | Terminates the given coroutine and makes it return the given arguments as |
424 | status (default: the empty list). Never returns if the coroutine is the |
427 | status (default: the empty list). Never returns if the coroutine is the |
… | |
… | |
610 | creating event callbacks that want to block. |
613 | creating event callbacks that want to block. |
611 | |
614 | |
612 | If your handler does not plan to block (e.g. simply sends a message to |
615 | If your handler does not plan to block (e.g. simply sends a message to |
613 | another coroutine, or puts some other coroutine into the ready queue), |
616 | another coroutine, or puts some other coroutine into the ready queue), |
614 | there is no reason to use C<unblock_sub>. |
617 | there is no reason to use C<unblock_sub>. |
|
|
618 | |
|
|
619 | Note that you also need to use C<unblock_sub> for any other callbacks that |
|
|
620 | are indirectly executed by any C-based event loop. For example, when you |
|
|
621 | use a module that uses L<AnyEvent> (and you use L<Coro::AnyEvent>) and it |
|
|
622 | provides callbacks that are the result of some event callback, then you |
|
|
623 | must not block either, or use C<unblock_sub>. |
615 | |
624 | |
616 | =cut |
625 | =cut |
617 | |
626 | |
618 | our @unblock_queue; |
627 | our @unblock_queue; |
619 | |
628 | |