| … | |
… | |
| 5 | =head1 SYNOPSIS |
5 | =head1 SYNOPSIS |
| 6 | |
6 | |
| 7 | use Coro; |
7 | use Coro; |
| 8 | use Coro::AnyEvent; |
8 | use Coro::AnyEvent; |
| 9 | |
9 | |
| 10 | # use coro within an Anyevent environment |
10 | # use coro within an AnyEvent environment |
|
|
11 | |
|
|
12 | =head1 INTRODUCTION |
|
|
13 | |
|
|
14 | When one naively starts to use coroutines in Perl, one will quickly run |
|
|
15 | into the problem that coroutines that block on a syscall (sleeping, |
|
|
16 | reading from a socket etc.) will block all coroutines. |
|
|
17 | |
|
|
18 | If one then uses an event loop, the problem is that the event loop has |
|
|
19 | no knowledge of coroutines and will not run them before it polls for new |
|
|
20 | events, again blocking the whole process. |
|
|
21 | |
|
|
22 | This module integrates coroutines into any event loop supported by |
|
|
23 | AnyEvent, combining event-based programming with coroutine-based |
|
|
24 | programming in a natural way. |
|
|
25 | |
|
|
26 | All you have to do is C<use Coro::AnyEvent> and then you can run a |
|
|
27 | coroutines freely. |
| 11 | |
28 | |
| 12 | =head1 DESCRIPTION |
29 | =head1 DESCRIPTION |
| 13 | |
30 | |
| 14 | TODO: |
31 | This module autodetects the event loop used (by relying on L<AnyEvent>) |
|
|
32 | and will either automatically defer to the high-performance L<Coro::EV> or |
|
|
33 | L<Coro::Event> modules, or will use a generic integration into any event |
|
|
34 | loop supported by L<AnyEvent>. |
| 15 | |
35 | |
| 16 | This module does two things: First, it offers some utility functions that |
36 | Unfortunately, few event loops (basically only L<EV> and L<Event>) support |
| 17 | might be useful for coroutines, and secondly, it integrates Coro into the |
37 | this kind of integration well, and therefore AnyEvent cannot offer the |
| 18 | EV main loop: |
38 | required functionality. |
| 19 | |
39 | |
| 20 | Before the process blocks (in EV::loop) to wait for events, this module |
40 | Here is what this module does when it has to work with other event loops: |
| 21 | will schedule and run all ready (= runnable) coroutines of the same or |
|
|
| 22 | higher priority. After that, it will cede once to a coroutine of lower |
|
|
| 23 | priority, then continue in the event loop. |
|
|
| 24 | |
41 | |
| 25 | That means that coroutines with the same or higher pripority as the |
42 | Each time a coroutine is put into the ready queue (and there are no other |
| 26 | coroutine running the main loop will inhibit event processing, while |
43 | coroutines in the ready queue), a timer with an C<after> value of C<0> is |
| 27 | coroutines of lower priority will get the CPU, but cannot completeley |
44 | registered with AnyEvent. |
| 28 | inhibit event processing. |
45 | |
|
|
46 | This creates something similar to an I<idle> watcher, i.e. a watcher |
|
|
47 | that keeps the event loop from blocking but still polls for new |
|
|
48 | events. (Unfortunately, some badly designed event loops (e.g. Event::Lib) |
|
|
49 | don't support a timeout of C<0> and will always block for a bit). |
|
|
50 | |
|
|
51 | The callback for that timer will C<cede> to other coroutines of the same |
|
|
52 | or higher priority for as long as such coroutines exists. This has the |
|
|
53 | effect of running all coroutines that have work to do will all coroutines |
|
|
54 | block to wait for external events. |
|
|
55 | |
|
|
56 | If no coroutines of equal or higher priority are ready, it will cede |
|
|
57 | to any coroutine, but only once. This has the effect of running |
|
|
58 | lower-priority coroutines as well, but it will not keep higher priority |
|
|
59 | coroutines from receiving new events. |
|
|
60 | |
|
|
61 | The priority used is simply the priority of the coroutine that runs the |
|
|
62 | event loop, usually the main program, and the priority is usually C<0>. |
|
|
63 | |
|
|
64 | As C<unblock_sub> cannot be used, you must not call into the event loop |
|
|
65 | recursively (e.g. you must not use AnyEvent condvars in a blocking |
|
|
66 | way). This restriction will be lifted in a later version of AnyEvent and |
|
|
67 | Coro. |
|
|
68 | |
|
|
69 | In addition to hooking into C<ready>, this module will also provide a |
|
|
70 | C<$Coro::idle> handler that runs the event loop. It is best not to rely on |
|
|
71 | this. |
| 29 | |
72 | |
| 30 | =cut |
73 | =cut |
| 31 | |
74 | |
| 32 | package Coro::AnyEvent; |
75 | package Coro::AnyEvent; |
| 33 | |
76 | |
