ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
Revision: 1.365
Committed: Tue Aug 16 14:47:26 2011 UTC (12 years, 10 months ago) by root
Branch: MAIN
Changes since 1.364: +42 -17 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.150 =head1 NAME
2 root 1.1
3 root 1.256 AnyEvent - the DBI of event loop programming
4 root 1.2
5 root 1.258 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt
6     and POE are various supported event loops/environments.
7 root 1.1
8     =head1 SYNOPSIS
9    
10 root 1.7 use AnyEvent;
11 root 1.2
12 root 1.322 # if you prefer function calls, look at the AE manpage for
13 root 1.318 # an alternative API.
14    
15     # file handle or descriptor readable
16 root 1.207 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
17 root 1.173
18 root 1.207 # one-shot or repeating timers
19 root 1.173 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
20 root 1.330 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...);
21 root 1.173
22     print AnyEvent->now; # prints current event loop time
23     print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
24    
25 root 1.207 # POSIX signal
26 root 1.173 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
27 root 1.5
28 root 1.207 # child process exit
29 root 1.173 my $w = AnyEvent->child (pid => $pid, cb => sub {
30     my ($pid, $status) = @_;
31 root 1.2 ...
32     });
33    
34 root 1.207 # called when event loop idle (if applicable)
35     my $w = AnyEvent->idle (cb => sub { ... });
36    
37 root 1.52 my $w = AnyEvent->condvar; # stores whether a condition was flagged
38 root 1.114 $w->send; # wake up current and all future recv's
39     $w->recv; # enters "main loop" till $condvar gets ->send
40 root 1.173 # use a condvar in callback mode:
41     $w->cb (sub { $_[0]->recv });
42 root 1.5
43 root 1.148 =head1 INTRODUCTION/TUTORIAL
44    
45     This manpage is mainly a reference manual. If you are interested
46     in a tutorial or some gentle introduction, have a look at the
47     L<AnyEvent::Intro> manpage.
48    
49 root 1.249 =head1 SUPPORT
50    
51 root 1.334 An FAQ document is available as L<AnyEvent::FAQ>.
52    
53     There also is a mailinglist for discussing all things AnyEvent, and an IRC
54 root 1.249 channel, too.
55    
56     See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
57 root 1.255 Repository>, at L<http://anyevent.schmorp.de>, for more info.
58 root 1.249
59 root 1.43 =head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
60 root 1.41
61     Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
62     nowadays. So what is different about AnyEvent?
63    
64     Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
65     policy> and AnyEvent is I<small and efficient>.
66    
67     First and foremost, I<AnyEvent is not an event model> itself, it only
68 root 1.168 interfaces to whatever event model the main program happens to use, in a
69 root 1.41 pragmatic way. For event models and certain classes of immortals alike,
70 root 1.53 the statement "there can only be one" is a bitter reality: In general,
71     only one event loop can be active at the same time in a process. AnyEvent
72 root 1.168 cannot change this, but it can hide the differences between those event
73     loops.
74 root 1.41
75     The goal of AnyEvent is to offer module authors the ability to do event
76     programming (waiting for I/O or timer events) without subscribing to a
77     religion, a way of living, and most importantly: without forcing your
78     module users into the same thing by forcing them to use the same event
79     model you use.
80    
81 root 1.53 For modules like POE or IO::Async (which is a total misnomer as it is
82     actually doing all I/O I<synchronously>...), using them in your module is
83 root 1.330 like joining a cult: After you join, you are dependent on them and you
84 root 1.168 cannot use anything else, as they are simply incompatible to everything
85     that isn't them. What's worse, all the potential users of your
86     module are I<also> forced to use the same event loop you use.
87 root 1.53
88     AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
89     fine. AnyEvent + Tk works fine etc. etc. but none of these work together
90 root 1.343 with the rest: POE + EV? No go. Tk + Event? No go. Again: if your module
91     uses one of those, every user of your module has to use it, too. But if
92     your module uses AnyEvent, it works transparently with all event models it
93     supports (including stuff like IO::Async, as long as those use one of the
94     supported event loops. It is easy to add new event loops to AnyEvent, too,
95     so it is future-proof).
96 root 1.41
97 root 1.53 In addition to being free of having to use I<the one and only true event
98 root 1.41 model>, AnyEvent also is free of bloat and policy: with POE or similar
99 root 1.128 modules, you get an enormous amount of code and strict rules you have to
100 root 1.330 follow. AnyEvent, on the other hand, is lean and to the point, by only
101 root 1.53 offering the functionality that is necessary, in as thin as a wrapper as
102 root 1.41 technically possible.
103    
104 root 1.142 Of course, AnyEvent comes with a big (and fully optional!) toolbox
105     of useful functionality, such as an asynchronous DNS resolver, 100%
106     non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
107     such as Windows) and lots of real-world knowledge and workarounds for
108     platform bugs and differences.
109    
110     Now, if you I<do want> lots of policy (this can arguably be somewhat
111 root 1.46 useful) and you want to force your users to use the one and only event
112     model, you should I<not> use this module.
113 root 1.43
114 root 1.1 =head1 DESCRIPTION
115    
116 root 1.330 L<AnyEvent> provides a uniform interface to various event loops. This
117     allows module authors to use event loop functionality without forcing
118     module users to use a specific event loop implementation (since more
119     than one event loop cannot coexist peacefully).
120 root 1.2
121 root 1.53 The interface itself is vaguely similar, but not identical to the L<Event>
122 root 1.2 module.
123    
124 root 1.53 During the first call of any watcher-creation method, the module tries
125 root 1.61 to detect the currently loaded event loop by probing whether one of the
126 root 1.352 following modules is already loaded: L<EV>, L<AnyEvent::Loop>,
127 root 1.331 L<Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. The first one
128     found is used. If none are detected, the module tries to load the first
129     four modules in the order given; but note that if L<EV> is not
130 root 1.352 available, the pure-perl L<AnyEvent::Loop> should always work, so
131 root 1.331 the other two are not normally tried.
132 root 1.14
133     Because AnyEvent first checks for modules that are already loaded, loading
134 root 1.53 an event model explicitly before first using AnyEvent will likely make
135 root 1.14 that model the default. For example:
136    
137     use Tk;
138     use AnyEvent;
139    
140     # .. AnyEvent will likely default to Tk
141    
142 root 1.53 The I<likely> means that, if any module loads another event model and
143 root 1.329 starts using it, all bets are off - this case should be very rare though,
144     as very few modules hardcode event loops without announcing this very
145     loudly.
146 root 1.53
147 root 1.352 The pure-perl implementation of AnyEvent is called C<AnyEvent::Loop>. Like
148     other event modules you can load it explicitly and enjoy the high
149     availability of that event loop :)
150 root 1.14
151     =head1 WATCHERS
152    
153     AnyEvent has the central concept of a I<watcher>, which is an object that
154     stores relevant data for each kind of event you are waiting for, such as
155 root 1.128 the callback to call, the file handle to watch, etc.
156 root 1.14
157     These watchers are normal Perl objects with normal Perl lifetime. After
158 root 1.53 creating a watcher it will immediately "watch" for events and invoke the
159     callback when the event occurs (of course, only when the event model
160     is in control).
161    
162 root 1.196 Note that B<callbacks must not permanently change global variables>
163     potentially in use by the event loop (such as C<$_> or C<$[>) and that B<<
164 root 1.330 callbacks must not C<die> >>. The former is good programming practice in
165 root 1.196 Perl and the latter stems from the fact that exception handling differs
166     widely between event loops.
167    
168 root 1.330 To disable a watcher you have to destroy it (e.g. by setting the
169 root 1.53 variable you store it in to C<undef> or otherwise deleting all references
170     to it).
171 root 1.14
172     All watchers are created by calling a method on the C<AnyEvent> class.
173    
174 root 1.53 Many watchers either are used with "recursion" (repeating timers for
175     example), or need to refer to their watcher object in other ways.
176    
177 root 1.330 One way to achieve that is this pattern:
178 root 1.53
179 root 1.151 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
180     # you can use $w here, for example to undef it
181     undef $w;
182     });
183 root 1.53
184     Note that C<my $w; $w => combination. This is necessary because in Perl,
185     my variables are only visible after the statement in which they are
186     declared.
187    
188 root 1.78 =head2 I/O WATCHERS
189 root 1.14
190 root 1.266 $w = AnyEvent->io (
191     fh => <filehandle_or_fileno>,
192     poll => <"r" or "w">,
193     cb => <callback>,
194     );
195    
196 root 1.53 You can create an I/O watcher by calling the C<< AnyEvent->io >> method
197     with the following mandatory key-value pairs as arguments:
198 root 1.14
199 root 1.229 C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
200     for events (AnyEvent might or might not keep a reference to this file
201     handle). Note that only file handles pointing to things for which
202 root 1.199 non-blocking operation makes sense are allowed. This includes sockets,
203     most character devices, pipes, fifos and so on, but not for example files
204     or block devices.
205    
206     C<poll> must be a string that is either C<r> or C<w>, which creates a
207     watcher waiting for "r"eadable or "w"ritable events, respectively.
208    
209     C<cb> is the callback to invoke each time the file handle becomes ready.
210 root 1.53
211 root 1.85 Although the callback might get passed parameters, their value and
212     presence is undefined and you cannot rely on them. Portable AnyEvent
213     callbacks cannot use arguments passed to I/O watcher callbacks.
214    
215 root 1.82 The I/O watcher might use the underlying file descriptor or a copy of it.
216 root 1.84 You must not close a file handle as long as any watcher is active on the
217     underlying file descriptor.
218 root 1.53
219 root 1.330 Some event loops issue spurious readiness notifications, so you should
220 root 1.53 always use non-blocking calls when reading/writing from/to your file
221     handles.
222 root 1.14
223 root 1.164 Example: wait for readability of STDIN, then read a line and disable the
224     watcher.
225 root 1.14
226     my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
227     chomp (my $input = <STDIN>);
228     warn "read: $input\n";
229     undef $w;
230     });
231    
232 root 1.19 =head2 TIME WATCHERS
233 root 1.14
234 root 1.266 $w = AnyEvent->timer (after => <seconds>, cb => <callback>);
235    
236     $w = AnyEvent->timer (
237     after => <fractional_seconds>,
238     interval => <fractional_seconds>,
239     cb => <callback>,
240     );
241    
242 root 1.19 You can create a time watcher by calling the C<< AnyEvent->timer >>
243 root 1.14 method with the following mandatory arguments:
244    
245 root 1.53 C<after> specifies after how many seconds (fractional values are
246 root 1.85 supported) the callback should be invoked. C<cb> is the callback to invoke
247     in that case.
248    
249     Although the callback might get passed parameters, their value and
250     presence is undefined and you cannot rely on them. Portable AnyEvent
251     callbacks cannot use arguments passed to time watcher callbacks.
252 root 1.14
253 root 1.330 The callback will normally be invoked only once. If you specify another
254 root 1.165 parameter, C<interval>, as a strictly positive number (> 0), then the
255     callback will be invoked regularly at that interval (in fractional
256     seconds) after the first invocation. If C<interval> is specified with a
257 root 1.330 false value, then it is treated as if it were not specified at all.
258 root 1.164
259     The callback will be rescheduled before invoking the callback, but no
260 root 1.330 attempt is made to avoid timer drift in most backends, so the interval is
261 root 1.164 only approximate.
262 root 1.14
263 root 1.164 Example: fire an event after 7.7 seconds.
264 root 1.14
265     my $w = AnyEvent->timer (after => 7.7, cb => sub {
266     warn "timeout\n";
267     });
268    
269     # to cancel the timer:
270 root 1.37 undef $w;
271 root 1.14
272 root 1.164 Example 2: fire an event after 0.5 seconds, then roughly every second.
273 root 1.53
274 root 1.164 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
275     warn "timeout\n";
276 root 1.53 };
277    
278     =head3 TIMING ISSUES
279    
280     There are two ways to handle timers: based on real time (relative, "fire
281     in 10 seconds") and based on wallclock time (absolute, "fire at 12
282     o'clock").
283    
284 root 1.58 While most event loops expect timers to specified in a relative way, they
285     use absolute time internally. This makes a difference when your clock
286     "jumps", for example, when ntp decides to set your clock backwards from
287     the wrong date of 2014-01-01 to 2008-01-01, a watcher that is supposed to
288 root 1.330 fire "after a second" might actually take six years to finally fire.
289 root 1.53
290     AnyEvent cannot compensate for this. The only event loop that is conscious
291 root 1.330 of these issues is L<EV>, which offers both relative (ev_timer, based
292 root 1.58 on true relative time) and absolute (ev_periodic, based on wallclock time)
293     timers.
294 root 1.53
295     AnyEvent always prefers relative timers, if available, matching the
296     AnyEvent API.
297    
298 root 1.143 AnyEvent has two additional methods that return the "current time":
299    
300     =over 4
301    
302     =item AnyEvent->time
303    
304     This returns the "current wallclock time" as a fractional number of
305     seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
306     return, and the result is guaranteed to be compatible with those).
307    
308 root 1.144 It progresses independently of any event loop processing, i.e. each call
309     will check the system clock, which usually gets updated frequently.
310 root 1.143
311     =item AnyEvent->now
312    
313     This also returns the "current wallclock time", but unlike C<time>, above,
314     this value might change only once per event loop iteration, depending on
315     the event loop (most return the same time as C<time>, above). This is the
316 root 1.144 time that AnyEvent's timers get scheduled against.
317    
318     I<In almost all cases (in all cases if you don't care), this is the
319     function to call when you want to know the current time.>
320    
321     This function is also often faster then C<< AnyEvent->time >>, and
322     thus the preferred method if you want some timestamp (for example,
323 root 1.330 L<AnyEvent::Handle> uses this to update its activity timeouts).
324 root 1.144
325     The rest of this section is only of relevance if you try to be very exact
326 root 1.330 with your timing; you can skip it without a bad conscience.
327 root 1.143
328     For a practical example of when these times differ, consider L<Event::Lib>
329     and L<EV> and the following set-up:
330    
331 root 1.330 The event loop is running and has just invoked one of your callbacks at
332 root 1.143 time=500 (assume no other callbacks delay processing). In your callback,
333     you wait a second by executing C<sleep 1> (blocking the process for a
334     second) and then (at time=501) you create a relative timer that fires
335     after three seconds.
336    
337     With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
338     both return C<501>, because that is the current time, and the timer will
339     be scheduled to fire at time=504 (C<501> + C<3>).
340    
341 root 1.144 With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
342 root 1.143 time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
343     last event processing phase started. With L<EV>, your timer gets scheduled
344     to run at time=503 (C<500> + C<3>).
345    
346     In one sense, L<Event::Lib> is more exact, as it uses the current time
347     regardless of any delays introduced by event processing. However, most
348     callbacks do not expect large delays in processing, so this causes a
349 root 1.144 higher drift (and a lot more system calls to get the current time).
350 root 1.143
351     In another sense, L<EV> is more exact, as your timer will be scheduled at
352     the same time, regardless of how long event processing actually took.
353    
354     In either case, if you care (and in most cases, you don't), then you
355     can get whatever behaviour you want with any event loop, by taking the
356     difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
357     account.
358    
359 root 1.205 =item AnyEvent->now_update
360    
361 root 1.352 Some event loops (such as L<EV> or L<AnyEvent::Loop>) cache the current
362     time for each loop iteration (see the discussion of L<< AnyEvent->now >>,
363     above).
364 root 1.205
365     When a callback runs for a long time (or when the process sleeps), then
366     this "current" time will differ substantially from the real time, which
367     might affect timers and time-outs.
368    
369     When this is the case, you can call this method, which will update the
370     event loop's idea of "current time".
371    
372 root 1.296 A typical example would be a script in a web server (e.g. C<mod_perl>) -
373     when mod_perl executes the script, then the event loop will have the wrong
374     idea about the "current time" (being potentially far in the past, when the
375     script ran the last time). In that case you should arrange a call to C<<
376     AnyEvent->now_update >> each time the web server process wakes up again
377     (e.g. at the start of your script, or in a handler).
378    
379 root 1.205 Note that updating the time I<might> cause some events to be handled.
380    
381 root 1.143 =back
382    
383 root 1.53 =head2 SIGNAL WATCHERS
384 root 1.14
385 root 1.266 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
386    
387 root 1.53 You can watch for signals using a signal watcher, C<signal> is the signal
388 root 1.167 I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
389     callback to be invoked whenever a signal occurs.
390 root 1.53
391 root 1.85 Although the callback might get passed parameters, their value and
392     presence is undefined and you cannot rely on them. Portable AnyEvent
393     callbacks cannot use arguments passed to signal watcher callbacks.
394    
395 elmex 1.129 Multiple signal occurrences can be clumped together into one callback
396     invocation, and callback invocation will be synchronous. Synchronous means
397 root 1.53 that it might take a while until the signal gets handled by the process,
398 elmex 1.129 but it is guaranteed not to interrupt any other callbacks.
399 root 1.53
400     The main advantage of using these watchers is that you can share a signal
401 root 1.242 between multiple watchers, and AnyEvent will ensure that signals will not
402     interrupt your program at bad times.
403 root 1.53
404 root 1.242 This watcher might use C<%SIG> (depending on the event loop used),
405     so programs overwriting those signals directly will likely not work
406     correctly.
407    
408 root 1.247 Example: exit on SIGINT
409    
410     my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
411    
412 root 1.298 =head3 Restart Behaviour
413    
414     While restart behaviour is up to the event loop implementation, most will
415     not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's
416     pure perl implementation).
417    
418     =head3 Safe/Unsafe Signals
419    
420     Perl signals can be either "safe" (synchronous to opcode handling) or
421     "unsafe" (asynchronous) - the former might get delayed indefinitely, the
422     latter might corrupt your memory.
423    
424     AnyEvent signal handlers are, in addition, synchronous to the event loop,
425     i.e. they will not interrupt your running perl program but will only be
426     called as part of the normal event handling (just like timer, I/O etc.
427     callbacks, too).
428    
429 root 1.247 =head3 Signal Races, Delays and Workarounds
430    
431     Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
432 root 1.267 callbacks to signals in a generic way, which is a pity, as you cannot
433     do race-free signal handling in perl, requiring C libraries for
434 root 1.330 this. AnyEvent will try to do its best, which means in some cases,
435 root 1.267 signals will be delayed. The maximum time a signal might be delayed is
436     specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This
437     variable can be changed only before the first signal watcher is created,
438     and should be left alone otherwise. This variable determines how often
439     AnyEvent polls for signals (in case a wake-up was missed). Higher values
440 root 1.242 will cause fewer spurious wake-ups, which is better for power and CPU
441 root 1.267 saving.
442    
443     All these problems can be avoided by installing the optional
444     L<Async::Interrupt> module, which works with most event loops. It will not
445     work with inherently broken event loops such as L<Event> or L<Event::Lib>
446 root 1.330 (and not with L<POE> currently, as POE does its own workaround with
447 root 1.267 one-second latency). For those, you just have to suffer the delays.
448 root 1.53
449     =head2 CHILD PROCESS WATCHERS
450    
451 root 1.266 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
452    
453 root 1.330 You can also watch for a child process exit and catch its exit status.
454 root 1.53
455 root 1.330 The child process is specified by the C<pid> argument (on some backends,
456 root 1.254 using C<0> watches for any child process exit, on others this will
457     croak). The watcher will be triggered only when the child process has
458     finished and an exit status is available, not on any trace events
459     (stopped/continued).
460 root 1.181
461     The callback will be called with the pid and exit status (as returned by
462     waitpid), so unlike other watcher types, you I<can> rely on child watcher
463     callback arguments.
464    
465     This watcher type works by installing a signal handler for C<SIGCHLD>,
466     and since it cannot be shared, nothing else should use SIGCHLD or reap
467     random child processes (waiting for specific child processes, e.g. inside
468     C<system>, is just fine).
469 root 1.53
470 root 1.82 There is a slight catch to child watchers, however: you usually start them
471     I<after> the child process was created, and this means the process could
472     have exited already (and no SIGCHLD will be sent anymore).
473    
474 root 1.219 Not all event models handle this correctly (neither POE nor IO::Async do,
475     see their AnyEvent::Impl manpages for details), but even for event models
476     that I<do> handle this correctly, they usually need to be loaded before
477     the process exits (i.e. before you fork in the first place). AnyEvent's
478     pure perl event loop handles all cases correctly regardless of when you
479     start the watcher.
480    
481     This means you cannot create a child watcher as the very first
482     thing in an AnyEvent program, you I<have> to create at least one
483     watcher before you C<fork> the child (alternatively, you can call
484     C<AnyEvent::detect>).
485 root 1.82
486 root 1.242 As most event loops do not support waiting for child events, they will be
487 root 1.351 emulated by AnyEvent in most cases, in which case the latency and race
488     problems mentioned in the description of signal watchers apply.
489 root 1.242
490 root 1.82 Example: fork a process and wait for it
491    
492 root 1.151 my $done = AnyEvent->condvar;
493    
494     my $pid = fork or exit 5;
495    
496     my $w = AnyEvent->child (
497     pid => $pid,
498     cb => sub {
499     my ($pid, $status) = @_;
500     warn "pid $pid exited with status $status";
501     $done->send;
502     },
503     );
504    
505     # do something else, then wait for process exit
506     $done->recv;
507 root 1.82
508 root 1.207 =head2 IDLE WATCHERS
509    
510 root 1.266 $w = AnyEvent->idle (cb => <callback>);
511    
512 root 1.330 This will repeatedly invoke the callback after the process becomes idle,
513     until either the watcher is destroyed or new events have been detected.
514 root 1.207
515 root 1.309 Idle watchers are useful when there is a need to do something, but it
516     is not so important (or wise) to do it instantly. The callback will be
517     invoked only when there is "nothing better to do", which is usually
518     defined as "all outstanding events have been handled and no new events
519     have been detected". That means that idle watchers ideally get invoked
520     when the event loop has just polled for new events but none have been
521     detected. Instead of blocking to wait for more events, the idle watchers
522     will be invoked.
523    
524     Unfortunately, most event loops do not really support idle watchers (only
525 root 1.207 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
526     will simply call the callback "from time to time".
527    
528     Example: read lines from STDIN, but only process them when the
529     program is otherwise idle:
530    
531     my @lines; # read data
532     my $idle_w;
533     my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
534     push @lines, scalar <STDIN>;
535    
536     # start an idle watcher, if not already done
537     $idle_w ||= AnyEvent->idle (cb => sub {
538     # handle only one line, when there are lines left
539     if (my $line = shift @lines) {
540     print "handled when idle: $line";
541     } else {
542     # otherwise disable the idle watcher again
543     undef $idle_w;
544     }
545     });
546     });
547    
548 root 1.53 =head2 CONDITION VARIABLES
549    
550 root 1.266 $cv = AnyEvent->condvar;
551    
552     $cv->send (<list>);
553     my @res = $cv->recv;
554    
555 root 1.105 If you are familiar with some event loops you will know that all of them
556     require you to run some blocking "loop", "run" or similar function that
557     will actively watch for new events and call your callbacks.
558    
559 root 1.239 AnyEvent is slightly different: it expects somebody else to run the event
560     loop and will only block when necessary (usually when told by the user).
561 root 1.105
562 root 1.326 The tool to do that is called a "condition variable", so called because
563     they represent a condition that must become true.
564 root 1.105
565 root 1.239 Now is probably a good time to look at the examples further below.
566    
567 root 1.105 Condition variables can be created by calling the C<< AnyEvent->condvar
568     >> method, usually without arguments. The only argument pair allowed is
569     C<cb>, which specifies a callback to be called when the condition variable
570 root 1.173 becomes true, with the condition variable as the first argument (but not
571     the results).
572 root 1.105
573 elmex 1.129 After creation, the condition variable is "false" until it becomes "true"
574 root 1.131 by calling the C<send> method (or calling the condition variable as if it
575 root 1.135 were a callback, read about the caveats in the description for the C<<
576     ->send >> method).
577 root 1.105
578 root 1.326 Since condition variables are the most complex part of the AnyEvent API, here are
579     some different mental models of what they are - pick the ones you can connect to:
580    
581     =over 4
582    
583     =item * Condition variables are like callbacks - you can call them (and pass them instead
584     of callbacks). Unlike callbacks however, you can also wait for them to be called.
585    
586     =item * Condition variables are signals - one side can emit or send them,
587     the other side can wait for them, or install a handler that is called when
588     the signal fires.
589    
590     =item * Condition variables are like "Merge Points" - points in your program
591     where you merge multiple independent results/control flows into one.
592    
593 root 1.330 =item * Condition variables represent a transaction - functions that start
594 root 1.326 some kind of transaction can return them, leaving the caller the choice
595     between waiting in a blocking fashion, or setting a callback.
596    
597     =item * Condition variables represent future values, or promises to deliver
598     some result, long before the result is available.
599    
600     =back
601 root 1.14
602 root 1.105 Condition variables are very useful to signal that something has finished,
603     for example, if you write a module that does asynchronous http requests,
604 root 1.53 then a condition variable would be the ideal candidate to signal the
605 root 1.105 availability of results. The user can either act when the callback is
606 root 1.114 called or can synchronously C<< ->recv >> for the results.
607 root 1.53
608 root 1.105 You can also use them to simulate traditional event loops - for example,
609     you can block your main program until an event occurs - for example, you
610 root 1.114 could C<< ->recv >> in your main program until the user clicks the Quit
611 root 1.106 button of your app, which would C<< ->send >> the "quit" event.
612 root 1.53
613     Note that condition variables recurse into the event loop - if you have
614 elmex 1.129 two pieces of code that call C<< ->recv >> in a round-robin fashion, you
615 root 1.53 lose. Therefore, condition variables are good to export to your caller, but
616     you should avoid making a blocking wait yourself, at least in callbacks,
617     as this asks for trouble.
618 root 1.41
619 root 1.105 Condition variables are represented by hash refs in perl, and the keys
620     used by AnyEvent itself are all named C<_ae_XXX> to make subclassing
621     easy (it is often useful to build your own transaction class on top of
622     AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call
623 root 1.330 its C<new> method in your own C<new> method.
624 root 1.105
625     There are two "sides" to a condition variable - the "producer side" which
626 root 1.106 eventually calls C<< -> send >>, and the "consumer side", which waits
627     for the send to occur.
628 root 1.105
629 root 1.131 Example: wait for a timer.
630 root 1.105
631 root 1.319 # condition: "wait till the timer is fired"
632     my $timer_fired = AnyEvent->condvar;
633 root 1.105
634 root 1.319 # create the timer - we could wait for, say
635     # a handle becomign ready, or even an
636     # AnyEvent::HTTP request to finish, but
637 root 1.105 # in this case, we simply use a timer:
638     my $w = AnyEvent->timer (
639     after => 1,
640 root 1.319 cb => sub { $timer_fired->send },
641 root 1.105 );
642    
643     # this "blocks" (while handling events) till the callback
644 root 1.285 # calls ->send
645 root 1.319 $timer_fired->recv;
646 root 1.105
647 root 1.239 Example: wait for a timer, but take advantage of the fact that condition
648     variables are also callable directly.
649 root 1.131
650     my $done = AnyEvent->condvar;
651     my $delay = AnyEvent->timer (after => 5, cb => $done);
652     $done->recv;
653    
654 root 1.173 Example: Imagine an API that returns a condvar and doesn't support
655     callbacks. This is how you make a synchronous call, for example from
656     the main program:
657    
658     use AnyEvent::CouchDB;
659    
660     ...
661    
662     my @info = $couchdb->info->recv;
663    
664 root 1.239 And this is how you would just set a callback to be called whenever the
665 root 1.173 results are available:
666    
667     $couchdb->info->cb (sub {
668     my @info = $_[0]->recv;
669     });
670    
671 root 1.105 =head3 METHODS FOR PRODUCERS
672    
673     These methods should only be used by the producing side, i.e. the
674 root 1.106 code/module that eventually sends the signal. Note that it is also
675 root 1.105 the producer side which creates the condvar in most cases, but it isn't
676     uncommon for the consumer to create it as well.
677 root 1.2
678 root 1.1 =over 4
679    
680 root 1.106 =item $cv->send (...)
681 root 1.105
682 root 1.114 Flag the condition as ready - a running C<< ->recv >> and all further
683     calls to C<recv> will (eventually) return after this method has been
684 root 1.106 called. If nobody is waiting the send will be remembered.
685 root 1.105
686     If a callback has been set on the condition variable, it is called
687 root 1.106 immediately from within send.
688 root 1.105
689 root 1.106 Any arguments passed to the C<send> call will be returned by all
690 root 1.114 future C<< ->recv >> calls.
691 root 1.105
692 root 1.239 Condition variables are overloaded so one can call them directly (as if
693     they were a code reference). Calling them directly is the same as calling
694     C<send>.
695 root 1.131
696 root 1.105 =item $cv->croak ($error)
697    
698 root 1.330 Similar to send, but causes all calls to C<< ->recv >> to invoke
699 root 1.105 C<Carp::croak> with the given error message/object/scalar.
700    
701     This can be used to signal any errors to the condition variable
702 root 1.239 user/consumer. Doing it this way instead of calling C<croak> directly
703 root 1.330 delays the error detection, but has the overwhelming advantage that it
704 root 1.239 diagnoses the error at the place where the result is expected, and not
705 root 1.330 deep in some event callback with no connection to the actual code causing
706 root 1.239 the problem.
707 root 1.105
708     =item $cv->begin ([group callback])
709    
710     =item $cv->end
711    
712     These two methods can be used to combine many transactions/events into
713     one. For example, a function that pings many hosts in parallel might want
714     to use a condition variable for the whole process.
715    
716     Every call to C<< ->begin >> will increment a counter, and every call to
717     C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
718 root 1.280 >>, the (last) callback passed to C<begin> will be executed, passing the
719     condvar as first argument. That callback is I<supposed> to call C<< ->send
720     >>, but that is not required. If no group callback was set, C<send> will
721     be called without any arguments.
722 root 1.105
723 root 1.222 You can think of C<< $cv->send >> giving you an OR condition (one call
724     sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND
725     condition (all C<begin> calls must be C<end>'ed before the condvar sends).
726    
727     Let's start with a simple example: you have two I/O watchers (for example,
728     STDOUT and STDERR for a program), and you want to wait for both streams to
729     close before activating a condvar:
730    
731     my $cv = AnyEvent->condvar;
732    
733     $cv->begin; # first watcher
734     my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
735     defined sysread $fh1, my $buf, 4096
736     or $cv->end;
737     });
738    
739     $cv->begin; # second watcher
740     my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
741     defined sysread $fh2, my $buf, 4096
742     or $cv->end;
743     });
744    
745     $cv->recv;
746    
747     This works because for every event source (EOF on file handle), there is
748     one call to C<begin>, so the condvar waits for all calls to C<end> before
749     sending.
750    
751     The ping example mentioned above is slightly more complicated, as the
752     there are results to be passwd back, and the number of tasks that are
753 root 1.330 begun can potentially be zero:
754 root 1.105
755     my $cv = AnyEvent->condvar;
756    
757     my %result;
758 root 1.280 $cv->begin (sub { shift->send (\%result) });
759 root 1.105
760     for my $host (@list_of_hosts) {
761     $cv->begin;
762     ping_host_then_call_callback $host, sub {
763     $result{$host} = ...;
764     $cv->end;
765     };
766     }
767    
768     $cv->end;
769    
770     This code fragment supposedly pings a number of hosts and calls
771 root 1.106 C<send> after results for all then have have been gathered - in any
772 root 1.105 order. To achieve this, the code issues a call to C<begin> when it starts
773     each ping request and calls C<end> when it has received some result for
774     it. Since C<begin> and C<end> only maintain a counter, the order in which
775     results arrive is not relevant.
776    
777     There is an additional bracketing call to C<begin> and C<end> outside the
778     loop, which serves two important purposes: first, it sets the callback
779     to be called once the counter reaches C<0>, and second, it ensures that
780 root 1.106 C<send> is called even when C<no> hosts are being pinged (the loop
781 root 1.105 doesn't execute once).
782    
783 root 1.222 This is the general pattern when you "fan out" into multiple (but
784 root 1.330 potentially zero) subrequests: use an outer C<begin>/C<end> pair to set
785 root 1.222 the callback and ensure C<end> is called at least once, and then, for each
786     subrequest you start, call C<begin> and for each subrequest you finish,
787     call C<end>.
788 root 1.105
789     =back
790    
791     =head3 METHODS FOR CONSUMERS
792    
793     These methods should only be used by the consuming side, i.e. the
794     code awaits the condition.
795    
796 root 1.106 =over 4
797    
798 root 1.114 =item $cv->recv
799 root 1.14
800 root 1.106 Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
801 root 1.330 >> methods have been called on C<$cv>, while servicing other watchers
802 root 1.105 normally.
803    
804     You can only wait once on a condition - additional calls are valid but
805     will return immediately.
806    
807     If an error condition has been set by calling C<< ->croak >>, then this
808     function will call C<croak>.
809 root 1.14
810 root 1.106 In list context, all parameters passed to C<send> will be returned,
811 root 1.105 in scalar context only the first one will be returned.
812 root 1.14
813 root 1.239 Note that doing a blocking wait in a callback is not supported by any
814     event loop, that is, recursive invocation of a blocking C<< ->recv
815     >> is not allowed, and the C<recv> call will C<croak> if such a
816     condition is detected. This condition can be slightly loosened by using
817     L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from
818     any thread that doesn't run the event loop itself.
819    
820 root 1.47 Not all event models support a blocking wait - some die in that case
821 root 1.53 (programs might want to do that to stay interactive), so I<if you are
822 root 1.239 using this from a module, never require a blocking wait>. Instead, let the
823 root 1.52 caller decide whether the call will block or not (for example, by coupling
824 root 1.47 condition variables with some kind of request results and supporting
825     callbacks so the caller knows that getting the result will not block,
826 elmex 1.129 while still supporting blocking waits if the caller so desires).
827 root 1.47
828 root 1.330 You can ensure that C<< ->recv >> never blocks by setting a callback and
829 root 1.114 only calling C<< ->recv >> from within that callback (or at a later
830 root 1.105 time). This will work even when the event loop does not support blocking
831     waits otherwise.
832 root 1.53
833 root 1.106 =item $bool = $cv->ready
834    
835     Returns true when the condition is "true", i.e. whether C<send> or
836     C<croak> have been called.
837    
838 root 1.173 =item $cb = $cv->cb ($cb->($cv))
839 root 1.106
840     This is a mutator function that returns the callback set and optionally
841     replaces it before doing so.
842    
843 root 1.330 The callback will be called when the condition becomes "true", i.e. when
844     C<send> or C<croak> are called, with the only argument being the
845     condition variable itself. If the condition is already true, the
846     callback is called immediately when it is set. Calling C<recv> inside
847     the callback or at any later time is guaranteed not to block.
848 root 1.106
849 root 1.53 =back
850 root 1.14
851 root 1.232 =head1 SUPPORTED EVENT LOOPS/BACKENDS
852    
853     The available backend classes are (every class has its own manpage):
854    
855     =over 4
856    
857     =item Backends that are autoprobed when no other event loop can be found.
858    
859     EV is the preferred backend when no other event loop seems to be in
860 root 1.276 use. If EV is not installed, then AnyEvent will fall back to its own
861     pure-perl implementation, which is available everywhere as it comes with
862     AnyEvent itself.
863 root 1.232
864     AnyEvent::Impl::EV based on EV (interface to libev, best choice).
865 root 1.352 AnyEvent::Impl::Perl pure-perl AnyEvent::Loop, fast and portable.
866 root 1.232
867     =item Backends that are transparently being picked up when they are used.
868    
869 root 1.330 These will be used if they are already loaded when the first watcher
870 root 1.232 is created, in which case it is assumed that the application is using
871     them. This means that AnyEvent will automatically pick the right backend
872     when the main program loads an event module before anything starts to
873     create watchers. Nothing special needs to be done by the main program.
874    
875 root 1.276 AnyEvent::Impl::Event based on Event, very stable, few glitches.
876 root 1.232 AnyEvent::Impl::Glib based on Glib, slow but very stable.
877     AnyEvent::Impl::Tk based on Tk, very broken.
878     AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
879     AnyEvent::Impl::POE based on POE, very slow, some limitations.
880 root 1.254 AnyEvent::Impl::Irssi used when running within irssi.
881 root 1.342 AnyEvent::Impl::IOAsync based on IO::Async.
882 root 1.344 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
883 root 1.356 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding).
884 root 1.232
885     =item Backends with special needs.
886    
887     Qt requires the Qt::Application to be instantiated first, but will
888     otherwise be picked up automatically. As long as the main program
889     instantiates the application before any AnyEvent watchers are created,
890     everything should just work.
891    
892     AnyEvent::Impl::Qt based on Qt.
893    
894     =item Event loops that are indirectly supported via other backends.
895    
896     Some event loops can be supported via other modules:
897    
898     There is no direct support for WxWidgets (L<Wx>) or L<Prima>.
899    
900     B<WxWidgets> has no support for watching file handles. However, you can
901     use WxWidgets through the POE adaptor, as POE has a Wx backend that simply
902     polls 20 times per second, which was considered to be too horrible to even
903     consider for AnyEvent.
904    
905     B<Prima> is not supported as nobody seems to be using it, but it has a POE
906     backend, so it can be supported through POE.
907    
908     AnyEvent knows about both L<Prima> and L<Wx>, however, and will try to
909     load L<POE> when detecting them, in the hope that POE will pick them up,
910     in which case everything will be automatic.
911    
912     =back
913    
914 root 1.53 =head1 GLOBAL VARIABLES AND FUNCTIONS
915 root 1.16
916 root 1.233 These are not normally required to use AnyEvent, but can be useful to
917     write AnyEvent extension modules.
918    
919 root 1.16 =over 4
920    
921     =item $AnyEvent::MODEL
922    
923 root 1.233 Contains C<undef> until the first watcher is being created, before the
924     backend has been autodetected.
925    
926     Afterwards it contains the event model that is being used, which is the
927     name of the Perl class implementing the model. This class is usually one
928 root 1.330 of the C<AnyEvent::Impl::xxx> modules, but can be any other class in the
929 root 1.233 case AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode> it
930     will be C<urxvt::anyevent>).
931 root 1.16
932 root 1.19 =item AnyEvent::detect
933    
934 root 1.53 Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
935     if necessary. You should only call this function right before you would
936     have created an AnyEvent watcher anyway, that is, as late as possible at
937 root 1.330 runtime, and not e.g. during initialisation of your module.
938 root 1.233
939 root 1.359 The effect of calling this function is as if a watcher had been created
940     (specifically, actions that happen "when the first watcher is created"
941     happen when calling detetc as well).
942    
943 root 1.233 If you need to do some initialisation before AnyEvent watchers are
944     created, use C<post_detect>.
945 root 1.19
946 root 1.111 =item $guard = AnyEvent::post_detect { BLOCK }
947 root 1.109
948     Arranges for the code block to be executed as soon as the event model is
949 root 1.330 autodetected (or immediately if that has already happened).
950 root 1.109
951 root 1.233 The block will be executed I<after> the actual backend has been detected
952     (C<$AnyEvent::MODEL> is set), but I<before> any watchers have been
953     created, so it is possible to e.g. patch C<@AnyEvent::ISA> or do
954     other initialisations - see the sources of L<AnyEvent::Strict> or
955     L<AnyEvent::AIO> to see how this is used.
956    
957     The most common usage is to create some global watchers, without forcing
958     event module detection too early, for example, L<AnyEvent::AIO> creates
959     and installs the global L<IO::AIO> watcher in a C<post_detect> block to
960     avoid autodetecting the event module at load time.
961    
962 root 1.110 If called in scalar or list context, then it creates and returns an object
963 root 1.252 that automatically removes the callback again when it is destroyed (or
964     C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
965     a case where this is useful.
966    
967     Example: Create a watcher for the IO::AIO module and store it in
968 root 1.330 C<$WATCHER>, but do so only do so after the event loop is initialised.
969 root 1.252
970     our WATCHER;
971    
972     my $guard = AnyEvent::post_detect {
973     $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
974     };
975    
976     # the ||= is important in case post_detect immediately runs the block,
977     # as to not clobber the newly-created watcher. assigning both watcher and
978     # post_detect guard to the same variable has the advantage of users being
979     # able to just C<undef $WATCHER> if the watcher causes them grief.
980    
981     $WATCHER ||= $guard;
982 root 1.110
983 root 1.111 =item @AnyEvent::post_detect
984 root 1.108
985     If there are any code references in this array (you can C<push> to it
986 root 1.330 before or after loading AnyEvent), then they will be called directly
987     after the event loop has been chosen.
988 root 1.108
989     You should check C<$AnyEvent::MODEL> before adding to this array, though:
990 root 1.233 if it is defined then the event loop has already been detected, and the
991     array will be ignored.
992    
993     Best use C<AnyEvent::post_detect { BLOCK }> when your application allows
994 root 1.304 it, as it takes care of these details.
995 root 1.108
996 root 1.233 This variable is mainly useful for modules that can do something useful
997     when AnyEvent is used and thus want to know when it is initialised, but do
998     not need to even load it by default. This array provides the means to hook
999     into AnyEvent passively, without loading it.
1000 root 1.109
1001 root 1.304 Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
1002     together, you could put this into Coro (this is the actual code used by
1003     Coro to accomplish this):
1004    
1005     if (defined $AnyEvent::MODEL) {
1006     # AnyEvent already initialised, so load Coro::AnyEvent
1007     require Coro::AnyEvent;
1008     } else {
1009     # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
1010     # as soon as it is
1011     push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
1012     }
1013    
1014 root 1.354 =item AnyEvent::postpone { BLOCK }
1015 root 1.353
1016     Arranges for the block to be executed as soon as possible, but not before
1017     the call itself returns. In practise, the block will be executed just
1018     before the event loop polls for new events, or shortly afterwards.
1019    
1020     This function never returns anything (to make the C<return postpone { ...
1021     }> idiom more useful.
1022    
1023     To understand the usefulness of this function, consider a function that
1024     asynchronously does something for you and returns some transaction
1025     object or guard to let you cancel the operation. For example,
1026     C<AnyEvent::Socket::tcp_connect>:
1027    
1028     # start a conenction attempt unless one is active
1029     $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub {
1030     delete $self->{connect_guard};
1031     ...
1032     };
1033    
1034     Imagine that this function could instantly call the callback, for
1035     example, because it detects an obvious error such as a negative port
1036     number. Invoking the callback before the function returns causes problems
1037     however: the callback will be called and will try to delete the guard
1038     object. But since the function hasn't returned yet, there is nothing to
1039     delete. When the function eventually returns it will assign the guard
1040     object to C<< $self->{connect_guard} >>, where it will likely never be
1041     deleted, so the program thinks it is still trying to connect.
1042    
1043     This is where C<AnyEvent::postpone> should be used. Instead of calling the
1044     callback directly on error:
1045    
1046     $cb->(undef), return # signal error to callback, BAD!
1047     if $some_error_condition;
1048    
1049     It should use C<postpone>:
1050    
1051     AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1052     if $some_error_condition;
1053    
1054 root 1.365 =item AnyEvent::log $level, $msg[, @args]
1055    
1056     Log the given C<$msg> at the given C<$level>.
1057    
1058     Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> -
1059     consequently, look at the L<AnyEvent::Log> documentation for details.
1060    
1061 root 1.16 =back
1062    
1063 root 1.14 =head1 WHAT TO DO IN A MODULE
1064    
1065 root 1.53 As a module author, you should C<use AnyEvent> and call AnyEvent methods
1066 root 1.14 freely, but you should not load a specific event module or rely on it.
1067    
1068 root 1.53 Be careful when you create watchers in the module body - AnyEvent will
1069 root 1.14 decide which event module to use as soon as the first method is called, so
1070     by calling AnyEvent in your module body you force the user of your module
1071     to load the event module first.
1072    
1073 root 1.114 Never call C<< ->recv >> on a condition variable unless you I<know> that
1074 root 1.106 the C<< ->send >> method has been called on it already. This is
1075 root 1.53 because it will stall the whole program, and the whole point of using
1076     events is to stay interactive.
1077    
1078 root 1.114 It is fine, however, to call C<< ->recv >> when the user of your module
1079 root 1.53 requests it (i.e. if you create a http request object ad have a method
1080 root 1.330 called C<results> that returns the results, it may call C<< ->recv >>
1081     freely, as the user of your module knows what she is doing. Always).
1082 root 1.53
1083 root 1.14 =head1 WHAT TO DO IN THE MAIN PROGRAM
1084    
1085     There will always be a single main program - the only place that should
1086     dictate which event model to use.
1087    
1088 root 1.330 If the program is not event-based, it need not do anything special, even
1089     when it depends on a module that uses an AnyEvent. If the program itself
1090     uses AnyEvent, but does not care which event loop is used, all it needs
1091     to do is C<use AnyEvent>. In either case, AnyEvent will choose the best
1092     available loop implementation.
1093 root 1.14
1094 root 1.134 If the main program relies on a specific event model - for example, in
1095     Gtk2 programs you have to rely on the Glib module - you should load the
1096 root 1.53 event module before loading AnyEvent or any module that uses it: generally
1097     speaking, you should load it as early as possible. The reason is that
1098     modules might create watchers when they are loaded, and AnyEvent will
1099     decide on the event model to use as soon as it creates watchers, and it
1100 root 1.330 might choose the wrong one unless you load the correct one yourself.
1101 root 1.14
1102 root 1.134 You can chose to use a pure-perl implementation by loading the
1103 root 1.352 C<AnyEvent::Loop> module, which gives you similar behaviour
1104 root 1.134 everywhere, but letting AnyEvent chose the model is generally better.
1105    
1106     =head2 MAINLOOP EMULATION
1107    
1108     Sometimes (often for short test scripts, or even standalone programs who
1109     only want to use AnyEvent), you do not want to run a specific event loop.
1110    
1111     In that case, you can use a condition variable like this:
1112    
1113     AnyEvent->condvar->recv;
1114    
1115     This has the effect of entering the event loop and looping forever.
1116    
1117     Note that usually your program has some exit condition, in which case
1118     it is better to use the "traditional" approach of storing a condition
1119     variable somewhere, waiting for it, and sending it when the program should
1120     exit cleanly.
1121    
1122 root 1.14
1123 elmex 1.100 =head1 OTHER MODULES
1124    
1125 root 1.101 The following is a non-exhaustive list of additional modules that use
1126 root 1.230 AnyEvent as a client and can therefore be mixed easily with other AnyEvent
1127     modules and other event loops in the same program. Some of the modules
1128 root 1.325 come as part of AnyEvent, the others are available via CPAN.
1129 root 1.101
1130     =over 4
1131    
1132     =item L<AnyEvent::Util>
1133    
1134 root 1.330 Contains various utility functions that replace often-used blocking
1135     functions such as C<inet_aton> with event/callback-based versions.
1136 root 1.101
1137 root 1.125 =item L<AnyEvent::Socket>
1138    
1139     Provides various utility functions for (internet protocol) sockets,
1140     addresses and name resolution. Also functions to create non-blocking tcp
1141     connections or tcp servers, with IPv6 and SRV record support and more.
1142    
1143 root 1.164 =item L<AnyEvent::Handle>
1144    
1145     Provide read and write buffers, manages watchers for reads and writes,
1146     supports raw and formatted I/O, I/O queued and fully transparent and
1147 root 1.330 non-blocking SSL/TLS (via L<AnyEvent::TLS>).
1148 root 1.164
1149 root 1.134 =item L<AnyEvent::DNS>
1150    
1151     Provides rich asynchronous DNS resolver capabilities.
1152    
1153 root 1.323 =item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1154 root 1.155
1155 root 1.323 Implement event-based interfaces to the protocols of the same name (for
1156     the curious, IGS is the International Go Server and FCP is the Freenet
1157     Client Protocol).
1158    
1159     =item L<AnyEvent::Handle::UDP>
1160    
1161     Here be danger!
1162    
1163     As Pauli would put it, "Not only is it not right, it's not even wrong!" -
1164     there are so many things wrong with AnyEvent::Handle::UDP, most notably
1165 root 1.330 its use of a stream-based API with a protocol that isn't streamable, that
1166 root 1.323 the only way to improve it is to delete it.
1167    
1168     It features data corruption (but typically only under load) and general
1169     confusion. On top, the author is not only clueless about UDP but also
1170     fact-resistant - some gems of his understanding: "connect doesn't work
1171     with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
1172     packets", "I don't need to implement proper error checking as UDP doesn't
1173     support error checking" and so on - he doesn't even understand what's
1174     wrong with his module when it is explained to him.
1175 root 1.101
1176 root 1.159 =item L<AnyEvent::DBI>
1177    
1178 root 1.323 Executes L<DBI> requests asynchronously in a proxy process for you,
1179 root 1.330 notifying you in an event-based way when the operation is finished.
1180 root 1.164
1181     =item L<AnyEvent::AIO>
1182    
1183 root 1.323 Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1184     toolbox of every event programmer. AnyEvent::AIO transparently fuses
1185     L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1186     file I/O, and much more.
1187 root 1.164
1188 root 1.323 =item L<AnyEvent::HTTPD>
1189 root 1.164
1190 root 1.323 A simple embedded webserver.
1191 root 1.164
1192 root 1.323 =item L<AnyEvent::FastPing>
1193 root 1.164
1194 root 1.323 The fastest ping in the west.
1195 root 1.101
1196     =item L<Coro>
1197    
1198 root 1.108 Has special support for AnyEvent via L<Coro::AnyEvent>.
1199 root 1.101
1200 elmex 1.100 =back
1201    
1202 root 1.1 =cut
1203    
1204     package AnyEvent;
1205    
1206 root 1.243 # basically a tuned-down version of common::sense
1207     sub common_sense {
1208 root 1.346 # from common:.sense 3.4
1209     ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "\x3c\x3f\x33\x00\x0f\xf0\x0f\xc0\xf0\xfc\x33\x00";
1210 root 1.306 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1211 root 1.243 $^H |= 0x00000600;
1212     }
1213    
1214     BEGIN { AnyEvent::common_sense }
1215 root 1.24
1216 root 1.239 use Carp ();
1217 root 1.1
1218 root 1.361 our $VERSION = '6.01';
1219 root 1.2 our $MODEL;
1220 root 1.1
1221 root 1.2 our @ISA;
1222 root 1.1
1223 root 1.135 our @REGISTRY;
1224    
1225 root 1.242 our $VERBOSE;
1226    
1227 root 1.138 BEGIN {
1228 root 1.313 require "AnyEvent/constants.pl";
1229    
1230 root 1.317 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1231 root 1.214
1232     delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1233     if ${^TAINT};
1234 root 1.242
1235     $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1236 root 1.138 }
1237    
1238 root 1.242 our $MAX_SIGNAL_LATENCY = 10;
1239 root 1.7
1240 root 1.136 our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1241 root 1.126
1242     {
1243     my $idx;
1244     $PROTOCOL{$_} = ++$idx
1245 root 1.136 for reverse split /\s*,\s*/,
1246     $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1247 root 1.126 }
1248    
1249 root 1.355 our @post_detect;
1250    
1251     sub post_detect(&) {
1252     my ($cb) = @_;
1253    
1254     push @post_detect, $cb;
1255    
1256     defined wantarray
1257     ? bless \$cb, "AnyEvent::Util::postdetect"
1258     : ()
1259     }
1260    
1261     sub AnyEvent::Util::postdetect::DESTROY {
1262     @post_detect = grep $_ != ${$_[0]}, @post_detect;
1263     }
1264    
1265     our $POSTPONE_W;
1266     our @POSTPONE;
1267    
1268     sub _postpone_exec {
1269     undef $POSTPONE_W;
1270    
1271     &{ shift @POSTPONE }
1272     while @POSTPONE;
1273     }
1274    
1275     sub postpone(&) {
1276     push @POSTPONE, shift;
1277    
1278     $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1279    
1280     ()
1281     }
1282    
1283 root 1.365 sub log($$;@) {
1284     require AnyEvent::Log;
1285     # AnyEvent::Log overwrites this function
1286     goto &log;
1287     }
1288    
1289 root 1.355 our @models = (
1290 root 1.254 [EV:: => AnyEvent::Impl::EV:: , 1],
1291 root 1.352 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
1292 root 1.254 # everything below here will not (normally) be autoprobed
1293 root 1.352 # as the pure perl backend should work everywhere
1294 root 1.135 # and is usually faster
1295 root 1.276 [Event:: => AnyEvent::Impl::Event::, 1],
1296 root 1.254 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1297 root 1.61 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1298 root 1.254 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1299 root 1.232 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1300 root 1.237 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1301 root 1.232 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1302 root 1.135 [Wx:: => AnyEvent::Impl::POE::],
1303     [Prima:: => AnyEvent::Impl::POE::],
1304 root 1.355 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1305 root 1.344 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1306 root 1.356 [FLTK:: => AnyEvent::Impl::FLTK2::],
1307 root 1.1 );
1308    
1309 root 1.361 our @isa_hook;
1310    
1311     sub _isa_set {
1312 root 1.362 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1313 root 1.361
1314     @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1315     for 1 .. $#pkg;
1316    
1317 root 1.362 grep $_ && $_->[1], @isa_hook
1318 root 1.361 and AE::_reset ();
1319     }
1320    
1321     # used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1322     sub _isa_hook($$;$) {
1323     my ($i, $pkg, $reset_ae) = @_;
1324    
1325 root 1.362 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1326 root 1.361
1327     _isa_set;
1328     }
1329    
1330 root 1.357 # all autoloaded methods reserve the complete glob, not just the method slot.
1331     # due to bugs in perls method cache implementation.
1332     our @methods = qw(io timer time now now_update signal child idle condvar);
1333    
1334 root 1.19 sub detect() {
1335 root 1.363 return $MODEL if $MODEL; # some programs keep references to detect
1336    
1337 root 1.357 local $!; # for good measure
1338     local $SIG{__DIE__}; # we use eval
1339    
1340 root 1.312 # free some memory
1341     *detect = sub () { $MODEL };
1342 root 1.357 # undef &func doesn't correctly update the method cache. grmbl.
1343     # so we delete the whole glob. grmbl.
1344     # otoh, perl doesn't let me undef an active usb, but it lets me free
1345     # a glob with an active sub. hrm. i hope it works, but perl is
1346     # usually buggy in this department. sigh.
1347     delete @{"AnyEvent::"}{@methods};
1348     undef @methods;
1349 root 1.312
1350 root 1.355 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1351     my $model = $1;
1352     $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1353 root 1.312 if (eval "require $model") {
1354     $MODEL = $model;
1355 root 1.365 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."
1356     if $VERBOSE >= 7;
1357 root 1.312 } else {
1358 root 1.365 AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1359 root 1.312 }
1360     }
1361    
1362     # check for already loaded models
1363 root 1.19 unless ($MODEL) {
1364 root 1.312 for (@REGISTRY, @models) {
1365     my ($package, $model) = @$_;
1366     if (${"$package\::VERSION"} > 0) {
1367     if (eval "require $model") {
1368     $MODEL = $model;
1369 root 1.365 AnyEvent::log 7 => "autodetected model '$model', using it."
1370     if $VERBOSE >= 7;
1371 root 1.312 last;
1372     }
1373 root 1.2 }
1374 root 1.1 }
1375    
1376 root 1.2 unless ($MODEL) {
1377 root 1.312 # try to autoload a model
1378 root 1.61 for (@REGISTRY, @models) {
1379 root 1.312 my ($package, $model, $autoload) = @$_;
1380     if (
1381     $autoload
1382     and eval "require $package"
1383     and ${"$package\::VERSION"} > 0
1384     and eval "require $model"
1385     ) {
1386     $MODEL = $model;
1387 root 1.365 AnyEvent::log 7 => "autoloaded model '$model', using it."
1388     if $VERBOSE >= 7;
1389 root 1.312 last;
1390 root 1.8 }
1391 root 1.2 }
1392    
1393 root 1.312 $MODEL
1394 root 1.365 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1395 root 1.1 }
1396 root 1.312 }
1397 root 1.19
1398 root 1.355 # free memory only needed for probing
1399     undef @models;
1400     undef @REGISTRY;
1401 root 1.108
1402 root 1.312 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1403 root 1.168
1404 root 1.338 # now nuke some methods that are overridden by the backend.
1405 root 1.355 # SUPER usage is not allowed in these.
1406 root 1.317 for (qw(time signal child idle)) {
1407     undef &{"AnyEvent::Base::$_"}
1408     if defined &{"$MODEL\::$_"};
1409     }
1410    
1411 root 1.361 _isa_set;
1412    
1413 root 1.339 if ($ENV{PERL_ANYEVENT_STRICT}) {
1414 root 1.357 require AnyEvent::Strict;
1415     }
1416    
1417     if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1418     require AnyEvent::Debug;
1419     AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1420     }
1421    
1422     if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1423 root 1.358 require AnyEvent::Socket;
1424 root 1.357 require AnyEvent::Debug;
1425 root 1.358
1426 root 1.359 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1427     $shell =~ s/\$\$/$$/g;
1428    
1429     my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1430 root 1.358 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1431 root 1.339 }
1432 root 1.167
1433 root 1.312 (shift @post_detect)->() while @post_detect;
1434 root 1.355 undef @post_detect;
1435 root 1.1
1436 root 1.317 *post_detect = sub(&) {
1437     shift->();
1438    
1439     undef
1440     };
1441    
1442 root 1.19 $MODEL
1443     }
1444    
1445 root 1.357 for my $name (@methods) {
1446     *$name = sub {
1447     detect;
1448     # we use goto because
1449     # a) it makes the thunk more transparent
1450     # b) it allows us to delete the thunk later
1451     goto &{ UNIVERSAL::can AnyEvent => "SUPER::$name" }
1452     };
1453 root 1.1 }
1454    
1455 root 1.169 # utility function to dup a filehandle. this is used by many backends
1456     # to support binding more than one watcher per filehandle (they usually
1457     # allow only one watcher per fd, so we dup it to get a different one).
1458 root 1.219 sub _dupfh($$;$$) {
1459 root 1.169 my ($poll, $fh, $r, $w) = @_;
1460    
1461     # cygwin requires the fh mode to be matching, unix doesn't
1462 root 1.241 my ($rw, $mode) = $poll eq "r" ? ($r, "<&") : ($w, ">&");
1463 root 1.169
1464 root 1.241 open my $fh2, $mode, $fh
1465 root 1.229 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1466 root 1.169
1467     # we assume CLOEXEC is already set by perl in all important cases
1468    
1469     ($fh2, $rw)
1470     }
1471    
1472 root 1.278 =head1 SIMPLIFIED AE API
1473    
1474     Starting with version 5.0, AnyEvent officially supports a second, much
1475     simpler, API that is designed to reduce the calling, typing and memory
1476 root 1.318 overhead by using function call syntax and a fixed number of parameters.
1477 root 1.278
1478     See the L<AE> manpage for details.
1479    
1480     =cut
1481 root 1.273
1482     package AE;
1483    
1484 root 1.275 our $VERSION = $AnyEvent::VERSION;
1485    
1486 root 1.355 sub _reset() {
1487     eval q{
1488     # fall back to the main API by default - backends and AnyEvent::Base
1489     # implementations can overwrite these.
1490    
1491     sub io($$$) {
1492     AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1493     }
1494    
1495     sub timer($$$) {
1496     AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1497     }
1498 root 1.273
1499 root 1.355 sub signal($$) {
1500     AnyEvent->signal (signal => $_[0], cb => $_[1])
1501     }
1502 root 1.273
1503 root 1.355 sub child($$) {
1504     AnyEvent->child (pid => $_[0], cb => $_[1])
1505     }
1506 root 1.273
1507 root 1.355 sub idle($) {
1508 root 1.357 AnyEvent->idle (cb => $_[0]);
1509 root 1.355 }
1510 root 1.273
1511 root 1.355 sub cv(;&) {
1512     AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1513     }
1514 root 1.273
1515 root 1.355 sub now() {
1516     AnyEvent->now
1517     }
1518 root 1.273
1519 root 1.355 sub now_update() {
1520     AnyEvent->now_update
1521     }
1522 root 1.273
1523 root 1.355 sub time() {
1524     AnyEvent->time
1525     }
1526 root 1.273
1527 root 1.355 *postpone = \&AnyEvent::postpone;
1528 root 1.365 *log = \&AnyEvent::log;
1529 root 1.355 };
1530     die if $@;
1531 root 1.273 }
1532    
1533 root 1.355 BEGIN { _reset }
1534 root 1.354
1535 root 1.19 package AnyEvent::Base;
1536    
1537 root 1.205 # default implementations for many methods
1538 root 1.143
1539 root 1.317 sub time {
1540     eval q{ # poor man's autoloading {}
1541 root 1.312 # probe for availability of Time::HiRes
1542     if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1543 root 1.365 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy."
1544     if $AnyEvent::VERBOSE >= 8;
1545 root 1.361 *time = sub { Time::HiRes::time () };
1546     *AE::time = \& Time::HiRes::time ;
1547 root 1.312 # if (eval "use POSIX (); (POSIX::times())...
1548     } else {
1549 root 1.365 AnyEvent::log critical => "using built-in time(), WARNING, no sub-second resolution!";
1550 root 1.361 *time = sub { CORE::time };
1551     *AE::time = sub (){ CORE::time };
1552 root 1.312 }
1553 root 1.317
1554 root 1.361 *now = \&time;
1555 root 1.312 };
1556     die if $@;
1557 root 1.242
1558 root 1.317 &time
1559 root 1.179 }
1560 root 1.143
1561 root 1.317 *now = \&time;
1562 root 1.205 sub now_update { }
1563 root 1.143
1564 root 1.352 sub _poll {
1565     Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1566     }
1567    
1568 root 1.114 # default implementation for ->condvar
1569 root 1.353 # in fact, the default should not be overwritten
1570 root 1.20
1571     sub condvar {
1572 root 1.317 eval q{ # poor man's autoloading {}
1573     *condvar = sub {
1574     bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1575     };
1576    
1577     *AE::cv = sub (;&) {
1578     bless { @_ ? (_ae_cb => shift) : () }, "AnyEvent::CondVar"
1579     };
1580     };
1581     die if $@;
1582    
1583     &condvar
1584 root 1.20 }
1585    
1586     # default implementation for ->signal
1587 root 1.19
1588 root 1.242 our $HAVE_ASYNC_INTERRUPT;
1589 root 1.263
1590     sub _have_async_interrupt() {
1591     $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT}
1592 root 1.289 && eval "use Async::Interrupt 1.02 (); 1")
1593 root 1.263 unless defined $HAVE_ASYNC_INTERRUPT;
1594    
1595     $HAVE_ASYNC_INTERRUPT
1596     }
1597    
1598 root 1.195 our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1599 root 1.242 our (%SIG_ASY, %SIG_ASY_W);
1600     our ($SIG_COUNT, $SIG_TW);
1601 root 1.195
1602 root 1.261 # install a dummy wakeup watcher to reduce signal catching latency
1603 root 1.312 # used by Impls
1604 root 1.246 sub _sig_add() {
1605     unless ($SIG_COUNT++) {
1606     # try to align timer on a full-second boundary, if possible
1607 root 1.273 my $NOW = AE::now;
1608 root 1.246
1609 root 1.273 $SIG_TW = AE::timer
1610     $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1611     $MAX_SIGNAL_LATENCY,
1612     sub { } # just for the PERL_ASYNC_CHECK
1613     ;
1614 root 1.246 }
1615     }
1616    
1617     sub _sig_del {
1618     undef $SIG_TW
1619     unless --$SIG_COUNT;
1620     }
1621    
1622 root 1.263 our $_sig_name_init; $_sig_name_init = sub {
1623 root 1.317 eval q{ # poor man's autoloading {}
1624 root 1.265 undef $_sig_name_init;
1625 root 1.263
1626 root 1.265 if (_have_async_interrupt) {
1627     *sig2num = \&Async::Interrupt::sig2num;
1628     *sig2name = \&Async::Interrupt::sig2name;
1629     } else {
1630     require Config;
1631 root 1.264
1632 root 1.265 my %signame2num;
1633     @signame2num{ split ' ', $Config::Config{sig_name} }
1634     = split ' ', $Config::Config{sig_num};
1635    
1636     my @signum2name;
1637     @signum2name[values %signame2num] = keys %signame2num;
1638    
1639     *sig2num = sub($) {
1640     $_[0] > 0 ? shift : $signame2num{+shift}
1641     };
1642     *sig2name = sub ($) {
1643     $_[0] > 0 ? $signum2name[+shift] : shift
1644     };
1645     }
1646     };
1647     die if $@;
1648 root 1.263 };
1649    
1650     sub sig2num ($) { &$_sig_name_init; &sig2num }
1651     sub sig2name($) { &$_sig_name_init; &sig2name }
1652    
1653 root 1.265 sub signal {
1654     eval q{ # poor man's autoloading {}
1655     # probe for availability of Async::Interrupt
1656     if (_have_async_interrupt) {
1657 root 1.365 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling."
1658     if $AnyEvent::VERBOSE >= 8;
1659 root 1.265
1660     $SIGPIPE_R = new Async::Interrupt::EventPipe;
1661 root 1.273 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1662 root 1.242
1663 root 1.265 } else {
1664 root 1.365 AnyEvent::log 8 => "using emulated perl signal handling with latency timer."
1665     if $AnyEvent::VERBOSE >= 8;
1666 root 1.242
1667 root 1.265 if (AnyEvent::WIN32) {
1668     require AnyEvent::Util;
1669 root 1.261
1670 root 1.265 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1671     AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
1672     AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case
1673     } else {
1674     pipe $SIGPIPE_R, $SIGPIPE_W;
1675 root 1.313 fcntl $SIGPIPE_R, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_R;
1676     fcntl $SIGPIPE_W, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_W; # just in case
1677 root 1.265
1678     # not strictly required, as $^F is normally 2, but let's make sure...
1679 root 1.313 fcntl $SIGPIPE_R, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1680     fcntl $SIGPIPE_W, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1681 root 1.265 }
1682 root 1.242
1683 root 1.265 $SIGPIPE_R
1684     or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1685 root 1.242
1686 root 1.273 $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;
1687 root 1.265 }
1688 root 1.242
1689 root 1.317 *signal = $HAVE_ASYNC_INTERRUPT
1690     ? sub {
1691     my (undef, %arg) = @_;
1692    
1693     # async::interrupt
1694     my $signal = sig2num $arg{signal};
1695     $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1696    
1697     $SIG_ASY{$signal} ||= new Async::Interrupt
1698     cb => sub { undef $SIG_EV{$signal} },
1699     signal => $signal,
1700     pipe => [$SIGPIPE_R->filenos],
1701     pipe_autodrain => 0,
1702     ;
1703    
1704     bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1705     }
1706     : sub {
1707     my (undef, %arg) = @_;
1708    
1709     # pure perl
1710     my $signal = sig2name $arg{signal};
1711     $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1712    
1713     $SIG{$signal} ||= sub {
1714     local $!;
1715     syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1716     undef $SIG_EV{$signal};
1717     };
1718    
1719     # can't do signal processing without introducing races in pure perl,
1720     # so limit the signal latency.
1721     _sig_add;
1722 root 1.242
1723 root 1.317 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1724     }
1725     ;
1726 root 1.200
1727 root 1.265 *AnyEvent::Base::signal::DESTROY = sub {
1728     my ($signal, $cb) = @{$_[0]};
1729 root 1.195
1730 root 1.265 _sig_del;
1731 root 1.195
1732 root 1.265 delete $SIG_CB{$signal}{$cb};
1733 root 1.195
1734 root 1.265 $HAVE_ASYNC_INTERRUPT
1735     ? delete $SIG_ASY{$signal}
1736     : # delete doesn't work with older perls - they then
1737     # print weird messages, or just unconditionally exit
1738     # instead of getting the default action.
1739     undef $SIG{$signal}
1740     unless keys %{ $SIG_CB{$signal} };
1741     };
1742 root 1.312
1743     *_signal_exec = sub {
1744     $HAVE_ASYNC_INTERRUPT
1745     ? $SIGPIPE_R->drain
1746     : sysread $SIGPIPE_R, (my $dummy), 9;
1747    
1748     while (%SIG_EV) {
1749     for (keys %SIG_EV) {
1750     delete $SIG_EV{$_};
1751 root 1.355 &$_ for values %{ $SIG_CB{$_} || {} };
1752 root 1.312 }
1753     }
1754     };
1755 root 1.265 };
1756     die if $@;
1757 root 1.312
1758 root 1.242 &signal
1759 root 1.19 }
1760    
1761 root 1.20 # default implementation for ->child
1762    
1763     our %PID_CB;
1764     our $CHLD_W;
1765 root 1.37 our $CHLD_DELAY_W;
1766 root 1.20
1767 root 1.312 # used by many Impl's
1768 root 1.254 sub _emit_childstatus($$) {
1769     my (undef, $rpid, $rstatus) = @_;
1770    
1771     $_->($rpid, $rstatus)
1772     for values %{ $PID_CB{$rpid} || {} },
1773     values %{ $PID_CB{0} || {} };
1774     }
1775    
1776 root 1.312 sub child {
1777     eval q{ # poor man's autoloading {}
1778     *_sigchld = sub {
1779     my $pid;
1780 root 1.254
1781 root 1.312 AnyEvent->_emit_childstatus ($pid, $?)
1782 root 1.341 while ($pid = waitpid -1, WNOHANG) > 0;
1783 root 1.312 };
1784 root 1.37
1785 root 1.312 *child = sub {
1786     my (undef, %arg) = @_;
1787 root 1.20
1788 root 1.351 my $pid = $arg{pid};
1789     my $cb = $arg{cb};
1790 root 1.20
1791 root 1.351 $PID_CB{$pid}{$cb+0} = $cb;
1792 root 1.20
1793 root 1.312 unless ($CHLD_W) {
1794     $CHLD_W = AE::signal CHLD => \&_sigchld;
1795     # child could be a zombie already, so make at least one round
1796     &_sigchld;
1797     }
1798 root 1.20
1799 root 1.351 bless [$pid, $cb+0], "AnyEvent::Base::child"
1800 root 1.312 };
1801 root 1.20
1802 root 1.312 *AnyEvent::Base::child::DESTROY = sub {
1803 root 1.351 my ($pid, $icb) = @{$_[0]};
1804 root 1.20
1805 root 1.351 delete $PID_CB{$pid}{$icb};
1806 root 1.312 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1807 root 1.20
1808 root 1.312 undef $CHLD_W unless keys %PID_CB;
1809     };
1810     };
1811     die if $@;
1812    
1813     &child
1814 root 1.20 }
1815    
1816 root 1.207 # idle emulation is done by simply using a timer, regardless
1817 root 1.210 # of whether the process is idle or not, and not letting
1818 root 1.207 # the callback use more than 50% of the time.
1819     sub idle {
1820 root 1.312 eval q{ # poor man's autoloading {}
1821     *idle = sub {
1822     my (undef, %arg) = @_;
1823 root 1.207
1824 root 1.312 my ($cb, $w, $rcb) = $arg{cb};
1825 root 1.207
1826 root 1.312 $rcb = sub {
1827     if ($cb) {
1828 root 1.356 $w = AE::time;
1829 root 1.312 &$cb;
1830 root 1.356 $w = AE::time - $w;
1831 root 1.312
1832     # never use more then 50% of the time for the idle watcher,
1833     # within some limits
1834     $w = 0.0001 if $w < 0.0001;
1835     $w = 5 if $w > 5;
1836    
1837     $w = AE::timer $w, 0, $rcb;
1838     } else {
1839     # clean up...
1840     undef $w;
1841     undef $rcb;
1842     }
1843     };
1844 root 1.207
1845 root 1.312 $w = AE::timer 0.05, 0, $rcb;
1846 root 1.207
1847 root 1.312 bless \\$cb, "AnyEvent::Base::idle"
1848     };
1849 root 1.207
1850 root 1.312 *AnyEvent::Base::idle::DESTROY = sub {
1851     undef $${$_[0]};
1852     };
1853     };
1854     die if $@;
1855 root 1.207
1856 root 1.312 &idle
1857 root 1.207 }
1858    
1859 root 1.116 package AnyEvent::CondVar;
1860    
1861     our @ISA = AnyEvent::CondVar::Base::;
1862    
1863 root 1.333 # only to be used for subclassing
1864     sub new {
1865     my $class = shift;
1866     bless AnyEvent->condvar (@_), $class
1867     }
1868    
1869 root 1.116 package AnyEvent::CondVar::Base;
1870 root 1.114
1871 root 1.243 #use overload
1872     # '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1873     # fallback => 1;
1874    
1875     # save 300+ kilobytes by dirtily hardcoding overloading
1876     ${"AnyEvent::CondVar::Base::OVERLOAD"}{dummy}++; # Register with magic by touching.
1877     *{'AnyEvent::CondVar::Base::()'} = sub { }; # "Make it findable via fetchmethod."
1878     *{'AnyEvent::CondVar::Base::(&{}'} = sub { my $self = shift; sub { $self->send (@_) } }; # &{}
1879     ${'AnyEvent::CondVar::Base::()'} = 1; # fallback
1880 root 1.131
1881 root 1.239 our $WAITING;
1882    
1883 root 1.114 sub _send {
1884 root 1.116 # nop
1885 root 1.114 }
1886    
1887 root 1.350 sub _wait {
1888 root 1.352 AnyEvent->_poll until $_[0]{_ae_sent};
1889 root 1.350 }
1890    
1891 root 1.114 sub send {
1892 root 1.115 my $cv = shift;
1893     $cv->{_ae_sent} = [@_];
1894 root 1.116 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
1895 root 1.115 $cv->_send;
1896 root 1.114 }
1897    
1898     sub croak {
1899 root 1.115 $_[0]{_ae_croak} = $_[1];
1900 root 1.114 $_[0]->send;
1901     }
1902    
1903     sub ready {
1904     $_[0]{_ae_sent}
1905     }
1906    
1907 root 1.350 sub recv {
1908     unless ($_[0]{_ae_sent}) {
1909     $WAITING
1910 root 1.352 and Carp::croak "AnyEvent::CondVar: recursive blocking wait attempted";
1911 root 1.239
1912 root 1.350 local $WAITING = 1;
1913     $_[0]->_wait;
1914     }
1915 root 1.116
1916 root 1.350 $_[0]{_ae_croak}
1917     and Carp::croak $_[0]{_ae_croak};
1918 root 1.114
1919 root 1.350 wantarray
1920     ? @{ $_[0]{_ae_sent} }
1921     : $_[0]{_ae_sent}[0]
1922 root 1.114 }
1923    
1924     sub cb {
1925 root 1.269 my $cv = shift;
1926    
1927     @_
1928     and $cv->{_ae_cb} = shift
1929     and $cv->{_ae_sent}
1930     and (delete $cv->{_ae_cb})->($cv);
1931 root 1.270
1932 root 1.269 $cv->{_ae_cb}
1933 root 1.114 }
1934    
1935     sub begin {
1936     ++$_[0]{_ae_counter};
1937     $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
1938     }
1939    
1940     sub end {
1941     return if --$_[0]{_ae_counter};
1942 root 1.124 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
1943 root 1.114 }
1944    
1945     # undocumented/compatibility with pre-3.4
1946     *broadcast = \&send;
1947 root 1.350 *wait = \&recv;
1948 root 1.114
1949 root 1.180 =head1 ERROR AND EXCEPTION HANDLING
1950 root 1.53
1951 root 1.180 In general, AnyEvent does not do any error handling - it relies on the
1952     caller to do that if required. The L<AnyEvent::Strict> module (see also
1953     the C<PERL_ANYEVENT_STRICT> environment variable, below) provides strict
1954     checking of all AnyEvent methods, however, which is highly useful during
1955     development.
1956    
1957     As for exception handling (i.e. runtime errors and exceptions thrown while
1958     executing a callback), this is not only highly event-loop specific, but
1959     also not in any way wrapped by this module, as this is the job of the main
1960     program.
1961    
1962     The pure perl event loop simply re-throws the exception (usually
1963     within C<< condvar->recv >>), the L<Event> and L<EV> modules call C<<
1964     $Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1965     so on.
1966 root 1.12
1967 root 1.7 =head1 ENVIRONMENT VARIABLES
1968    
1969 root 1.180 The following environment variables are used by this module or its
1970 root 1.214 submodules.
1971    
1972     Note that AnyEvent will remove I<all> environment variables starting with
1973     C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
1974     enabled.
1975 root 1.7
1976 root 1.55 =over 4
1977    
1978     =item C<PERL_ANYEVENT_VERBOSE>
1979    
1980 root 1.60 By default, AnyEvent will be completely silent except in fatal
1981     conditions. You can set this environment variable to make AnyEvent more
1982     talkative.
1983    
1984 root 1.365 When set to C<5> or higher, causes AnyEvent to warn about unexpected
1985 root 1.60 conditions, such as not being able to load the event model specified by
1986     C<PERL_ANYEVENT_MODEL>.
1987    
1988 root 1.365 When set to C<7> or higher, cause AnyEvent to report to STDERR which event
1989 root 1.55 model it chooses.
1990    
1991 root 1.244 When set to C<8> or higher, then AnyEvent will report extra information on
1992     which optional modules it loads and how it implements certain features.
1993    
1994 root 1.167 =item C<PERL_ANYEVENT_STRICT>
1995    
1996     AnyEvent does not do much argument checking by default, as thorough
1997     argument checking is very costly. Setting this variable to a true value
1998 root 1.170 will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1999 root 1.218 check the arguments passed to most method calls. If it finds any problems,
2000 root 1.170 it will croak.
2001    
2002     In other words, enables "strict" mode.
2003    
2004 root 1.330 Unlike C<use strict> (or its modern cousin, C<< use L<common::sense>
2005 root 1.243 >>, it is definitely recommended to keep it off in production. Keeping
2006     C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
2007     can be very useful, however.
2008 root 1.167
2009 root 1.358 =item C<PERL_ANYEVENT_DEBUG_SHELL>
2010    
2011 root 1.359 If this env variable is set, then its contents will be interpreted by
2012     C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
2013     C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
2014     that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
2015    
2016     This takes place when the first watcher is created.
2017 root 1.358
2018     For example, to bind a debug shell on a unix domain socket in
2019 root 1.359 F<< /tmp/debug<pid>.sock >>, you could use this:
2020    
2021 root 1.364 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2022 root 1.358
2023 root 1.359 Note that creating sockets in F</tmp> is very unsafe on multiuser
2024     systems.
2025 root 1.358
2026     =item C<PERL_ANYEVENT_DEBUG_WRAP>
2027    
2028     Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2029     debugging purposes. See C<AnyEvent::Debug::wrap> for details.
2030    
2031 root 1.55 =item C<PERL_ANYEVENT_MODEL>
2032    
2033     This can be used to specify the event model to be used by AnyEvent, before
2034 root 1.355 auto detection and -probing kicks in.
2035    
2036     It normally is a string consisting entirely of ASCII letters (e.g. C<EV>
2037     or C<IOAsync>). The string C<AnyEvent::Impl::> gets prepended and the
2038     resulting module name is loaded and - if the load was successful - used as
2039     event model backend. If it fails to load then AnyEvent will proceed with
2040 root 1.128 auto detection and -probing.
2041 root 1.55
2042 root 1.355 If the string ends with C<::> instead (e.g. C<AnyEvent::Impl::EV::>) then
2043     nothing gets prepended and the module name is used as-is (hint: C<::> at
2044     the end of a string designates a module name and quotes it appropriately).
2045 root 1.55
2046 root 1.352 For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
2047 root 1.55 could start your program like this:
2048    
2049 root 1.151 PERL_ANYEVENT_MODEL=Perl perl ...
2050 root 1.55
2051 root 1.125 =item C<PERL_ANYEVENT_PROTOCOLS>
2052    
2053     Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
2054     for IPv4 or IPv6. The default is unspecified (and might change, or be the result
2055 root 1.128 of auto probing).
2056 root 1.125
2057     Must be set to a comma-separated list of protocols or address families,
2058     current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
2059     used, and preference will be given to protocols mentioned earlier in the
2060     list.
2061    
2062 root 1.127 This variable can effectively be used for denial-of-service attacks
2063     against local programs (e.g. when setuid), although the impact is likely
2064 root 1.194 small, as the program has to handle conenction and other failures anyways.
2065 root 1.127
2066 root 1.125 Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
2067     but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2068     - only support IPv4, never try to resolve or contact IPv6
2069 root 1.128 addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2070 root 1.125 IPv6, but prefer IPv6 over IPv4.
2071    
2072 root 1.127 =item C<PERL_ANYEVENT_EDNS0>
2073    
2074 root 1.128 Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
2075 root 1.127 for DNS. This extension is generally useful to reduce DNS traffic, but
2076     some (broken) firewalls drop such DNS packets, which is why it is off by
2077     default.
2078    
2079     Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2080     EDNS0 in its DNS requests.
2081    
2082 root 1.142 =item C<PERL_ANYEVENT_MAX_FORKS>
2083    
2084     The maximum number of child processes that C<AnyEvent::Util::fork_call>
2085     will create in parallel.
2086    
2087 root 1.226 =item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
2088    
2089     The default value for the C<max_outstanding> parameter for the default DNS
2090     resolver - this is the maximum number of parallel DNS requests that are
2091     sent to the DNS server.
2092    
2093     =item C<PERL_ANYEVENT_RESOLV_CONF>
2094    
2095     The file to use instead of F</etc/resolv.conf> (or OS-specific
2096     configuration) in the default resolver. When set to the empty string, no
2097     default config will be used.
2098    
2099 root 1.227 =item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2100    
2101     When neither C<ca_file> nor C<ca_path> was specified during
2102     L<AnyEvent::TLS> context creation, and either of these environment
2103     variables exist, they will be used to specify CA certificate locations
2104     instead of a system-dependent default.
2105    
2106 root 1.244 =item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2107    
2108     When these are set to C<1>, then the respective modules are not
2109     loaded. Mostly good for testing AnyEvent itself.
2110    
2111 root 1.55 =back
2112 root 1.7
2113 root 1.180 =head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
2114    
2115     This is an advanced topic that you do not normally need to use AnyEvent in
2116     a module. This section is only of use to event loop authors who want to
2117     provide AnyEvent compatibility.
2118    
2119     If you need to support another event library which isn't directly
2120     supported by AnyEvent, you can supply your own interface to it by
2121     pushing, before the first watcher gets created, the package name of
2122     the event module and the package name of the interface to use onto
2123     C<@AnyEvent::REGISTRY>. You can do that before and even without loading
2124     AnyEvent, so it is reasonably cheap.
2125    
2126     Example:
2127    
2128     push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
2129    
2130     This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
2131     package/class when it finds the C<urxvt> package/module is already loaded.
2132    
2133     When AnyEvent is loaded and asked to find a suitable event model, it
2134     will first check for the presence of urxvt by trying to C<use> the
2135     C<urxvt::anyevent> module.
2136    
2137     The class should provide implementations for all watcher types. See
2138     L<AnyEvent::Impl::EV> (source code), L<AnyEvent::Impl::Glib> (Source code)
2139     and so on for actual examples. Use C<perldoc -m AnyEvent::Impl::Glib> to
2140     see the sources.
2141    
2142     If you don't provide C<signal> and C<child> watchers than AnyEvent will
2143     provide suitable (hopefully) replacements.
2144    
2145     The above example isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
2146     terminal emulator uses the above line as-is. An interface isn't included
2147     in AnyEvent because it doesn't make sense outside the embedded interpreter
2148     inside I<rxvt-unicode>, and it is updated and maintained as part of the
2149     I<rxvt-unicode> distribution.
2150    
2151     I<rxvt-unicode> also cheats a bit by not providing blocking access to
2152     condition variables: code blocking while waiting for a condition will
2153     C<die>. This still works with most modules/usages, and blocking calls must
2154     not be done in an interactive application, so it makes sense.
2155    
2156 root 1.53 =head1 EXAMPLE PROGRAM
2157 root 1.2
2158 root 1.78 The following program uses an I/O watcher to read data from STDIN, a timer
2159 root 1.53 to display a message once per second, and a condition variable to quit the
2160     program when the user enters quit:
2161 root 1.2
2162     use AnyEvent;
2163    
2164     my $cv = AnyEvent->condvar;
2165    
2166 root 1.53 my $io_watcher = AnyEvent->io (
2167     fh => \*STDIN,
2168     poll => 'r',
2169     cb => sub {
2170     warn "io event <$_[0]>\n"; # will always output <r>
2171     chomp (my $input = <STDIN>); # read a line
2172     warn "read: $input\n"; # output what has been read
2173 root 1.118 $cv->send if $input =~ /^q/i; # quit program if /^q/i
2174 root 1.53 },
2175     );
2176 root 1.2
2177 root 1.287 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
2178     warn "timeout\n"; # print 'timeout' at most every second
2179     });
2180 root 1.2
2181 root 1.118 $cv->recv; # wait until user enters /^q/i
2182 root 1.2
2183 root 1.5 =head1 REAL-WORLD EXAMPLE
2184    
2185     Consider the L<Net::FCP> module. It features (among others) the following
2186     API calls, which are to freenet what HTTP GET requests are to http:
2187    
2188     my $data = $fcp->client_get ($url); # blocks
2189    
2190     my $transaction = $fcp->txn_client_get ($url); # does not block
2191     $transaction->cb ( sub { ... } ); # set optional result callback
2192     my $data = $transaction->result; # possibly blocks
2193    
2194     The C<client_get> method works like C<LWP::Simple::get>: it requests the
2195     given URL and waits till the data has arrived. It is defined to be:
2196    
2197     sub client_get { $_[0]->txn_client_get ($_[1])->result }
2198    
2199     And in fact is automatically generated. This is the blocking API of
2200     L<Net::FCP>, and it works as simple as in any other, similar, module.
2201    
2202     More complicated is C<txn_client_get>: It only creates a transaction
2203     (completion, result, ...) object and initiates the transaction.
2204    
2205     my $txn = bless { }, Net::FCP::Txn::;
2206    
2207     It also creates a condition variable that is used to signal the completion
2208     of the request:
2209    
2210     $txn->{finished} = AnyAvent->condvar;
2211    
2212     It then creates a socket in non-blocking mode.
2213    
2214     socket $txn->{fh}, ...;
2215     fcntl $txn->{fh}, F_SETFL, O_NONBLOCK;
2216     connect $txn->{fh}, ...
2217     and !$!{EWOULDBLOCK}
2218     and !$!{EINPROGRESS}
2219     and Carp::croak "unable to connect: $!\n";
2220    
2221 root 1.6 Then it creates a write-watcher which gets called whenever an error occurs
2222 root 1.5 or the connection succeeds:
2223    
2224     $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });
2225    
2226     And returns this transaction object. The C<fh_ready_w> callback gets
2227     called as soon as the event loop detects that the socket is ready for
2228     writing.
2229    
2230     The C<fh_ready_w> method makes the socket blocking again, writes the
2231     request data and replaces the watcher by a read watcher (waiting for reply
2232     data). The actual code is more complicated, but that doesn't matter for
2233     this example:
2234    
2235     fcntl $txn->{fh}, F_SETFL, 0;
2236     syswrite $txn->{fh}, $txn->{request}
2237     or die "connection or write error";
2238     $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
2239    
2240     Again, C<fh_ready_r> waits till all data has arrived, and then stores the
2241 root 1.128 result and signals any possible waiters that the request has finished:
2242 root 1.5
2243     sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
2244    
2245     if (end-of-file or data complete) {
2246     $txn->{result} = $txn->{buf};
2247 root 1.118 $txn->{finished}->send;
2248 root 1.6 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
2249 root 1.5 }
2250    
2251     The C<result> method, finally, just waits for the finished signal (if the
2252     request was already finished, it doesn't wait, of course, and returns the
2253     data:
2254    
2255 root 1.118 $txn->{finished}->recv;
2256 root 1.6 return $txn->{result};
2257 root 1.5
2258     The actual code goes further and collects all errors (C<die>s, exceptions)
2259 root 1.128 that occurred during request processing. The C<result> method detects
2260 root 1.52 whether an exception as thrown (it is stored inside the $txn object)
2261 root 1.5 and just throws the exception, which means connection errors and other
2262 root 1.318 problems get reported to the code that tries to use the result, not in a
2263 root 1.5 random callback.
2264    
2265     All of this enables the following usage styles:
2266    
2267     1. Blocking:
2268    
2269     my $data = $fcp->client_get ($url);
2270    
2271 root 1.49 2. Blocking, but running in parallel:
2272 root 1.5
2273     my @datas = map $_->result,
2274     map $fcp->txn_client_get ($_),
2275     @urls;
2276    
2277     Both blocking examples work without the module user having to know
2278     anything about events.
2279    
2280 root 1.49 3a. Event-based in a main program, using any supported event module:
2281 root 1.5
2282 root 1.49 use EV;
2283 root 1.5
2284     $fcp->txn_client_get ($url)->cb (sub {
2285     my $txn = shift;
2286     my $data = $txn->result;
2287     ...
2288     });
2289    
2290 root 1.49 EV::loop;
2291 root 1.5
2292     3b. The module user could use AnyEvent, too:
2293    
2294     use AnyEvent;
2295    
2296     my $quit = AnyEvent->condvar;
2297    
2298     $fcp->txn_client_get ($url)->cb (sub {
2299     ...
2300 root 1.118 $quit->send;
2301 root 1.5 });
2302    
2303 root 1.118 $quit->recv;
2304 root 1.5
2305 root 1.64
2306 root 1.91 =head1 BENCHMARKS
2307 root 1.64
2308 root 1.65 To give you an idea of the performance and overheads that AnyEvent adds
2309 root 1.91 over the event loops themselves and to give you an impression of the speed
2310     of various event loops I prepared some benchmarks.
2311 root 1.77
2312 root 1.91 =head2 BENCHMARKING ANYEVENT OVERHEAD
2313    
2314     Here is a benchmark of various supported event models used natively and
2315 root 1.128 through AnyEvent. The benchmark creates a lot of timers (with a zero
2316 root 1.91 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
2317     which it is), lets them fire exactly once and destroys them again.
2318    
2319     Source code for this benchmark is found as F<eg/bench> in the AnyEvent
2320 root 1.278 distribution. It uses the L<AE> interface, which makes a real difference
2321     for the EV and Perl backends only.
2322 root 1.91
2323     =head3 Explanation of the columns
2324 root 1.68
2325     I<watcher> is the number of event watchers created/destroyed. Since
2326     different event models feature vastly different performances, each event
2327     loop was given a number of watchers so that overall runtime is acceptable
2328     and similar between tested event loop (and keep them from crashing): Glib
2329     would probably take thousands of years if asked to process the same number
2330     of watchers as EV in this benchmark.
2331    
2332     I<bytes> is the number of bytes (as measured by the resident set size,
2333     RSS) consumed by each watcher. This method of measuring captures both C
2334     and Perl-based overheads.
2335    
2336     I<create> is the time, in microseconds (millionths of seconds), that it
2337     takes to create a single watcher. The callback is a closure shared between
2338     all watchers, to avoid adding memory overhead. That means closure creation
2339     and memory usage is not included in the figures.
2340    
2341     I<invoke> is the time, in microseconds, used to invoke a simple
2342     callback. The callback simply counts down a Perl variable and after it was
2343 root 1.118 invoked "watcher" times, it would C<< ->send >> a condvar once to
2344 root 1.69 signal the end of this phase.
2345 root 1.64
2346 root 1.71 I<destroy> is the time, in microseconds, that it takes to destroy a single
2347 root 1.68 watcher.
2348 root 1.64
2349 root 1.91 =head3 Results
2350 root 1.64
2351 root 1.75 name watchers bytes create invoke destroy comment
2352 root 1.278 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
2353     EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
2354     Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
2355     Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
2356     Event/Event 16000 516 31.16 31.84 0.82 Event native interface
2357     Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
2358     IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
2359     IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
2360     Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
2361     Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
2362     POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
2363     POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
2364 root 1.64
2365 root 1.91 =head3 Discussion
2366 root 1.68
2367     The benchmark does I<not> measure scalability of the event loop very
2368     well. For example, a select-based event loop (such as the pure perl one)
2369     can never compete with an event loop that uses epoll when the number of
2370 root 1.80 file descriptors grows high. In this benchmark, all events become ready at
2371     the same time, so select/poll-based implementations get an unnatural speed
2372     boost.
2373 root 1.68
2374 root 1.95 Also, note that the number of watchers usually has a nonlinear effect on
2375     overall speed, that is, creating twice as many watchers doesn't take twice
2376     the time - usually it takes longer. This puts event loops tested with a
2377     higher number of watchers at a disadvantage.
2378    
2379 root 1.96 To put the range of results into perspective, consider that on the
2380     benchmark machine, handling an event takes roughly 1600 CPU cycles with
2381     EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU
2382     cycles with POE.
2383    
2384 root 1.68 C<EV> is the sole leader regarding speed and memory use, which are both
2385 root 1.278 maximal/minimal, respectively. When using the L<AE> API there is zero
2386     overhead (when going through the AnyEvent API create is about 5-6 times
2387     slower, with other times being equal, so still uses far less memory than
2388     any other event loop and is still faster than Event natively).
2389 root 1.64
2390     The pure perl implementation is hit in a few sweet spots (both the
2391 root 1.86 constant timeout and the use of a single fd hit optimisations in the perl
2392     interpreter and the backend itself). Nevertheless this shows that it
2393     adds very little overhead in itself. Like any select-based backend its
2394     performance becomes really bad with lots of file descriptors (and few of
2395     them active), of course, but this was not subject of this benchmark.
2396 root 1.64
2397 root 1.90 The C<Event> module has a relatively high setup and callback invocation
2398     cost, but overall scores in on the third place.
2399 root 1.64
2400 root 1.220 C<IO::Async> performs admirably well, about on par with C<Event>, even
2401     when using its pure perl backend.
2402    
2403 root 1.90 C<Glib>'s memory usage is quite a bit higher, but it features a
2404 root 1.73 faster callback invocation and overall ends up in the same class as
2405     C<Event>. However, Glib scales extremely badly, doubling the number of
2406     watchers increases the processing time by more than a factor of four,
2407     making it completely unusable when using larger numbers of watchers
2408     (note that only a single file descriptor was used in the benchmark, so
2409     inefficiencies of C<poll> do not account for this).
2410 root 1.64
2411 root 1.73 The C<Tk> adaptor works relatively well. The fact that it crashes with
2412 root 1.64 more than 2000 watchers is a big setback, however, as correctness takes
2413 root 1.68 precedence over speed. Nevertheless, its performance is surprising, as the
2414     file descriptor is dup()ed for each watcher. This shows that the dup()
2415     employed by some adaptors is not a big performance issue (it does incur a
2416 root 1.87 hidden memory cost inside the kernel which is not reflected in the figures
2417     above).
2418 root 1.68
2419 root 1.103 C<POE>, regardless of underlying event loop (whether using its pure perl
2420     select-based backend or the Event module, the POE-EV backend couldn't
2421     be tested because it wasn't working) shows abysmal performance and
2422     memory usage with AnyEvent: Watchers use almost 30 times as much memory
2423     as EV watchers, and 10 times as much memory as Event (the high memory
2424 root 1.87 requirements are caused by requiring a session for each watcher). Watcher
2425     invocation speed is almost 900 times slower than with AnyEvent's pure perl
2426 root 1.103 implementation.
2427    
2428     The design of the POE adaptor class in AnyEvent can not really account
2429     for the performance issues, though, as session creation overhead is
2430     small compared to execution of the state machine, which is coded pretty
2431     optimally within L<AnyEvent::Impl::POE> (and while everybody agrees that
2432     using multiple sessions is not a good approach, especially regarding
2433     memory usage, even the author of POE could not come up with a faster
2434     design).
2435 root 1.72
2436 root 1.91 =head3 Summary
2437 root 1.72
2438 root 1.87 =over 4
2439    
2440 root 1.89 =item * Using EV through AnyEvent is faster than any other event loop
2441     (even when used without AnyEvent), but most event loops have acceptable
2442     performance with or without AnyEvent.
2443 root 1.72
2444 root 1.87 =item * The overhead AnyEvent adds is usually much smaller than the overhead of
2445 root 1.89 the actual event loop, only with extremely fast event loops such as EV
2446 root 1.362 does AnyEvent add significant overhead.
2447 root 1.72
2448 root 1.90 =item * You should avoid POE like the plague if you want performance or
2449 root 1.72 reasonable memory usage.
2450 root 1.64
2451 root 1.87 =back
2452    
2453 root 1.91 =head2 BENCHMARKING THE LARGE SERVER CASE
2454    
2455 root 1.128 This benchmark actually benchmarks the event loop itself. It works by
2456     creating a number of "servers": each server consists of a socket pair, a
2457 root 1.91 timeout watcher that gets reset on activity (but never fires), and an I/O
2458     watcher waiting for input on one side of the socket. Each time the socket
2459     watcher reads a byte it will write that byte to a random other "server".
2460    
2461     The effect is that there will be a lot of I/O watchers, only part of which
2462     are active at any one point (so there is a constant number of active
2463 root 1.128 fds for each loop iteration, but which fds these are is random). The
2464 root 1.91 timeout is reset each time something is read because that reflects how
2465     most timeouts work (and puts extra pressure on the event loops).
2466    
2467 root 1.128 In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
2468 root 1.91 (1%) are active. This mirrors the activity of large servers with many
2469 root 1.92 connections, most of which are idle at any one point in time.
2470 root 1.91
2471     Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
2472 root 1.278 distribution. It uses the L<AE> interface, which makes a real difference
2473     for the EV and Perl backends only.
2474 root 1.91
2475     =head3 Explanation of the columns
2476    
2477     I<sockets> is the number of sockets, and twice the number of "servers" (as
2478 root 1.94 each server has a read and write socket end).
2479 root 1.91
2480 root 1.128 I<create> is the time it takes to create a socket pair (which is
2481 root 1.91 nontrivial) and two watchers: an I/O watcher and a timeout watcher.
2482    
2483     I<request>, the most important value, is the time it takes to handle a
2484     single "request", that is, reading the token from the pipe and forwarding
2485 root 1.93 it to another server. This includes deleting the old timeout and creating
2486     a new one that moves the timeout into the future.
2487 root 1.91
2488     =head3 Results
2489    
2490 root 1.220 name sockets create request
2491 root 1.278 EV 20000 62.66 7.99
2492     Perl 20000 68.32 32.64
2493     IOAsync 20000 174.06 101.15 epoll
2494     IOAsync 20000 174.67 610.84 poll
2495     Event 20000 202.69 242.91
2496     Glib 20000 557.01 1689.52
2497     POE 20000 341.54 12086.32 uses POE::Loop::Event
2498 root 1.91
2499     =head3 Discussion
2500    
2501     This benchmark I<does> measure scalability and overall performance of the
2502     particular event loop.
2503    
2504     EV is again fastest. Since it is using epoll on my system, the setup time
2505     is relatively high, though.
2506    
2507     Perl surprisingly comes second. It is much faster than the C-based event
2508     loops Event and Glib.
2509    
2510 root 1.220 IO::Async performs very well when using its epoll backend, and still quite
2511     good compared to Glib when using its pure perl backend.
2512    
2513 root 1.91 Event suffers from high setup time as well (look at its code and you will
2514     understand why). Callback invocation also has a high overhead compared to
2515     the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event
2516     uses select or poll in basically all documented configurations.
2517    
2518     Glib is hit hard by its quadratic behaviour w.r.t. many watchers. It
2519     clearly fails to perform with many filehandles or in busy servers.
2520    
2521     POE is still completely out of the picture, taking over 1000 times as long
2522     as EV, and over 100 times as long as the Perl implementation, even though
2523     it uses a C-based event loop in this case.
2524    
2525     =head3 Summary
2526    
2527     =over 4
2528    
2529 root 1.103 =item * The pure perl implementation performs extremely well.
2530 root 1.91
2531     =item * Avoid Glib or POE in large projects where performance matters.
2532    
2533     =back
2534    
2535     =head2 BENCHMARKING SMALL SERVERS
2536    
2537     While event loops should scale (and select-based ones do not...) even to
2538     large servers, most programs we (or I :) actually write have only a few
2539     I/O watchers.
2540    
2541     In this benchmark, I use the same benchmark program as in the large server
2542     case, but it uses only eight "servers", of which three are active at any
2543     one time. This should reflect performance for a small server relatively
2544     well.
2545    
2546     The columns are identical to the previous table.
2547    
2548     =head3 Results
2549    
2550     name sockets create request
2551     EV 16 20.00 6.54
2552 root 1.99 Perl 16 25.75 12.62
2553 root 1.91 Event 16 81.27 35.86
2554     Glib 16 32.63 15.48
2555     POE 16 261.87 276.28 uses POE::Loop::Event
2556    
2557     =head3 Discussion
2558    
2559     The benchmark tries to test the performance of a typical small
2560     server. While knowing how various event loops perform is interesting, keep
2561     in mind that their overhead in this case is usually not as important, due
2562 root 1.97 to the small absolute number of watchers (that is, you need efficiency and
2563     speed most when you have lots of watchers, not when you only have a few of
2564     them).
2565 root 1.91
2566     EV is again fastest.
2567    
2568 elmex 1.129 Perl again comes second. It is noticeably faster than the C-based event
2569 root 1.102 loops Event and Glib, although the difference is too small to really
2570     matter.
2571 root 1.91
2572 root 1.97 POE also performs much better in this case, but is is still far behind the
2573 root 1.91 others.
2574    
2575     =head3 Summary
2576    
2577     =over 4
2578    
2579     =item * C-based event loops perform very well with small number of
2580     watchers, as the management overhead dominates.
2581    
2582     =back
2583    
2584 root 1.215 =head2 THE IO::Lambda BENCHMARK
2585    
2586     Recently I was told about the benchmark in the IO::Lambda manpage, which
2587     could be misinterpreted to make AnyEvent look bad. In fact, the benchmark
2588     simply compares IO::Lambda with POE, and IO::Lambda looks better (which
2589     shouldn't come as a surprise to anybody). As such, the benchmark is
2590 root 1.218 fine, and mostly shows that the AnyEvent backend from IO::Lambda isn't
2591     very optimal. But how would AnyEvent compare when used without the extra
2592 root 1.215 baggage? To explore this, I wrote the equivalent benchmark for AnyEvent.
2593    
2594     The benchmark itself creates an echo-server, and then, for 500 times,
2595     connects to the echo server, sends a line, waits for the reply, and then
2596     creates the next connection. This is a rather bad benchmark, as it doesn't
2597 root 1.218 test the efficiency of the framework or much non-blocking I/O, but it is a
2598     benchmark nevertheless.
2599 root 1.215
2600     name runtime
2601     Lambda/select 0.330 sec
2602     + optimized 0.122 sec
2603     Lambda/AnyEvent 0.327 sec
2604     + optimized 0.138 sec
2605     Raw sockets/select 0.077 sec
2606     POE/select, components 0.662 sec
2607     POE/select, raw sockets 0.226 sec
2608     POE/select, optimized 0.404 sec
2609    
2610     AnyEvent/select/nb 0.085 sec
2611     AnyEvent/EV/nb 0.068 sec
2612     +state machine 0.134 sec
2613    
2614 root 1.218 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
2615 root 1.215 benchmarks actually make blocking connects and use 100% blocking I/O,
2616     defeating the purpose of an event-based solution. All of the newly
2617     written AnyEvent benchmarks use 100% non-blocking connects (using
2618     AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
2619 root 1.218 resolver), so AnyEvent is at a disadvantage here, as non-blocking connects
2620 root 1.215 generally require a lot more bookkeeping and event handling than blocking
2621     connects (which involve a single syscall only).
2622    
2623     The last AnyEvent benchmark additionally uses L<AnyEvent::Handle>, which
2624 root 1.218 offers similar expressive power as POE and IO::Lambda, using conventional
2625     Perl syntax. This means that both the echo server and the client are 100%
2626     non-blocking, further placing it at a disadvantage.
2627    
2628     As you can see, the AnyEvent + EV combination even beats the
2629     hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
2630     backend easily beats IO::Lambda and POE.
2631 root 1.215
2632     And even the 100% non-blocking version written using the high-level (and
2633 root 1.288 slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda
2634     higher level ("unoptimised") abstractions by a large margin, even though
2635     it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
2636 root 1.218
2637     The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
2638     F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2639 root 1.288 part of the IO::Lambda distribution and were used without any changes.
2640 root 1.216
2641 root 1.64
2642 root 1.185 =head1 SIGNALS
2643    
2644     AnyEvent currently installs handlers for these signals:
2645    
2646     =over 4
2647    
2648     =item SIGCHLD
2649    
2650     A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
2651     emulation for event loops that do not support them natively. Also, some
2652     event loops install a similar handler.
2653    
2654 root 1.235 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE, then
2655     AnyEvent will reset it to default, to avoid losing child exit statuses.
2656 root 1.219
2657 root 1.185 =item SIGPIPE
2658    
2659     A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
2660     when AnyEvent gets loaded.
2661    
2662     The rationale for this is that AnyEvent users usually do not really depend
2663     on SIGPIPE delivery (which is purely an optimisation for shell use, or
2664     badly-written programs), but C<SIGPIPE> can cause spurious and rare
2665     program exits as a lot of people do not expect C<SIGPIPE> when writing to
2666     some random socket.
2667    
2668     The rationale for installing a no-op handler as opposed to ignoring it is
2669     that this way, the handler will be restored to defaults on exec.
2670    
2671     Feel free to install your own handler, or reset it to defaults.
2672    
2673     =back
2674    
2675     =cut
2676    
2677 root 1.219 undef $SIG{CHLD}
2678     if $SIG{CHLD} eq 'IGNORE';
2679    
2680 root 1.185 $SIG{PIPE} = sub { }
2681     unless defined $SIG{PIPE};
2682    
2683 root 1.242 =head1 RECOMMENDED/OPTIONAL MODULES
2684    
2685     One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2686 root 1.330 its built-in modules) are required to use it.
2687 root 1.242
2688     That does not mean that AnyEvent won't take advantage of some additional
2689     modules if they are installed.
2690    
2691 root 1.301 This section explains which additional modules will be used, and how they
2692 root 1.299 affect AnyEvent's operation.
2693 root 1.242
2694     =over 4
2695    
2696     =item L<Async::Interrupt>
2697    
2698     This slightly arcane module is used to implement fast signal handling: To
2699     my knowledge, there is no way to do completely race-free and quick
2700     signal handling in pure perl. To ensure that signals still get
2701     delivered, AnyEvent will start an interval timer to wake up perl (and
2702 root 1.247 catch the signals) with some delay (default is 10 seconds, look for
2703 root 1.242 C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2704    
2705     If this module is available, then it will be used to implement signal
2706     catching, which means that signals will not be delayed, and the event loop
2707 root 1.300 will not be interrupted regularly, which is more efficient (and good for
2708 root 1.242 battery life on laptops).
2709    
2710     This affects not just the pure-perl event loop, but also other event loops
2711     that have no signal handling on their own (e.g. Glib, Tk, Qt).
2712    
2713 root 1.247 Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2714     and either employ their own workarounds (POE) or use AnyEvent's workaround
2715     (using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2716     does nothing for those backends.
2717    
2718 root 1.242 =item L<EV>
2719    
2720     This module isn't really "optional", as it is simply one of the backend
2721     event loops that AnyEvent can use. However, it is simply the best event
2722     loop available in terms of features, speed and stability: It supports
2723     the AnyEvent API optimally, implements all the watcher types in XS, does
2724     automatic timer adjustments even when no monotonic clock is available,
2725     can take avdantage of advanced kernel interfaces such as C<epoll> and
2726     C<kqueue>, and is the fastest backend I<by far>. You can even embed
2727     L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2728    
2729 root 1.316 If you only use backends that rely on another event loop (e.g. C<Tk>),
2730     then this module will do nothing for you.
2731    
2732 root 1.242 =item L<Guard>
2733    
2734     The guard module, when used, will be used to implement
2735     C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2736     lot less memory), but otherwise doesn't affect guard operation much. It is
2737     purely used for performance.
2738    
2739     =item L<JSON> and L<JSON::XS>
2740    
2741 root 1.291 One of these modules is required when you want to read or write JSON data
2742 root 1.316 via L<AnyEvent::Handle>. L<JSON> is also written in pure-perl, but can take
2743 root 1.248 advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2744 root 1.242
2745     =item L<Net::SSLeay>
2746    
2747     Implementing TLS/SSL in Perl is certainly interesting, but not very
2748     worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2749     the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2750    
2751     =item L<Time::HiRes>
2752    
2753     This module is part of perl since release 5.008. It will be used when the
2754 root 1.330 chosen event library does not come with a timing source of its own. The
2755 root 1.352 pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to
2756 root 1.242 try to use a monotonic clock for timing stability.
2757    
2758     =back
2759    
2760    
2761 root 1.55 =head1 FORK
2762    
2763     Most event libraries are not fork-safe. The ones who are usually are
2764 root 1.308 because they rely on inefficient but fork-safe C<select> or C<poll> calls
2765     - higher performance APIs such as BSD's kqueue or the dreaded Linux epoll
2766     are usually badly thought-out hacks that are incompatible with fork in
2767     one way or another. Only L<EV> is fully fork-aware and ensures that you
2768     continue event-processing in both parent and child (or both, if you know
2769     what you are doing).
2770    
2771     This means that, in general, you cannot fork and do event processing in
2772     the child if the event library was initialised before the fork (which
2773     usually happens when the first AnyEvent watcher is created, or the library
2774     is loaded).
2775 root 1.301
2776 root 1.55 If you have to fork, you must either do so I<before> creating your first
2777 root 1.242 watcher OR you must not use AnyEvent at all in the child OR you must do
2778     something completely out of the scope of AnyEvent.
2779 root 1.55
2780 root 1.301 The problem of doing event processing in the parent I<and> the child
2781     is much more complicated: even for backends that I<are> fork-aware or
2782     fork-safe, their behaviour is not usually what you want: fork clones all
2783     watchers, that means all timers, I/O watchers etc. are active in both
2784 root 1.308 parent and child, which is almost never what you want. USing C<exec>
2785     to start worker children from some kind of manage rprocess is usually
2786     preferred, because it is much easier and cleaner, at the expense of having
2787     to have another binary.
2788 root 1.301
2789 root 1.64
2790 root 1.55 =head1 SECURITY CONSIDERATIONS
2791    
2792     AnyEvent can be forced to load any event model via
2793     $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to
2794     execute arbitrary code or directly gain access, it can easily be used to
2795     make the program hang or malfunction in subtle ways, as AnyEvent watchers
2796     will not be active when the program uses a different event model than
2797     specified in the variable.
2798    
2799     You can make AnyEvent completely ignore this variable by deleting it
2800     before the first watcher gets created, e.g. with a C<BEGIN> block:
2801    
2802 root 1.151 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
2803    
2804     use AnyEvent;
2805 root 1.55
2806 root 1.107 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
2807     be used to probe what backend is used and gain other information (which is
2808 root 1.167 probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and
2809 root 1.213 $ENV{PERL_ANYEVENT_STRICT}.
2810 root 1.107
2811 root 1.218 Note that AnyEvent will remove I<all> environment variables starting with
2812     C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
2813     enabled.
2814    
2815 root 1.64
2816 root 1.156 =head1 BUGS
2817    
2818     Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
2819     to work around. If you suffer from memleaks, first upgrade to Perl 5.10
2820     and check wether the leaks still show up. (Perl 5.10.0 has other annoying
2821 root 1.197 memleaks, such as leaking on C<map> and C<grep> but it is usually not as
2822 root 1.156 pronounced).
2823    
2824    
2825 root 1.2 =head1 SEE ALSO
2826    
2827 root 1.334 Tutorial/Introduction: L<AnyEvent::Intro>.
2828    
2829     FAQ: L<AnyEvent::FAQ>.
2830    
2831 root 1.365 Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2832     (simply logging).
2833    
2834     Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2835     L<AnyEvent::Debug> (interactive shell, watcher tracing).
2836 root 1.125
2837 root 1.365 Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2838     L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2839     L<Qt>, L<POE>, L<FLTK>.
2840 root 1.108
2841     Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2842     L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2843     L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2844 root 1.365 L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
2845     L<AnyEvent::Impl::FLTK>.
2846 root 1.108
2847 root 1.365 Non-blocking handles, pipes, stream sockets, TCP clients and
2848 root 1.230 servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2849 root 1.125
2850 root 1.122 Asynchronous DNS: L<AnyEvent::DNS>.
2851    
2852 root 1.335 Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
2853 root 1.5
2854 root 1.334 Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::IRC>,
2855 root 1.230 L<AnyEvent::HTTP>.
2856 root 1.2
2857 root 1.64
2858 root 1.54 =head1 AUTHOR
2859    
2860 root 1.151 Marc Lehmann <schmorp@schmorp.de>
2861     http://home.schmorp.de/
2862 root 1.2
2863     =cut
2864    
2865     1
2866 root 1.1