File Coverage

blib/lib/Coro/AnyEvent.pm
Criterion Covered Total %
statement 10 38 26.3
branch 0 2 0.0
condition 2 9 22.2
subroutine 4 16 25.0
pod 6 6 100.0
total 22 71 30.9


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Coro::AnyEvent - integrate threads into AnyEvent
4              
5             =head1 SYNOPSIS
6              
7             use Coro;
8             use AnyEvent;
9             # using both Coro and AnyEvent will automatically load Coro::AnyEvent
10              
11             # or load it manually for its utility functions:
12             use Coro::AnyEvent;
13              
14             Coro::AnyEvent::sleep 5; # block current thread for 5s
15             Coro::AnyEvent::poll; # poll for new events once
16             Coro::AnyEvent::idle; # block until process no longer busy
17             Coro::AnyEvent::idle_upto 5; # same, but only up to 5 seconds
18              
19             Coro::AnyEvent::readable $fh, 60
20             or die "fh didn't become readable within 60 seconds\n";
21              
22             =head1 DESCRIPTION
23              
24             When one naively starts to use threads in Perl, one will quickly run
25             into the problem that threads which block on a syscall (sleeping,
26             reading from a socket etc.) will block all threads.
27              
28             If one then uses an event loop, the problem is that the event loop has
29             no knowledge of threads and will not run them before it polls for new
30             events, again blocking the whole process.
31              
32             This module integrates threads into any event loop supported by
33             AnyEvent, combining event-based programming with coroutine-based
34             programming in a natural way.
35              
36             As of Coro 5.21 and newer, this module gets loaded automatically when
37             AnyEvent initialises itself and Coro is used in the same process, thus
38             there is no need to load it manually if you just want your threads to
39             coexist with AnyEvent.
40              
41             If you want to use any functions from this module, you of course still
42             need to C, just as with other perl modules.
43              
44             Also, this module autodetects the event loop used (by relying on
45             L) and will either automatically defer to the high-performance
46             L or L modules, or will use a generic integration
47             method that should work with any event loop supported by L.
48              
49             =head1 USAGE
50              
51             =head2 RUN AN EVENT LOOP - OR NOT?
52              
53             For performance reasons, it is recommended that the main program or
54             something else run the event loop of the event model you use, i.e.
55              
56             use Gtk2; # <- the event model
57             use AnyEvent;
58             use Coro:
59              
60             # initialise stuff
61             async { ... };
62              
63             # now run mainloop of Gtk2
64             main Gtk2;
65              
66             You can move the event loop into a thread as well, although this tends to
67             get confusing:
68              
69             use Gtk2;
70             use AnyEvent;
71             use Coro:
72              
73             async { main Gtk2 };
74              
75             # do other things...
76             while () {
77             use Coro::AnyEvent;
78             Coro::AnyEvent::sleep 1;
79             print "ping...\n";
80             }
81              
82             You can also do nothing, in which case Coro::AnyEvent will invoke the event
83             loop as needed, which is less efficient, but sometimes very convenient.
84              
85             What you I is to block inside an event loop
86             callback. The reason is that most event loops are not reentrant and
87             this can cause a deadlock at best and corrupt memory at worst.
88              
89             Coro will try to catch you when you block in the event loop
90             ("FATAL: $Coro::IDLE blocked itself"), but this is just best effort and
91             only works when you do not run your own event loop.
92              
93             To avoid this problem, start a new thread (e.g. with C)
94             or use C to run blocking tasks.
95              
96             =head2 INVERSION OF CONTROL
97              
98             If you need to wait for a single event, the rouse functions will come in
99             handy (see the Coro manpage for details):
100              
101             # wait for single SIGINT
102             {
103             my $int_w = AnyEvent->signal (signal => "INT", cb => Coro::rouse_cb);
104             Coro::rouse_wait;
105             }
106              
107             =head2 EVENT MODULES OTHER THAN ANYEVENT
108              
109             Keep in mind that, as shipped, Coro and Coro::AnyEvent only work with
110             AnyEvent, and only when AnyEvent is actually used (i.e. initialised), so
111             this will not work:
112              
113             # does not work: EV without AnyEvent is not recognised
114             use EV;
115             use Coro;
116              
117             EV::loop;
118              
119             And neither does this, unless you actually I AnyEvent for something:
120              
121             # does not work: AnyEvent must be initialised (e.g. by creating watchers)
122             use EV;
123             use AnyEvent;
124             use Coro;
125              
126             EV::loop;
127              
128             This does work, however, because you create a watcher (condvars work,
129             too), thus forcing AnyEvent to initialise itself:
130              
131             # does work: AnyEvent is actually used
132             use EV;
133             use AnyEvent;
134             use Coro;
135              
136             my $timer = AE::timer 1, 1, sub { };
137              
138             EV::loop;
139              
140             And if you want to use AnyEvent just to bridge between Coro and your event
141             model of choice, you can simply force it to initialise itself, like this:
142              
143             # does work: AnyEvent is initialised manually
144             use POE;
145             use AnyEvent;
146             use Coro;
147              
148             AnyEvent::detect; # force AnyEvent to integrate Coro into POE
149             POE::Kernel->run;
150              
151             =head1 FUNCTIONS
152              
153             Coro::AnyEvent also offers a few functions that might be useful.
154              
155             =over 4
156              
157             =cut
158              
159             package Coro::AnyEvent;
160              
161 2     2   426 use common::sense;
  2         4  
  2         9  
162              
163 2     2   82 use Coro;
  2         2  
  2         111  
164 2     2   695 use AnyEvent ();
  2         4049  
  2         1609  
165              
166             our $VERSION = 6.514;
167              
168             #############################################################################
169             # idle handler
170              
171             our $IDLE;
172              
173             #############################################################################
174             # 0-timeout idle emulation watcher
175              
176             our $ACTIVITY;
177              
178             sub _activity {
179 12   66 12   82 $ACTIVITY ||= AE::timer 0, 0, \&_schedule;
180             }
181              
182             Coro::_set_readyhook (\&AnyEvent::detect);
183              
184             AnyEvent::post_detect {
185             my $model = $AnyEvent::MODEL;
186              
187             if ($model eq "AnyEvent::Impl::EV" and eval { require Coro::EV }) {
188             # provide faster versions of some functions
189             Coro::EV::_set_readyhook ();
190              
191             eval '
192             *sleep = \&Coro::EV::timer_once;
193             *poll = \&Coro::EV::_poll;
194             *idle = sub() {
195             my $w = EV::idle Coro::rouse_cb;
196             Coro::rouse_wait;
197             };
198             *idle_upto = sub($) {
199             my $cb = Coro::rouse_cb;
200             my $t = EV::timer $_[0], 0, $cb;
201             my $w = EV::idle $cb;
202             Coro::rouse_wait;
203             };
204             *readable = sub($;$) {
205             EV::READ & Coro::EV::timed_io_once $_[0], EV::READ , $_[1]
206             };
207             *writable = sub($;$) {
208             EV::WRITE & Coro::EV::timed_io_once $_[0], EV::WRITE, $_[1]
209             };
210             ';
211             die if $@;
212              
213             } elsif ($model eq "AnyEvent::Impl::Event" and eval { require Coro::Event }) {
214             Coro::_set_readyhook undef;
215             # let Coro::Event do its thing
216             } else {
217             # do the inefficient thing ourselves
218             Coro::_set_readyhook \&_activity;
219              
220             $IDLE = new Coro sub {
221             my $_poll = AnyEvent->can ("_poll")
222             || AnyEvent->can ("one_event"); # AnyEvent < 6.0
223              
224             while () {
225             $_poll->();
226             Coro::schedule if Coro::nready;
227             }
228             };
229             $IDLE->{desc} = "[AnyEvent idle process]";
230              
231             $Coro::idle = $IDLE;
232              
233             # call the readyhook, in case coroutines were already readied
234             _activity;
235             }
236              
237             # augment condvars
238             unshift @AnyEvent::CondVar::ISA, "Coro::AnyEvent::CondVar";
239             };
240              
241             =item Coro::AnyEvent::poll
242              
243             This call will block the current thread until the event loop has polled
244             for potential new events and instructs the event loop to poll for new
245             events once, without blocking.
246              
247             Note that this call will not actually execute the poll, nor will it wait
248             until there are some events, just block until the event loop has polled
249             for new events, so other threads will have a chance to run.
250              
251             This is useful when you have a thread that does some computations, but you
252             still want to poll for new events from time to time. Simply call C
253             from time to time:
254              
255             my $long_calc = async {
256             for (1..10000) {
257             Coro::AnyEvent::poll;
258             # do some stuff, make sure it takes at least 0.001s or so
259             }
260             }
261              
262             Although you should also consider C or C in such cases.
263              
264             =item Coro::AnyEvent::sleep $seconds
265              
266             This blocks the current thread for at least the given number of seconds.
267              
268             =item Coro::AnyEvent::idle
269              
270             This call is similar to C in that it will also poll for
271             events. Unlike C, it will only resume the thread once there are no
272             events to handle anymore, i.e. when the process is otherwise idle.
273              
274             This is good for background threads that shouldn't use CPU time when
275             foreground jobs are ready to run.
276              
277             =item Coro::AnyEvent::idle_upto $seconds
278              
279             Like C, but with a maximum waiting time.
280              
281             If your process is busy handling events, calling C can mean that
282             your thread will never be resumed. To avoid this, you can use C
283             and specify a timeout, after which your thread will be resumed even if the
284             process is completely busy.
285              
286             =item Coro::AnyEvent::readable $fh_or_fileno[, $timeout]
287              
288             =item Coro::AnyEvent::writable $fh_or_fileno[, $timeout]
289              
290             Blocks the current thread until the given file handle (or file descriptor)
291             becomes readable (or writable), or the given timeout has elapsed,
292             whichever happens first. No timeout counts as infinite timeout.
293              
294             Returns true when the file handle became ready, false when a timeout
295             occurred.
296              
297             Note that these functions are quite inefficient as compared to using a
298             single watcher (they recreate watchers on every invocation) or compared to
299             using Coro::Handle.
300              
301             Note also that they only work for sources that have reasonable
302             non-blocking behaviour (e.g. not files).
303              
304             Example: wait until STDIN becomes readable, then quit the program.
305              
306             use Coro::AnyEvent;
307             print "press enter to quit...\n";
308             Coro::AnyEvent::readable *STDIN;
309             exit 0;
310              
311             =cut
312              
313             sub poll() {
314 0     0 1   my $w = AE::timer 0, 0, Coro::rouse_cb;
315 0           Coro::rouse_wait;
316             }
317              
318             sub sleep($) {
319 0     0 1   my $w = AE::timer $_[0], 0, Coro::rouse_cb;
320 0           Coro::rouse_wait;
321             }
322              
323             sub idle() {
324 0     0 1   my $w = AE::idle Coro::rouse_cb;
325 0           Coro::rouse_wait;
326             }
327              
328             sub idle_upto($) {
329 0     0 1   my $cb = Coro::rouse_cb;
330 0           my $t = AE::timer shift, 0, $cb;
331 0           my $w = AE::idle $cb;
332 0           Coro::rouse_wait;
333             }
334              
335             sub readable($;$) {
336 0     0 1   my $cb = Coro::rouse_cb;
337 0     0     my $w = AE::io $_[0], 0, sub { $cb->(1) };
  0            
338 0   0 0     my $t = defined $_[1] && AE::timer $_[1], 0, sub { $cb->(0) };
  0            
339 0           Coro::rouse_wait
340             }
341              
342             sub writable($;$) {
343 0     0 1   my $cb = Coro::rouse_cb;
344 0     0     my $w = AE::io $_[0], 1, sub { $cb->(1) };
  0            
345 0   0 0     my $t = defined $_[1] && AE::timer $_[1], 0, sub { $cb->(0) };
  0            
346 0           Coro::rouse_wait
347             }
348              
349             sub Coro::AnyEvent::CondVar::send {
350 0 0   0     (delete $_[0]{_ae_coro})->ready if $_[0]{_ae_coro};
351              
352 0           &AnyEvent::CondVar::Base::send;
353             };
354              
355             sub Coro::AnyEvent::CondVar::recv {
356 0     0     until ($_[0]{_ae_sent}) {
357 0           local $_[0]{_ae_coro} = $Coro::current;
358 0           Coro::schedule;
359             }
360              
361 0           &AnyEvent::CondVar::Base::recv;
362             };
363              
364             1;
365              
366             =back
367              
368             =head1 IMPLEMENTATION DETAILS
369              
370             Unfortunately, few event loops (basically only L and L)
371             support the kind of integration required for smooth operations well, and
372             consequently, AnyEvent cannot completely offer the functionality required
373             by this module, so we need to improvise.
374              
375             Here is what this module does when it has to work with other event loops:
376              
377             =over 4
378              
379             =item * run ready threads before blocking the process
380              
381             Each time a thread is put into the ready queue (and there are no other
382             threads in the ready queue), a timer with an C value of C<0> is
383             registered with AnyEvent.
384              
385             This creates something similar to an I watcher, i.e. a watcher
386             that keeps the event loop from blocking but still polls for new
387             events. (Unfortunately, some badly designed event loops (e.g. Event::Lib)
388             don't support a timeout of C<0> and will always block for a bit).
389              
390             The callback for that timer will C to other threads of the same or
391             higher priority for as long as such threads exists. This has the effect of
392             running all threads that have work to do until all threads block to wait
393             for external events.
394              
395             If no threads of equal or higher priority are ready, it will cede to any
396             thread, but only once. This has the effect of running lower-priority
397             threads as well, but it will not keep higher priority threads from
398             receiving new events.
399              
400             The priority used is simply the priority of the thread that runs the event
401             loop, usually the main program, which usually has a priority of C<0>. Note
402             that Coro::AnyEvent does I run an event loop for you, so unless the
403             main program runs one, there will simply be no event loop to C to
404             (event handling will still work, somewhat inefficiently, but any thread
405             will have a higher priority than event handling in that case).
406              
407             =item * provide a suitable idle callback.
408              
409             In addition to hooking into C, this module will also provide a
410             C<$Coro::idle> handler that runs the event loop. It is best not to take
411             advantage of this too often, as this is rather inefficient, but it should
412             work perfectly fine.
413              
414             =item * provide overrides for AnyEvent's condvars
415              
416             This module installs overrides for AnyEvent's condvars. That is, when
417             the module is loaded it will provide its own condition variables. This
418             makes them coroutine-safe, i.e. you can safely block on them from within a
419             coroutine.
420              
421             =item * lead to data corruption or worse
422              
423             As C cannot be used by this module (as it is the module
424             that implements it, basically), you must not call into the event
425             loop recursively from any coroutine. This is not usually a difficult
426             restriction to live with, just use condvars, C or other means
427             of inter-coroutine-communications.
428              
429             If you use a module that supports AnyEvent (or uses the same event
430             loop as AnyEvent, making it implicitly compatible), and it offers
431             callbacks of any kind, then you must not block in them, either (or use
432             e.g. C), see the description of C in the
433             L module.
434              
435             This also means that you should load the module as early as possible,
436             as only condvars created after this module has been loaded will work
437             correctly.
438              
439             =back
440              
441             =head1 SEE ALSO
442              
443             L, to see which event loops are supported, L and
444             L for more efficient and more correct solutions (they will be
445             used automatically if applicable).
446              
447             =head1 AUTHOR/SUPPORT/CONTACT
448              
449             Marc A. Lehmann
450             http://software.schmorp.de/pkg/Coro.html
451              
452             =cut
453