ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.247 by root, Sat Jul 18 22:24:17 2009 UTC vs.
Revision 1.387 by root, Sat Oct 1 22:39:29 2011 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - the DBI of event loop programming
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt,
6event loops. 6FLTK and POE are various supported event loops/environments.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
12 # if you prefer function calls, look at the AE manpage for
13 # an alternative API.
14
12 # file descriptor readable 15 # file handle or descriptor readable
13 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... }); 16 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
14 17
15 # one-shot or repeating timers 18 # one-shot or repeating timers
16 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); 19 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
17 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... 20 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...);
18 21
19 print AnyEvent->now; # prints current event loop time 22 print AnyEvent->now; # prints current event loop time
20 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. 23 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
21 24
22 # POSIX signal 25 # POSIX signal
40=head1 INTRODUCTION/TUTORIAL 43=head1 INTRODUCTION/TUTORIAL
41 44
42This manpage is mainly a reference manual. If you are interested 45This manpage is mainly a reference manual. If you are interested
43in a tutorial or some gentle introduction, have a look at the 46in a tutorial or some gentle introduction, have a look at the
44L<AnyEvent::Intro> manpage. 47L<AnyEvent::Intro> manpage.
48
49=head1 SUPPORT
50
51An FAQ document is available as L<AnyEvent::FAQ>.
52
53There also is a mailinglist for discussing all things AnyEvent, and an IRC
54channel, too.
55
56See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
57Repository>, at L<http://anyevent.schmorp.de>, for more info.
45 58
46=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 59=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
47 60
48Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 61Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
49nowadays. So what is different about AnyEvent? 62nowadays. So what is different about AnyEvent?
65module users into the same thing by forcing them to use the same event 78module users into the same thing by forcing them to use the same event
66model you use. 79model you use.
67 80
68For modules like POE or IO::Async (which is a total misnomer as it is 81For modules like POE or IO::Async (which is a total misnomer as it is
69actually doing all I/O I<synchronously>...), using them in your module is 82actually doing all I/O I<synchronously>...), using them in your module is
70like joining a cult: After you joined, you are dependent on them and you 83like joining a cult: After you join, you are dependent on them and you
71cannot use anything else, as they are simply incompatible to everything 84cannot use anything else, as they are simply incompatible to everything
72that isn't them. What's worse, all the potential users of your 85that isn't them. What's worse, all the potential users of your
73module are I<also> forced to use the same event loop you use. 86module are I<also> forced to use the same event loop you use.
74 87
75AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 88AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
76fine. AnyEvent + Tk works fine etc. etc. but none of these work together 89fine. AnyEvent + Tk works fine etc. etc. but none of these work together
77with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if 90with the rest: POE + EV? No go. Tk + Event? No go. Again: if your module
78your module uses one of those, every user of your module has to use it, 91uses one of those, every user of your module has to use it, too. But if
79too. But if your module uses AnyEvent, it works transparently with all 92your module uses AnyEvent, it works transparently with all event models it
80event models it supports (including stuff like IO::Async, as long as those 93supports (including stuff like IO::Async, as long as those use one of the
81use one of the supported event loops. It is trivial to add new event loops 94supported event loops. It is easy to add new event loops to AnyEvent, too,
82to AnyEvent, too, so it is future-proof). 95so it is future-proof).
83 96
84In addition to being free of having to use I<the one and only true event 97In addition to being free of having to use I<the one and only true event
85model>, AnyEvent also is free of bloat and policy: with POE or similar 98model>, AnyEvent also is free of bloat and policy: with POE or similar
86modules, you get an enormous amount of code and strict rules you have to 99modules, you get an enormous amount of code and strict rules you have to
87follow. AnyEvent, on the other hand, is lean and up to the point, by only 100follow. AnyEvent, on the other hand, is lean and to the point, by only
88offering the functionality that is necessary, in as thin as a wrapper as 101offering the functionality that is necessary, in as thin as a wrapper as
89technically possible. 102technically possible.
90 103
91Of course, AnyEvent comes with a big (and fully optional!) toolbox 104Of course, AnyEvent comes with a big (and fully optional!) toolbox
92of useful functionality, such as an asynchronous DNS resolver, 100% 105of useful functionality, such as an asynchronous DNS resolver, 100%
98useful) and you want to force your users to use the one and only event 111useful) and you want to force your users to use the one and only event
99model, you should I<not> use this module. 112model, you should I<not> use this module.
100 113
101=head1 DESCRIPTION 114=head1 DESCRIPTION
102 115
103L<AnyEvent> provides an identical interface to multiple event loops. This 116L<AnyEvent> provides a uniform interface to various event loops. This
104allows module authors to utilise an event loop without forcing module 117allows module authors to use event loop functionality without forcing
105users to use the same event loop (as only a single event loop can coexist 118module users to use a specific event loop implementation (since more
106peacefully at any one time). 119than one event loop cannot coexist peacefully).
107 120
108The interface itself is vaguely similar, but not identical to the L<Event> 121The interface itself is vaguely similar, but not identical to the L<Event>
109module. 122module.
110 123
111During the first call of any watcher-creation method, the module tries 124During the first call of any watcher-creation method, the module tries
112to detect the currently loaded event loop by probing whether one of the 125to detect the currently loaded event loop by probing whether one of the
113following modules is already loaded: L<EV>, 126following modules is already loaded: L<EV>, L<AnyEvent::Loop>,
114L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>, 127L<Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. The first one
115L<POE>. The first one found is used. If none are found, the module tries 128found is used. If none are detected, the module tries to load the first
116to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl 129four modules in the order given; but note that if L<EV> is not
117adaptor should always succeed) in the order given. The first one that can 130available, the pure-perl L<AnyEvent::Loop> should always work, so
118be successfully loaded will be used. If, after this, still none could be 131the other two are not normally tried.
119found, AnyEvent will fall back to a pure-perl event loop, which is not
120very efficient, but should work everywhere.
121 132
122Because AnyEvent first checks for modules that are already loaded, loading 133Because AnyEvent first checks for modules that are already loaded, loading
123an event model explicitly before first using AnyEvent will likely make 134an event model explicitly before first using AnyEvent will likely make
124that model the default. For example: 135that model the default. For example:
125 136
127 use AnyEvent; 138 use AnyEvent;
128 139
129 # .. AnyEvent will likely default to Tk 140 # .. AnyEvent will likely default to Tk
130 141
131The I<likely> means that, if any module loads another event model and 142The I<likely> means that, if any module loads another event model and
132starts using it, all bets are off. Maybe you should tell their authors to 143starts using it, all bets are off - this case should be very rare though,
133use AnyEvent so their modules work together with others seamlessly... 144as very few modules hardcode event loops without announcing this very
145loudly.
134 146
135The pure-perl implementation of AnyEvent is called 147The pure-perl implementation of AnyEvent is called C<AnyEvent::Loop>. Like
136C<AnyEvent::Impl::Perl>. Like other event modules you can load it 148other event modules you can load it explicitly and enjoy the high
137explicitly and enjoy the high availability of that event loop :) 149availability of that event loop :)
138 150
139=head1 WATCHERS 151=head1 WATCHERS
140 152
141AnyEvent has the central concept of a I<watcher>, which is an object that 153AnyEvent has the central concept of a I<watcher>, which is an object that
142stores relevant data for each kind of event you are waiting for, such as 154stores relevant data for each kind of event you are waiting for, such as
147callback when the event occurs (of course, only when the event model 159callback when the event occurs (of course, only when the event model
148is in control). 160is in control).
149 161
150Note that B<callbacks must not permanently change global variables> 162Note that B<callbacks must not permanently change global variables>
151potentially in use by the event loop (such as C<$_> or C<$[>) and that B<< 163potentially in use by the event loop (such as C<$_> or C<$[>) and that B<<
152callbacks must not C<die> >>. The former is good programming practise in 164callbacks must not C<die> >>. The former is good programming practice in
153Perl and the latter stems from the fact that exception handling differs 165Perl and the latter stems from the fact that exception handling differs
154widely between event loops. 166widely between event loops.
155 167
156To disable the watcher you have to destroy it (e.g. by setting the 168To disable a watcher you have to destroy it (e.g. by setting the
157variable you store it in to C<undef> or otherwise deleting all references 169variable you store it in to C<undef> or otherwise deleting all references
158to it). 170to it).
159 171
160All watchers are created by calling a method on the C<AnyEvent> class. 172All watchers are created by calling a method on the C<AnyEvent> class.
161 173
162Many watchers either are used with "recursion" (repeating timers for 174Many watchers either are used with "recursion" (repeating timers for
163example), or need to refer to their watcher object in other ways. 175example), or need to refer to their watcher object in other ways.
164 176
165An any way to achieve that is this pattern: 177One way to achieve that is this pattern:
166 178
167 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 179 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
168 # you can use $w here, for example to undef it 180 # you can use $w here, for example to undef it
169 undef $w; 181 undef $w;
170 }); 182 });
172Note that C<my $w; $w => combination. This is necessary because in Perl, 184Note that C<my $w; $w => combination. This is necessary because in Perl,
173my variables are only visible after the statement in which they are 185my variables are only visible after the statement in which they are
174declared. 186declared.
175 187
176=head2 I/O WATCHERS 188=head2 I/O WATCHERS
189
190 $w = AnyEvent->io (
191 fh => <filehandle_or_fileno>,
192 poll => <"r" or "w">,
193 cb => <callback>,
194 );
177 195
178You can create an I/O watcher by calling the C<< AnyEvent->io >> method 196You can create an I/O watcher by calling the C<< AnyEvent->io >> method
179with the following mandatory key-value pairs as arguments: 197with the following mandatory key-value pairs as arguments:
180 198
181C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch 199C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
196 214
197The I/O watcher might use the underlying file descriptor or a copy of it. 215The I/O watcher might use the underlying file descriptor or a copy of it.
198You must not close a file handle as long as any watcher is active on the 216You must not close a file handle as long as any watcher is active on the
199underlying file descriptor. 217underlying file descriptor.
200 218
201Some event loops issue spurious readyness notifications, so you should 219Some event loops issue spurious readiness notifications, so you should
202always use non-blocking calls when reading/writing from/to your file 220always use non-blocking calls when reading/writing from/to your file
203handles. 221handles.
204 222
205Example: wait for readability of STDIN, then read a line and disable the 223Example: wait for readability of STDIN, then read a line and disable the
206watcher. 224watcher.
211 undef $w; 229 undef $w;
212 }); 230 });
213 231
214=head2 TIME WATCHERS 232=head2 TIME WATCHERS
215 233
234 $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
216You can create a time watcher by calling the C<< AnyEvent->timer >> 242You can create a time watcher by calling the C<< AnyEvent->timer >>
217method with the following mandatory arguments: 243method with the following mandatory arguments:
218 244
219C<after> specifies after how many seconds (fractional values are 245C<after> specifies after how many seconds (fractional values are
220supported) the callback should be invoked. C<cb> is the callback to invoke 246supported) the callback should be invoked. C<cb> is the callback to invoke
222 248
223Although the callback might get passed parameters, their value and 249Although the callback might get passed parameters, their value and
224presence is undefined and you cannot rely on them. Portable AnyEvent 250presence is undefined and you cannot rely on them. Portable AnyEvent
225callbacks cannot use arguments passed to time watcher callbacks. 251callbacks cannot use arguments passed to time watcher callbacks.
226 252
227The callback will normally be invoked once only. If you specify another 253The callback will normally be invoked only once. If you specify another
228parameter, C<interval>, as a strictly positive number (> 0), then the 254parameter, C<interval>, as a strictly positive number (> 0), then the
229callback will be invoked regularly at that interval (in fractional 255callback will be invoked regularly at that interval (in fractional
230seconds) after the first invocation. If C<interval> is specified with a 256seconds) after the first invocation. If C<interval> is specified with a
231false value, then it is treated as if it were missing. 257false value, then it is treated as if it were not specified at all.
232 258
233The callback will be rescheduled before invoking the callback, but no 259The callback will be rescheduled before invoking the callback, but no
234attempt is done to avoid timer drift in most backends, so the interval is 260attempt is made to avoid timer drift in most backends, so the interval is
235only approximate. 261only approximate.
236 262
237Example: fire an event after 7.7 seconds. 263Example: fire an event after 7.7 seconds.
238 264
239 my $w = AnyEvent->timer (after => 7.7, cb => sub { 265 my $w = AnyEvent->timer (after => 7.7, cb => sub {
257 283
258While most event loops expect timers to specified in a relative way, they 284While most event loops expect timers to specified in a relative way, they
259use absolute time internally. This makes a difference when your clock 285use absolute time internally. This makes a difference when your clock
260"jumps", for example, when ntp decides to set your clock backwards from 286"jumps", for example, when ntp decides to set your clock backwards from
261the wrong date of 2014-01-01 to 2008-01-01, a watcher that is supposed to 287the wrong date of 2014-01-01 to 2008-01-01, a watcher that is supposed to
262fire "after" a second might actually take six years to finally fire. 288fire "after a second" might actually take six years to finally fire.
263 289
264AnyEvent cannot compensate for this. The only event loop that is conscious 290AnyEvent cannot compensate for this. The only event loop that is conscious
265about these issues is L<EV>, which offers both relative (ev_timer, based 291of these issues is L<EV>, which offers both relative (ev_timer, based
266on true relative time) and absolute (ev_periodic, based on wallclock time) 292on true relative time) and absolute (ev_periodic, based on wallclock time)
267timers. 293timers.
268 294
269AnyEvent always prefers relative timers, if available, matching the 295AnyEvent always prefers relative timers, if available, matching the
270AnyEvent API. 296AnyEvent API.
292I<In almost all cases (in all cases if you don't care), this is the 318I<In almost all cases (in all cases if you don't care), this is the
293function to call when you want to know the current time.> 319function to call when you want to know the current time.>
294 320
295This function is also often faster then C<< AnyEvent->time >>, and 321This function is also often faster then C<< AnyEvent->time >>, and
296thus the preferred method if you want some timestamp (for example, 322thus the preferred method if you want some timestamp (for example,
297L<AnyEvent::Handle> uses this to update it's activity timeouts). 323L<AnyEvent::Handle> uses this to update its activity timeouts).
298 324
299The rest of this section is only of relevance if you try to be very exact 325The rest of this section is only of relevance if you try to be very exact
300with your timing, you can skip it without bad conscience. 326with your timing; you can skip it without a bad conscience.
301 327
302For a practical example of when these times differ, consider L<Event::Lib> 328For a practical example of when these times differ, consider L<Event::Lib>
303and L<EV> and the following set-up: 329and L<EV> and the following set-up:
304 330
305The event loop is running and has just invoked one of your callback at 331The event loop is running and has just invoked one of your callbacks at
306time=500 (assume no other callbacks delay processing). In your callback, 332time=500 (assume no other callbacks delay processing). In your callback,
307you wait a second by executing C<sleep 1> (blocking the process for a 333you wait a second by executing C<sleep 1> (blocking the process for a
308second) and then (at time=501) you create a relative timer that fires 334second) and then (at time=501) you create a relative timer that fires
309after three seconds. 335after three seconds.
310 336
330difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into 356difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
331account. 357account.
332 358
333=item AnyEvent->now_update 359=item AnyEvent->now_update
334 360
335Some event loops (such as L<EV> or L<AnyEvent::Impl::Perl>) cache 361Some event loops (such as L<EV> or L<AnyEvent::Loop>) cache the current
336the current time for each loop iteration (see the discussion of L<< 362time for each loop iteration (see the discussion of L<< AnyEvent->now >>,
337AnyEvent->now >>, above). 363above).
338 364
339When a callback runs for a long time (or when the process sleeps), then 365When a callback runs for a long time (or when the process sleeps), then
340this "current" time will differ substantially from the real time, which 366this "current" time will differ substantially from the real time, which
341might affect timers and time-outs. 367might affect timers and time-outs.
342 368
343When this is the case, you can call this method, which will update the 369When this is the case, you can call this method, which will update the
344event loop's idea of "current time". 370event loop's idea of "current time".
345 371
372A typical example would be a script in a web server (e.g. C<mod_perl>) -
373when mod_perl executes the script, then the event loop will have the wrong
374idea about the "current time" (being potentially far in the past, when the
375script ran the last time). In that case you should arrange a call to C<<
376AnyEvent->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
346Note that updating the time I<might> cause some events to be handled. 379Note that updating the time I<might> cause some events to be handled.
347 380
348=back 381=back
349 382
350=head2 SIGNAL WATCHERS 383=head2 SIGNAL WATCHERS
384
385 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
351 386
352You can watch for signals using a signal watcher, C<signal> is the signal 387You can watch for signals using a signal watcher, C<signal> is the signal
353I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl 388I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
354callback to be invoked whenever a signal occurs. 389callback to be invoked whenever a signal occurs.
355 390
372 407
373Example: exit on SIGINT 408Example: exit on SIGINT
374 409
375 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 410 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
376 411
412=head3 Restart Behaviour
413
414While restart behaviour is up to the event loop implementation, most will
415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's
416pure perl implementation).
417
418=head3 Safe/Unsafe Signals
419
420Perl signals can be either "safe" (synchronous to opcode handling)
421or "unsafe" (asynchronous) - the former might delay signal delivery
422indefinitely, the latter might corrupt your memory.
423
424AnyEvent signal handlers are, in addition, synchronous to the event loop,
425i.e. they will not interrupt your running perl program but will only be
426called as part of the normal event handling (just like timer, I/O etc.
427callbacks, too).
428
377=head3 Signal Races, Delays and Workarounds 429=head3 Signal Races, Delays and Workarounds
378 430
379Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support
380callbacks to signals in a generic way, which is a pity, as you cannot do 432attaching callbacks to signals in a generic way, which is a pity,
381race-free signal handling in perl. AnyEvent will try to do it's best, but 433as you cannot do race-free signal handling in perl, requiring
434C libraries for this. AnyEvent will try to do its best, which
382in some cases, signals will be delayed. The maximum time a signal might 435means in some cases, signals will be delayed. The maximum time
383be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 436a signal might be delayed is 10 seconds by default, but can
384seconds). This variable can be changed only before the first signal 437be overriden via C<$ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY}> or
385watcher is created, and should be left alone otherwise. Higher values 438C<$AnyEvent::MAX_SIGNAL_LATENCY> - see the Ö<ENVIRONMENT VARIABLES>
386will cause fewer spurious wake-ups, which is better for power and CPU 439section for details.
440
387saving. All these problems can be avoided by installing the optional 441All these problems can be avoided by installing the optional
388L<Async::Interrupt> module. This will not work with inherently broken 442L<Async::Interrupt> module, which works with most event loops. It will not
389event loops such as L<Event> or L<Event::Lib> (and not with L<POE> 443work with inherently broken event loops such as L<Event> or L<Event::Lib>
390currently, as POE does it's own workaround with one-second latency). With 444(and not with L<POE> currently). For those, you just have to suffer the
391those, you just have to suffer the delays. 445delays.
392 446
393=head2 CHILD PROCESS WATCHERS 447=head2 CHILD PROCESS WATCHERS
394 448
449 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
450
395You can also watch on a child process exit and catch its exit status. 451You can also watch for a child process exit and catch its exit status.
396 452
397The child process is specified by the C<pid> argument (if set to C<0>, it 453The child process is specified by the C<pid> argument (on some backends,
398watches for any child process exit). The watcher will triggered only when 454using C<0> watches for any child process exit, on others this will
399the child process has finished and an exit status is available, not on 455croak). The watcher will be triggered only when the child process has
400any trace events (stopped/continued). 456finished and an exit status is available, not on any trace events
457(stopped/continued).
401 458
402The callback will be called with the pid and exit status (as returned by 459The callback will be called with the pid and exit status (as returned by
403waitpid), so unlike other watcher types, you I<can> rely on child watcher 460waitpid), so unlike other watcher types, you I<can> rely on child watcher
404callback arguments. 461callback arguments.
405 462
423thing in an AnyEvent program, you I<have> to create at least one 480thing in an AnyEvent program, you I<have> to create at least one
424watcher before you C<fork> the child (alternatively, you can call 481watcher before you C<fork> the child (alternatively, you can call
425C<AnyEvent::detect>). 482C<AnyEvent::detect>).
426 483
427As most event loops do not support waiting for child events, they will be 484As most event loops do not support waiting for child events, they will be
428emulated by AnyEvent in most cases, in which the latency and race problems 485emulated by AnyEvent in most cases, in which case the latency and race
429mentioned in the description of signal watchers apply. 486problems mentioned in the description of signal watchers apply.
430 487
431Example: fork a process and wait for it 488Example: fork a process and wait for it
432 489
433 my $done = AnyEvent->condvar; 490 my $done = AnyEvent->condvar;
434 491
446 # do something else, then wait for process exit 503 # do something else, then wait for process exit
447 $done->recv; 504 $done->recv;
448 505
449=head2 IDLE WATCHERS 506=head2 IDLE WATCHERS
450 507
451Sometimes there is a need to do something, but it is not so important 508 $w = AnyEvent->idle (cb => <callback>);
452to do it instantly, but only when there is nothing better to do. This
453"nothing better to do" is usually defined to be "no other events need
454attention by the event loop".
455 509
456Idle watchers ideally get invoked when the event loop has nothing 510This will repeatedly invoke the callback after the process becomes idle,
457better to do, just before it would block the process to wait for new 511until either the watcher is destroyed or new events have been detected.
458events. Instead of blocking, the idle watcher is invoked.
459 512
460Most event loops unfortunately do not really support idle watchers (only 513Idle watchers are useful when there is a need to do something, but it
514is not so important (or wise) to do it instantly. The callback will be
515invoked only when there is "nothing better to do", which is usually
516defined as "all outstanding events have been handled and no new events
517have been detected". That means that idle watchers ideally get invoked
518when the event loop has just polled for new events but none have been
519detected. Instead of blocking to wait for more events, the idle watchers
520will be invoked.
521
522Unfortunately, most event loops do not really support idle watchers (only
461EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent 523EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
462will simply call the callback "from time to time". 524will simply call the callback "from time to time".
463 525
464Example: read lines from STDIN, but only process them when the 526Example: read lines from STDIN, but only process them when the
465program is otherwise idle: 527program is otherwise idle:
481 }); 543 });
482 }); 544 });
483 545
484=head2 CONDITION VARIABLES 546=head2 CONDITION VARIABLES
485 547
548 $cv = AnyEvent->condvar;
549
550 $cv->send (<list>);
551 my @res = $cv->recv;
552
486If you are familiar with some event loops you will know that all of them 553If you are familiar with some event loops you will know that all of them
487require you to run some blocking "loop", "run" or similar function that 554require you to run some blocking "loop", "run" or similar function that
488will actively watch for new events and call your callbacks. 555will actively watch for new events and call your callbacks.
489 556
490AnyEvent is slightly different: it expects somebody else to run the event 557AnyEvent is slightly different: it expects somebody else to run the event
491loop and will only block when necessary (usually when told by the user). 558loop and will only block when necessary (usually when told by the user).
492 559
493The instrument to do that is called a "condition variable", so called 560The tool to do that is called a "condition variable", so called because
494because they represent a condition that must become true. 561they represent a condition that must become true.
495 562
496Now is probably a good time to look at the examples further below. 563Now is probably a good time to look at the examples further below.
497 564
498Condition variables can be created by calling the C<< AnyEvent->condvar 565Condition variables can be created by calling the C<< AnyEvent->condvar
499>> method, usually without arguments. The only argument pair allowed is 566>> method, usually without arguments. The only argument pair allowed is
504After creation, the condition variable is "false" until it becomes "true" 571After creation, the condition variable is "false" until it becomes "true"
505by calling the C<send> method (or calling the condition variable as if it 572by calling the C<send> method (or calling the condition variable as if it
506were a callback, read about the caveats in the description for the C<< 573were a callback, read about the caveats in the description for the C<<
507->send >> method). 574->send >> method).
508 575
509Condition variables are similar to callbacks, except that you can 576Since condition variables are the most complex part of the AnyEvent API, here are
510optionally wait for them. They can also be called merge points - points 577some different mental models of what they are - pick the ones you can connect to:
511in time where multiple outstanding events have been processed. And yet 578
512another way to call them is transactions - each condition variable can be 579=over 4
513used to represent a transaction, which finishes at some point and delivers 580
514a result. 581=item * Condition variables are like callbacks - you can call them (and pass them instead
582of callbacks). Unlike callbacks however, you can also wait for them to be called.
583
584=item * Condition variables are signals - one side can emit or send them,
585the other side can wait for them, or install a handler that is called when
586the signal fires.
587
588=item * Condition variables are like "Merge Points" - points in your program
589where you merge multiple independent results/control flows into one.
590
591=item * Condition variables represent a transaction - functions that start
592some kind of transaction can return them, leaving the caller the choice
593between waiting in a blocking fashion, or setting a callback.
594
595=item * Condition variables represent future values, or promises to deliver
596some result, long before the result is available.
597
598=back
515 599
516Condition variables are very useful to signal that something has finished, 600Condition variables are very useful to signal that something has finished,
517for example, if you write a module that does asynchronous http requests, 601for example, if you write a module that does asynchronous http requests,
518then a condition variable would be the ideal candidate to signal the 602then a condition variable would be the ideal candidate to signal the
519availability of results. The user can either act when the callback is 603availability of results. The user can either act when the callback is
532 616
533Condition variables are represented by hash refs in perl, and the keys 617Condition variables are represented by hash refs in perl, and the keys
534used by AnyEvent itself are all named C<_ae_XXX> to make subclassing 618used by AnyEvent itself are all named C<_ae_XXX> to make subclassing
535easy (it is often useful to build your own transaction class on top of 619easy (it is often useful to build your own transaction class on top of
536AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call 620AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call
537it's C<new> method in your own C<new> method. 621its C<new> method in your own C<new> method.
538 622
539There are two "sides" to a condition variable - the "producer side" which 623There are two "sides" to a condition variable - the "producer side" which
540eventually calls C<< -> send >>, and the "consumer side", which waits 624eventually calls C<< -> send >>, and the "consumer side", which waits
541for the send to occur. 625for the send to occur.
542 626
543Example: wait for a timer. 627Example: wait for a timer.
544 628
545 # wait till the result is ready 629 # condition: "wait till the timer is fired"
546 my $result_ready = AnyEvent->condvar; 630 my $timer_fired = AnyEvent->condvar;
547 631
548 # do something such as adding a timer 632 # create the timer - we could wait for, say
549 # or socket watcher the calls $result_ready->send 633 # a handle becomign ready, or even an
550 # when the "result" is ready. 634 # AnyEvent::HTTP request to finish, but
551 # in this case, we simply use a timer: 635 # in this case, we simply use a timer:
552 my $w = AnyEvent->timer ( 636 my $w = AnyEvent->timer (
553 after => 1, 637 after => 1,
554 cb => sub { $result_ready->send }, 638 cb => sub { $timer_fired->send },
555 ); 639 );
556 640
557 # this "blocks" (while handling events) till the callback 641 # this "blocks" (while handling events) till the callback
558 # calls -<send 642 # calls ->send
559 $result_ready->recv; 643 $timer_fired->recv;
560 644
561Example: wait for a timer, but take advantage of the fact that condition 645Example: wait for a timer, but take advantage of the fact that condition
562variables are also callable directly. 646variables are also callable directly.
563 647
564 my $done = AnyEvent->condvar; 648 my $done = AnyEvent->condvar;
607they were a code reference). Calling them directly is the same as calling 691they were a code reference). Calling them directly is the same as calling
608C<send>. 692C<send>.
609 693
610=item $cv->croak ($error) 694=item $cv->croak ($error)
611 695
612Similar to send, but causes all call's to C<< ->recv >> to invoke 696Similar to send, but causes all calls to C<< ->recv >> to invoke
613C<Carp::croak> with the given error message/object/scalar. 697C<Carp::croak> with the given error message/object/scalar.
614 698
615This can be used to signal any errors to the condition variable 699This can be used to signal any errors to the condition variable
616user/consumer. Doing it this way instead of calling C<croak> directly 700user/consumer. Doing it this way instead of calling C<croak> directly
617delays the error detetcion, but has the overwhelmign advantage that it 701delays the error detection, but has the overwhelming advantage that it
618diagnoses the error at the place where the result is expected, and not 702diagnoses the error at the place where the result is expected, and not
619deep in some event clalback without connection to the actual code causing 703deep in some event callback with no connection to the actual code causing
620the problem. 704the problem.
621 705
622=item $cv->begin ([group callback]) 706=item $cv->begin ([group callback])
623 707
624=item $cv->end 708=item $cv->end
627one. For example, a function that pings many hosts in parallel might want 711one. For example, a function that pings many hosts in parallel might want
628to use a condition variable for the whole process. 712to use a condition variable for the whole process.
629 713
630Every call to C<< ->begin >> will increment a counter, and every call to 714Every call to C<< ->begin >> will increment a counter, and every call to
631C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end 715C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
632>>, the (last) callback passed to C<begin> will be executed. That callback 716>>, the (last) callback passed to C<begin> will be executed, passing the
633is I<supposed> to call C<< ->send >>, but that is not required. If no 717condvar as first argument. That callback is I<supposed> to call C<< ->send
634callback was set, C<send> will be called without any arguments. 718>>, but that is not required. If no group callback was set, C<send> will
719be called without any arguments.
635 720
636You can think of C<< $cv->send >> giving you an OR condition (one call 721You can think of C<< $cv->send >> giving you an OR condition (one call
637sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND 722sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND
638condition (all C<begin> calls must be C<end>'ed before the condvar sends). 723condition (all C<begin> calls must be C<end>'ed before the condvar sends).
639 724
661one call to C<begin>, so the condvar waits for all calls to C<end> before 746one call to C<begin>, so the condvar waits for all calls to C<end> before
662sending. 747sending.
663 748
664The ping example mentioned above is slightly more complicated, as the 749The ping example mentioned above is slightly more complicated, as the
665there are results to be passwd back, and the number of tasks that are 750there are results to be passwd back, and the number of tasks that are
666begung can potentially be zero: 751begun can potentially be zero:
667 752
668 my $cv = AnyEvent->condvar; 753 my $cv = AnyEvent->condvar;
669 754
670 my %result; 755 my %result;
671 $cv->begin (sub { $cv->send (\%result) }); 756 $cv->begin (sub { shift->send (\%result) });
672 757
673 for my $host (@list_of_hosts) { 758 for my $host (@list_of_hosts) {
674 $cv->begin; 759 $cv->begin;
675 ping_host_then_call_callback $host, sub { 760 ping_host_then_call_callback $host, sub {
676 $result{$host} = ...; 761 $result{$host} = ...;
692to be called once the counter reaches C<0>, and second, it ensures that 777to be called once the counter reaches C<0>, and second, it ensures that
693C<send> is called even when C<no> hosts are being pinged (the loop 778C<send> is called even when C<no> hosts are being pinged (the loop
694doesn't execute once). 779doesn't execute once).
695 780
696This is the general pattern when you "fan out" into multiple (but 781This is the general pattern when you "fan out" into multiple (but
697potentially none) subrequests: use an outer C<begin>/C<end> pair to set 782potentially zero) subrequests: use an outer C<begin>/C<end> pair to set
698the callback and ensure C<end> is called at least once, and then, for each 783the callback and ensure C<end> is called at least once, and then, for each
699subrequest you start, call C<begin> and for each subrequest you finish, 784subrequest you start, call C<begin> and for each subrequest you finish,
700call C<end>. 785call C<end>.
701 786
702=back 787=back
709=over 4 794=over 4
710 795
711=item $cv->recv 796=item $cv->recv
712 797
713Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak 798Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
714>> methods have been called on c<$cv>, while servicing other watchers 799>> methods have been called on C<$cv>, while servicing other watchers
715normally. 800normally.
716 801
717You can only wait once on a condition - additional calls are valid but 802You can only wait once on a condition - additional calls are valid but
718will return immediately. 803will return immediately.
719 804
736caller decide whether the call will block or not (for example, by coupling 821caller decide whether the call will block or not (for example, by coupling
737condition variables with some kind of request results and supporting 822condition variables with some kind of request results and supporting
738callbacks so the caller knows that getting the result will not block, 823callbacks so the caller knows that getting the result will not block,
739while still supporting blocking waits if the caller so desires). 824while still supporting blocking waits if the caller so desires).
740 825
741You can ensure that C<< -recv >> never blocks by setting a callback and 826You can ensure that C<< ->recv >> never blocks by setting a callback and
742only calling C<< ->recv >> from within that callback (or at a later 827only calling C<< ->recv >> from within that callback (or at a later
743time). This will work even when the event loop does not support blocking 828time). This will work even when the event loop does not support blocking
744waits otherwise. 829waits otherwise.
745 830
746=item $bool = $cv->ready 831=item $bool = $cv->ready
752 837
753This is a mutator function that returns the callback set and optionally 838This is a mutator function that returns the callback set and optionally
754replaces it before doing so. 839replaces it before doing so.
755 840
756The callback will be called when the condition becomes "true", i.e. when 841The callback will be called when the condition becomes "true", i.e. when
757C<send> or C<croak> are called, with the only argument being the condition 842C<send> or C<croak> are called, with the only argument being the
758variable itself. Calling C<recv> inside the callback or at any later time 843condition variable itself. If the condition is already true, the
759is guaranteed not to block. 844callback is called immediately when it is set. Calling C<recv> inside
845the callback or at any later time is guaranteed not to block.
760 846
761=back 847=back
762 848
763=head1 SUPPORTED EVENT LOOPS/BACKENDS 849=head1 SUPPORTED EVENT LOOPS/BACKENDS
764 850
767=over 4 853=over 4
768 854
769=item Backends that are autoprobed when no other event loop can be found. 855=item Backends that are autoprobed when no other event loop can be found.
770 856
771EV is the preferred backend when no other event loop seems to be in 857EV is the preferred backend when no other event loop seems to be in
772use. If EV is not installed, then AnyEvent will try Event, and, failing 858use. If EV is not installed, then AnyEvent will fall back to its own
773that, will fall back to its own pure-perl implementation, which is 859pure-perl implementation, which is available everywhere as it comes with
774available everywhere as it comes with AnyEvent itself. 860AnyEvent itself.
775 861
776 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 862 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
777 AnyEvent::Impl::Event based on Event, very stable, few glitches.
778 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 863 AnyEvent::Impl::Perl pure-perl AnyEvent::Loop, fast and portable.
779 864
780=item Backends that are transparently being picked up when they are used. 865=item Backends that are transparently being picked up when they are used.
781 866
782These will be used when they are currently loaded when the first watcher 867These will be used if they are already loaded when the first watcher
783is created, in which case it is assumed that the application is using 868is created, in which case it is assumed that the application is using
784them. This means that AnyEvent will automatically pick the right backend 869them. This means that AnyEvent will automatically pick the right backend
785when the main program loads an event module before anything starts to 870when the main program loads an event module before anything starts to
786create watchers. Nothing special needs to be done by the main program. 871create watchers. Nothing special needs to be done by the main program.
787 872
873 AnyEvent::Impl::Event based on Event, very stable, few glitches.
788 AnyEvent::Impl::Glib based on Glib, slow but very stable. 874 AnyEvent::Impl::Glib based on Glib, slow but very stable.
789 AnyEvent::Impl::Tk based on Tk, very broken. 875 AnyEvent::Impl::Tk based on Tk, very broken.
790 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 876 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
791 AnyEvent::Impl::POE based on POE, very slow, some limitations. 877 AnyEvent::Impl::POE based on POE, very slow, some limitations.
878 AnyEvent::Impl::Irssi used when running within irssi.
879 AnyEvent::Impl::IOAsync based on IO::Async.
880 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
881 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
792 882
793=item Backends with special needs. 883=item Backends with special needs.
794 884
795Qt requires the Qt::Application to be instantiated first, but will 885Qt requires the Qt::Application to be instantiated first, but will
796otherwise be picked up automatically. As long as the main program 886otherwise be picked up automatically. As long as the main program
797instantiates the application before any AnyEvent watchers are created, 887instantiates the application before any AnyEvent watchers are created,
798everything should just work. 888everything should just work.
799 889
800 AnyEvent::Impl::Qt based on Qt. 890 AnyEvent::Impl::Qt based on Qt.
801 891
802Support for IO::Async can only be partial, as it is too broken and
803architecturally limited to even support the AnyEvent API. It also
804is the only event loop that needs the loop to be set explicitly, so
805it can only be used by a main program knowing about AnyEvent. See
806L<AnyEvent::Impl::Async> for the gory details.
807
808 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
809
810=item Event loops that are indirectly supported via other backends. 892=item Event loops that are indirectly supported via other backends.
811 893
812Some event loops can be supported via other modules: 894Some event loops can be supported via other modules:
813 895
814There is no direct support for WxWidgets (L<Wx>) or L<Prima>. 896There is no direct support for WxWidgets (L<Wx>) or L<Prima>.
839Contains C<undef> until the first watcher is being created, before the 921Contains C<undef> until the first watcher is being created, before the
840backend has been autodetected. 922backend has been autodetected.
841 923
842Afterwards it contains the event model that is being used, which is the 924Afterwards it contains the event model that is being used, which is the
843name of the Perl class implementing the model. This class is usually one 925name of the Perl class implementing the model. This class is usually one
844of the C<AnyEvent::Impl:xxx> modules, but can be any other class in the 926of the C<AnyEvent::Impl::xxx> modules, but can be any other class in the
845case AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode> it 927case AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode> it
846will be C<urxvt::anyevent>). 928will be C<urxvt::anyevent>).
847 929
848=item AnyEvent::detect 930=item AnyEvent::detect
849 931
850Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 932Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
851if necessary. You should only call this function right before you would 933if necessary. You should only call this function right before you would
852have created an AnyEvent watcher anyway, that is, as late as possible at 934have created an AnyEvent watcher anyway, that is, as late as possible at
853runtime, and not e.g. while initialising of your module. 935runtime, and not e.g. during initialisation of your module.
936
937The effect of calling this function is as if a watcher had been created
938(specifically, actions that happen "when the first watcher is created"
939happen when calling detetc as well).
854 940
855If you need to do some initialisation before AnyEvent watchers are 941If you need to do some initialisation before AnyEvent watchers are
856created, use C<post_detect>. 942created, use C<post_detect>.
857 943
858=item $guard = AnyEvent::post_detect { BLOCK } 944=item $guard = AnyEvent::post_detect { BLOCK }
859 945
860Arranges for the code block to be executed as soon as the event model is 946Arranges for the code block to be executed as soon as the event model is
861autodetected (or immediately if this has already happened). 947autodetected (or immediately if that has already happened).
862 948
863The block will be executed I<after> the actual backend has been detected 949The block will be executed I<after> the actual backend has been detected
864(C<$AnyEvent::MODEL> is set), but I<before> any watchers have been 950(C<$AnyEvent::MODEL> is set), but I<before> any watchers have been
865created, so it is possible to e.g. patch C<@AnyEvent::ISA> or do 951created, so it is possible to e.g. patch C<@AnyEvent::ISA> or do
866other initialisations - see the sources of L<AnyEvent::Strict> or 952other initialisations - see the sources of L<AnyEvent::Strict> or
870event module detection too early, for example, L<AnyEvent::AIO> creates 956event module detection too early, for example, L<AnyEvent::AIO> creates
871and installs the global L<IO::AIO> watcher in a C<post_detect> block to 957and installs the global L<IO::AIO> watcher in a C<post_detect> block to
872avoid autodetecting the event module at load time. 958avoid autodetecting the event module at load time.
873 959
874If called in scalar or list context, then it creates and returns an object 960If called in scalar or list context, then it creates and returns an object
875that automatically removes the callback again when it is destroyed. See 961that automatically removes the callback again when it is destroyed (or
962C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
876L<Coro::BDB> for a case where this is useful. 963a case where this is useful.
964
965Example: Create a watcher for the IO::AIO module and store it in
966C<$WATCHER>, but do so only do so after the event loop is initialised.
967
968 our WATCHER;
969
970 my $guard = AnyEvent::post_detect {
971 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
972 };
973
974 # the ||= is important in case post_detect immediately runs the block,
975 # as to not clobber the newly-created watcher. assigning both watcher and
976 # post_detect guard to the same variable has the advantage of users being
977 # able to just C<undef $WATCHER> if the watcher causes them grief.
978
979 $WATCHER ||= $guard;
877 980
878=item @AnyEvent::post_detect 981=item @AnyEvent::post_detect
879 982
880If there are any code references in this array (you can C<push> to it 983If there are any code references in this array (you can C<push> to it
881before or after loading AnyEvent), then they will called directly after 984before or after loading AnyEvent), then they will be called directly
882the event loop has been chosen. 985after the event loop has been chosen.
883 986
884You should check C<$AnyEvent::MODEL> before adding to this array, though: 987You should check C<$AnyEvent::MODEL> before adding to this array, though:
885if it is defined then the event loop has already been detected, and the 988if it is defined then the event loop has already been detected, and the
886array will be ignored. 989array will be ignored.
887 990
888Best use C<AnyEvent::post_detect { BLOCK }> when your application allows 991Best use C<AnyEvent::post_detect { BLOCK }> when your application allows
889it,as it takes care of these details. 992it, as it takes care of these details.
890 993
891This variable is mainly useful for modules that can do something useful 994This variable is mainly useful for modules that can do something useful
892when AnyEvent is used and thus want to know when it is initialised, but do 995when AnyEvent is used and thus want to know when it is initialised, but do
893not need to even load it by default. This array provides the means to hook 996not need to even load it by default. This array provides the means to hook
894into AnyEvent passively, without loading it. 997into AnyEvent passively, without loading it.
895 998
999Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
1000together, you could put this into Coro (this is the actual code used by
1001Coro to accomplish this):
1002
1003 if (defined $AnyEvent::MODEL) {
1004 # AnyEvent already initialised, so load Coro::AnyEvent
1005 require Coro::AnyEvent;
1006 } else {
1007 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
1008 # as soon as it is
1009 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
1010 }
1011
1012=item AnyEvent::postpone { BLOCK }
1013
1014Arranges for the block to be executed as soon as possible, but not before
1015the call itself returns. In practise, the block will be executed just
1016before the event loop polls for new events, or shortly afterwards.
1017
1018This function never returns anything (to make the C<return postpone { ...
1019}> idiom more useful.
1020
1021To understand the usefulness of this function, consider a function that
1022asynchronously does something for you and returns some transaction
1023object or guard to let you cancel the operation. For example,
1024C<AnyEvent::Socket::tcp_connect>:
1025
1026 # start a conenction attempt unless one is active
1027 $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub {
1028 delete $self->{connect_guard};
1029 ...
1030 };
1031
1032Imagine that this function could instantly call the callback, for
1033example, because it detects an obvious error such as a negative port
1034number. Invoking the callback before the function returns causes problems
1035however: the callback will be called and will try to delete the guard
1036object. But since the function hasn't returned yet, there is nothing to
1037delete. When the function eventually returns it will assign the guard
1038object to C<< $self->{connect_guard} >>, where it will likely never be
1039deleted, so the program thinks it is still trying to connect.
1040
1041This is where C<AnyEvent::postpone> should be used. Instead of calling the
1042callback directly on error:
1043
1044 $cb->(undef), return # signal error to callback, BAD!
1045 if $some_error_condition;
1046
1047It should use C<postpone>:
1048
1049 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1050 if $some_error_condition;
1051
1052=item AnyEvent::log $level, $msg[, @args]
1053
1054Log the given C<$msg> at the given C<$level>.
1055
1056If L<AnyEvent::Log> is not loaded then this function makes a simple test
1057to see whether the message will be logged. If the test succeeds it will
1058load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1059the L<AnyEvent::Log> documentation for details.
1060
1061If the test fails it will simply return. Right now this happens when a
1062numerical loglevel is used and it is larger than the level specified via
1063C<$ENV{PERL_ANYEVENT_VERBOSE}>.
1064
1065If you want to sprinkle loads of logging calls around your code, consider
1066creating a logger callback with the C<AnyEvent::Log::logger> function,
1067which can reduce typing, codesize and can reduce the logging overhead
1068enourmously.
1069
896=back 1070=back
897 1071
898=head1 WHAT TO DO IN A MODULE 1072=head1 WHAT TO DO IN A MODULE
899 1073
900As a module author, you should C<use AnyEvent> and call AnyEvent methods 1074As a module author, you should C<use AnyEvent> and call AnyEvent methods
910because it will stall the whole program, and the whole point of using 1084because it will stall the whole program, and the whole point of using
911events is to stay interactive. 1085events is to stay interactive.
912 1086
913It is fine, however, to call C<< ->recv >> when the user of your module 1087It is fine, however, to call C<< ->recv >> when the user of your module
914requests it (i.e. if you create a http request object ad have a method 1088requests it (i.e. if you create a http request object ad have a method
915called C<results> that returns the results, it should call C<< ->recv >> 1089called C<results> that returns the results, it may call C<< ->recv >>
916freely, as the user of your module knows what she is doing. always). 1090freely, as the user of your module knows what she is doing. Always).
917 1091
918=head1 WHAT TO DO IN THE MAIN PROGRAM 1092=head1 WHAT TO DO IN THE MAIN PROGRAM
919 1093
920There will always be a single main program - the only place that should 1094There will always be a single main program - the only place that should
921dictate which event model to use. 1095dictate which event model to use.
922 1096
923If it doesn't care, it can just "use AnyEvent" and use it itself, or not 1097If the program is not event-based, it need not do anything special, even
924do anything special (it does not need to be event-based) and let AnyEvent 1098when it depends on a module that uses an AnyEvent. If the program itself
925decide which implementation to chose if some module relies on it. 1099uses AnyEvent, but does not care which event loop is used, all it needs
1100to do is C<use AnyEvent>. In either case, AnyEvent will choose the best
1101available loop implementation.
926 1102
927If the main program relies on a specific event model - for example, in 1103If the main program relies on a specific event model - for example, in
928Gtk2 programs you have to rely on the Glib module - you should load the 1104Gtk2 programs you have to rely on the Glib module - you should load the
929event module before loading AnyEvent or any module that uses it: generally 1105event module before loading AnyEvent or any module that uses it: generally
930speaking, you should load it as early as possible. The reason is that 1106speaking, you should load it as early as possible. The reason is that
931modules might create watchers when they are loaded, and AnyEvent will 1107modules might create watchers when they are loaded, and AnyEvent will
932decide on the event model to use as soon as it creates watchers, and it 1108decide on the event model to use as soon as it creates watchers, and it
933might chose the wrong one unless you load the correct one yourself. 1109might choose the wrong one unless you load the correct one yourself.
934 1110
935You can chose to use a pure-perl implementation by loading the 1111You can chose to use a pure-perl implementation by loading the
936C<AnyEvent::Impl::Perl> module, which gives you similar behaviour 1112C<AnyEvent::Loop> module, which gives you similar behaviour
937everywhere, but letting AnyEvent chose the model is generally better. 1113everywhere, but letting AnyEvent chose the model is generally better.
938 1114
939=head2 MAINLOOP EMULATION 1115=head2 MAINLOOP EMULATION
940 1116
941Sometimes (often for short test scripts, or even standalone programs who 1117Sometimes (often for short test scripts, or even standalone programs who
954 1130
955 1131
956=head1 OTHER MODULES 1132=head1 OTHER MODULES
957 1133
958The following is a non-exhaustive list of additional modules that use 1134The following is a non-exhaustive list of additional modules that use
959AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1135AnyEvent as a client and can therefore be mixed easily with other
960modules and other event loops in the same program. Some of the modules 1136AnyEvent modules and other event loops in the same program. Some of the
961come with AnyEvent, most are available via CPAN. 1137modules come as part of AnyEvent, the others are available via CPAN (see
1138L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1139a longer non-exhaustive list), and the list is heavily biased towards
1140modules of the AnyEvent author himself :)
962 1141
963=over 4 1142=over 4
964 1143
965=item L<AnyEvent::Util> 1144=item L<AnyEvent::Util>
966 1145
967Contains various utility functions that replace often-used but blocking 1146Contains various utility functions that replace often-used blocking
968functions such as C<inet_aton> by event-/callback-based versions. 1147functions such as C<inet_aton> with event/callback-based versions.
969 1148
970=item L<AnyEvent::Socket> 1149=item L<AnyEvent::Socket>
971 1150
972Provides various utility functions for (internet protocol) sockets, 1151Provides various utility functions for (internet protocol) sockets,
973addresses and name resolution. Also functions to create non-blocking tcp 1152addresses and name resolution. Also functions to create non-blocking tcp
975 1154
976=item L<AnyEvent::Handle> 1155=item L<AnyEvent::Handle>
977 1156
978Provide read and write buffers, manages watchers for reads and writes, 1157Provide read and write buffers, manages watchers for reads and writes,
979supports raw and formatted I/O, I/O queued and fully transparent and 1158supports raw and formatted I/O, I/O queued and fully transparent and
980non-blocking SSL/TLS (via L<AnyEvent::TLS>. 1159non-blocking SSL/TLS (via L<AnyEvent::TLS>).
981 1160
982=item L<AnyEvent::DNS> 1161=item L<AnyEvent::DNS>
983 1162
984Provides rich asynchronous DNS resolver capabilities. 1163Provides rich asynchronous DNS resolver capabilities.
985 1164
1165=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1166
1167Implement event-based interfaces to the protocols of the same name (for
1168the curious, IGS is the International Go Server and FCP is the Freenet
1169Client Protocol).
1170
986=item L<AnyEvent::HTTP> 1171=item L<AnyEvent::AIO>
987 1172
988A simple-to-use HTTP library that is capable of making a lot of concurrent 1173Truly asynchronous (as opposed to non-blocking) I/O, should be in the
989HTTP requests. 1174toolbox of every event programmer. AnyEvent::AIO transparently fuses
1175L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1176file I/O, and much more.
1177
1178=item L<AnyEvent::Filesys::Notify>
1179
1180AnyEvent is good for non-blocking stuff, but it can't detect file or
1181path changes (e.g. "watch this directory for new files", "watch this
1182file for changes"). The L<AnyEvent::Filesys::Notify> module promises to
1183do just that in a portbale fashion, supporting inotify on GNU/Linux and
1184some weird, without doubt broken, stuff on OS X to monitor files. It can
1185fall back to blocking scans at regular intervals transparently on other
1186platforms, so it's about as portable as it gets.
1187
1188(I haven't used it myself, but I haven't heard anybody complaining about
1189it yet).
1190
1191=item L<AnyEvent::DBI>
1192
1193Executes L<DBI> requests asynchronously in a proxy process for you,
1194notifying you in an event-based way when the operation is finished.
990 1195
991=item L<AnyEvent::HTTPD> 1196=item L<AnyEvent::HTTPD>
992 1197
993Provides a simple web application server framework. 1198A simple embedded webserver.
994 1199
995=item L<AnyEvent::FastPing> 1200=item L<AnyEvent::FastPing>
996 1201
997The fastest ping in the west. 1202The fastest ping in the west.
998 1203
999=item L<AnyEvent::DBI>
1000
1001Executes L<DBI> requests asynchronously in a proxy process.
1002
1003=item L<AnyEvent::AIO>
1004
1005Truly asynchronous I/O, should be in the toolbox of every event
1006programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
1007together.
1008
1009=item L<AnyEvent::BDB>
1010
1011Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
1012L<BDB> and AnyEvent together.
1013
1014=item L<AnyEvent::GPSD>
1015
1016A non-blocking interface to gpsd, a daemon delivering GPS information.
1017
1018=item L<AnyEvent::IRC>
1019
1020AnyEvent based IRC client module family (replacing the older Net::IRC3).
1021
1022=item L<AnyEvent::XMPP>
1023
1024AnyEvent based XMPP (Jabber protocol) module family (replacing the older
1025Net::XMPP2>.
1026
1027=item L<AnyEvent::IGS>
1028
1029A non-blocking interface to the Internet Go Server protocol (used by
1030L<App::IGS>).
1031
1032=item L<Net::FCP>
1033
1034AnyEvent-based implementation of the Freenet Client Protocol, birthplace
1035of AnyEvent.
1036
1037=item L<Event::ExecFlow>
1038
1039High level API for event-based execution flow control.
1040
1041=item L<Coro> 1204=item L<Coro>
1042 1205
1043Has special support for AnyEvent via L<Coro::AnyEvent>. 1206Has special support for AnyEvent via L<Coro::AnyEvent>, which allows you
1207to simply invert the flow control - don't call us, we will call you:
1208
1209 async {
1210 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1211 print "5 seconds later!\n";
1212
1213 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1214 my $line = <STDIN>; # works for ttys
1215
1216 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1217 my ($body, $hdr) = Coro::rouse_wait;
1218 };
1044 1219
1045=back 1220=back
1046 1221
1047=cut 1222=cut
1048 1223
1049package AnyEvent; 1224package AnyEvent;
1050 1225
1051# basically a tuned-down version of common::sense 1226# basically a tuned-down version of common::sense
1052sub common_sense { 1227sub common_sense {
1053 # no warnings 1228 # from common:.sense 3.4
1054 ${^WARNING_BITS} ^= ${^WARNING_BITS}; 1229 ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "\x3c\x3f\x33\x00\x0f\xf0\x0f\xc0\xf0\xfc\x33\x00";
1055 # use strict vars subs 1230 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1056 $^H |= 0x00000600; 1231 $^H |= 0x00000600;
1057} 1232}
1058 1233
1059BEGIN { AnyEvent::common_sense } 1234BEGIN { AnyEvent::common_sense }
1060 1235
1061use Carp (); 1236use Carp ();
1062 1237
1063our $VERSION = 4.85; 1238our $VERSION = '6.02';
1064our $MODEL; 1239our $MODEL;
1065
1066our $AUTOLOAD;
1067our @ISA; 1240our @ISA;
1068
1069our @REGISTRY; 1241our @REGISTRY;
1070
1071our $WIN32;
1072
1073our $VERBOSE; 1242our $VERBOSE;
1243our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1244our $MAX_SIGNAL_LATENCY = $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} || 10; # executes after the BEGIN block below (tainting!)
1074 1245
1075BEGIN { 1246BEGIN {
1076 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1247 require "AnyEvent/constants.pl";
1248
1077 eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; 1249 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1078 1250
1079 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1251 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1080 if ${^TAINT}; 1252 if ${^TAINT};
1081 1253
1082 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1254 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1255 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1083 1256
1084} 1257 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1258 if ${^TAINT};
1085 1259
1086our $MAX_SIGNAL_LATENCY = 10; 1260 # $ENV{PERL_ANYEVENT_xxx} now valid
1087 1261
1088our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1262 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1089 1263
1090{
1091 my $idx; 1264 my $idx;
1092 $PROTOCOL{$_} = ++$idx 1265 $PROTOCOL{$_} = ++$idx
1093 for reverse split /\s*,\s*/, 1266 for reverse split /\s*,\s*/,
1094 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1267 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1095} 1268}
1096 1269
1270our @post_detect;
1271
1272sub post_detect(&) {
1273 my ($cb) = @_;
1274
1275 push @post_detect, $cb;
1276
1277 defined wantarray
1278 ? bless \$cb, "AnyEvent::Util::postdetect"
1279 : ()
1280}
1281
1282sub AnyEvent::Util::postdetect::DESTROY {
1283 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1284}
1285
1286our $POSTPONE_W;
1287our @POSTPONE;
1288
1289sub _postpone_exec {
1290 undef $POSTPONE_W;
1291
1292 &{ shift @POSTPONE }
1293 while @POSTPONE;
1294}
1295
1296sub postpone(&) {
1297 push @POSTPONE, shift;
1298
1299 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1300
1301 ()
1302}
1303
1304sub log($$;@) {
1305 # only load the big bloated module when we actually are about to log something
1306 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1307 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1308 # AnyEvent::Log overwrites this function
1309 goto &log;
1310 }
1311
1312 0 # not logged
1313}
1314
1315sub logger($;$) {
1316 package AnyEvent::Log;
1317
1318 my ($level, $renabled) = @_;
1319
1320 $$renabled = $level <= $VERBOSE;
1321
1322 my $pkg = (caller)[0];
1323
1324 my $logger = [$pkg, $level, $renabled];
1325
1326 our %LOGGER;
1327 $LOGGER{$logger+0} = $logger;
1328
1329 require AnyEvent::Util;
1330 my $guard = AnyEvent::Util::guard (sub {
1331 # "clean up"
1332 delete $LOGGER{$logger+0};
1333 });
1334
1335 sub {
1336 return 0 unless $$renabled;
1337
1338 $guard if 0; # keep guard alive, but don't cause runtime overhead
1339 require AnyEvent::Log unless $AnyEvent::Log::VERSION;
1340 package AnyEvent::Log;
1341 _log ($logger->[0], $level, @_) # logger->[0] has been converted at load time
1342 }
1343}
1344
1345if (length $ENV{PERL_ANYEVENT_LOG}) {
1346 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1347}
1348
1097my @models = ( 1349our @models = (
1098 [EV:: => AnyEvent::Impl::EV::], 1350 [EV:: => AnyEvent::Impl::EV::],
1099 [Event:: => AnyEvent::Impl::Event::],
1100 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1351 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1101 # everything below here will not be autoprobed 1352 # everything below here will not (normally) be autoprobed
1102 # as the pureperl backend should work everywhere 1353 # as the pure perl backend should work everywhere
1103 # and is usually faster 1354 # and is usually faster
1355 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package, so msut be near the top
1356 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1104 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1357 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1358 # everything below here should not be autoloaded
1105 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1359 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1106 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1360 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1107 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1361 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1108 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1362 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1109 [Wx:: => AnyEvent::Impl::POE::], 1363 [Wx:: => AnyEvent::Impl::POE::],
1110 [Prima:: => AnyEvent::Impl::POE::], 1364 [Prima:: => AnyEvent::Impl::POE::],
1111 # IO::Async is just too broken - we would need workarounds for its 1365 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1112 # byzantine signal and broken child handling, among others. 1366 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1113 # IO::Async is rather hard to detect, as it doesn't have any 1367 [FLTK:: => AnyEvent::Impl::FLTK::],
1114 # obvious default class.
1115# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1116# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1117# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1118); 1368);
1119 1369
1120our %method = map +($_ => 1), 1370our @isa_hook;
1371
1372sub _isa_set {
1373 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1374
1375 @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1376 for 1 .. $#pkg;
1377
1378 grep $_ && $_->[1], @isa_hook
1379 and AE::_reset ();
1380}
1381
1382# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1383sub _isa_hook($$;$) {
1384 my ($i, $pkg, $reset_ae) = @_;
1385
1386 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1387
1388 _isa_set;
1389}
1390
1391# all autoloaded methods reserve the complete glob, not just the method slot.
1392# due to bugs in perls method cache implementation.
1121 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1393our @methods = qw(io timer time now now_update signal child idle condvar);
1122 1394
1123our @post_detect;
1124
1125sub post_detect(&) { 1395sub detect() {
1126 my ($cb) = @_; 1396 return $MODEL if $MODEL; # some programs keep references to detect
1127 1397
1128 if ($MODEL) { 1398 # IO::Async::Loop::AnyEvent is extremely evil, refuse to work with it
1129 $cb->(); 1399 # the author knows about the problems and what it does to AnyEvent as a whole
1400 # (and the ability of others to use AnyEvent), but simply wants to abuse AnyEvent
1401 # anyway.
1402 AnyEvent::log fatal => "AnyEvent: IO::Async::Loop::AnyEvent detected - this module is broken by design,\n"
1403 . "abuses internals and breaks AnyEvent, will not continue."
1404 if exists $INC{"IO/Async/Loop/AnyEvent.pm"};
1130 1405
1131 1 1406 local $!; # for good measure
1407 local $SIG{__DIE__}; # we use eval
1408
1409 # free some memory
1410 *detect = sub () { $MODEL };
1411 # undef &func doesn't correctly update the method cache. grmbl.
1412 # so we delete the whole glob. grmbl.
1413 # otoh, perl doesn't let me undef an active usb, but it lets me free
1414 # a glob with an active sub. hrm. i hope it works, but perl is
1415 # usually buggy in this department. sigh.
1416 delete @{"AnyEvent::"}{@methods};
1417 undef @methods;
1418
1419 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1420 my $model = $1;
1421 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1422 if (eval "require $model") {
1423 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1424 $MODEL = $model;
1132 } else { 1425 } else {
1133 push @post_detect, $cb; 1426 AnyEvent::log 4 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1134 1427 }
1135 defined wantarray
1136 ? bless \$cb, "AnyEvent::Util::postdetect"
1137 : ()
1138 } 1428 }
1139}
1140 1429
1141sub AnyEvent::Util::postdetect::DESTROY { 1430 # check for already loaded models
1142 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1143}
1144
1145sub detect() {
1146 unless ($MODEL) { 1431 unless ($MODEL) {
1147 local $SIG{__DIE__}; 1432 for (@REGISTRY, @models) {
1148 1433 my ($package, $model) = @$_;
1149 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1434 if (${"$package\::VERSION"} > 0) {
1150 my $model = "AnyEvent::Impl::$1";
1151 if (eval "require $model") { 1435 if (eval "require $model") {
1436 AnyEvent::log 7 => "autodetected model '$model', using it.";
1152 $MODEL = $model; 1437 $MODEL = $model;
1153 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2; 1438 last;
1154 } else { 1439 }
1155 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
1156 } 1440 }
1157 } 1441 }
1158 1442
1159 # check for already loaded models
1160 unless ($MODEL) { 1443 unless ($MODEL) {
1444 # try to autoload a model
1161 for (@REGISTRY, @models) { 1445 for (@REGISTRY, @models) {
1162 my ($package, $model) = @$_; 1446 my ($package, $model) = @$_;
1447 if (
1448 eval "require $package"
1163 if (${"$package\::VERSION"} > 0) { 1449 and ${"$package\::VERSION"} > 0
1164 if (eval "require $model") { 1450 and eval "require $model"
1451 ) {
1452 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1165 $MODEL = $model; 1453 $MODEL = $model;
1166 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1167 last; 1454 last;
1168 }
1169 } 1455 }
1170 } 1456 }
1171 1457
1172 unless ($MODEL) {
1173 # try to load a model
1174
1175 for (@REGISTRY, @models) {
1176 my ($package, $model) = @$_;
1177 if (eval "require $package"
1178 and ${"$package\::VERSION"} > 0
1179 and eval "require $model") {
1180 $MODEL = $model;
1181 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2;
1182 last;
1183 }
1184 }
1185
1186 $MODEL 1458 $MODEL
1187 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n"; 1459 or AnyEvent::log fatal => "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1188 }
1189 } 1460 }
1190
1191 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1192
1193 unshift @ISA, $MODEL;
1194
1195 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
1196
1197 (shift @post_detect)->() while @post_detect;
1198 } 1461 }
1199 1462
1463 # free memory only needed for probing
1464 undef @models;
1465 undef @REGISTRY;
1466
1467 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1468
1469 # now nuke some methods that are overridden by the backend.
1470 # SUPER usage is not allowed in these.
1471 for (qw(time signal child idle)) {
1472 undef &{"AnyEvent::Base::$_"}
1473 if defined &{"$MODEL\::$_"};
1474 }
1475
1476 _isa_set;
1477
1478 # we're officially open!
1479
1480 if ($ENV{PERL_ANYEVENT_STRICT}) {
1481 require AnyEvent::Strict;
1482 }
1483
1484 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1485 require AnyEvent::Debug;
1486 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1487 }
1488
1489 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1490 require AnyEvent::Socket;
1491 require AnyEvent::Debug;
1492
1493 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1494 $shell =~ s/\$\$/$$/g;
1495
1496 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1497 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1498 }
1499
1500 # now the anyevent environment is set up as the user told us to, so
1501 # call the actual user code - post detects
1502
1503 (shift @post_detect)->() while @post_detect;
1504 undef @post_detect;
1505
1506 *post_detect = sub(&) {
1507 shift->();
1508
1509 undef
1510 };
1511
1200 $MODEL 1512 $MODEL
1201} 1513}
1202 1514
1203sub AUTOLOAD { 1515for my $name (@methods) {
1204 (my $func = $AUTOLOAD) =~ s/.*://; 1516 *$name = sub {
1205 1517 detect;
1206 $method{$func} 1518 # we use goto because
1207 or Carp::croak "$func: not a valid method for AnyEvent objects"; 1519 # a) it makes the thunk more transparent
1208 1520 # b) it allows us to delete the thunk later
1209 detect unless $MODEL; 1521 goto &{ UNIVERSAL::can AnyEvent => "SUPER::$name" }
1210 1522 };
1211 my $class = shift;
1212 $class->$func (@_);
1213} 1523}
1214 1524
1215# utility function to dup a filehandle. this is used by many backends 1525# utility function to dup a filehandle. this is used by many backends
1216# to support binding more than one watcher per filehandle (they usually 1526# to support binding more than one watcher per filehandle (they usually
1217# allow only one watcher per fd, so we dup it to get a different one). 1527# allow only one watcher per fd, so we dup it to get a different one).
1227 # we assume CLOEXEC is already set by perl in all important cases 1537 # we assume CLOEXEC is already set by perl in all important cases
1228 1538
1229 ($fh2, $rw) 1539 ($fh2, $rw)
1230} 1540}
1231 1541
1542=head1 SIMPLIFIED AE API
1543
1544Starting with version 5.0, AnyEvent officially supports a second, much
1545simpler, API that is designed to reduce the calling, typing and memory
1546overhead by using function call syntax and a fixed number of parameters.
1547
1548See the L<AE> manpage for details.
1549
1550=cut
1551
1552package AE;
1553
1554our $VERSION = $AnyEvent::VERSION;
1555
1556sub _reset() {
1557 eval q{
1558 # fall back to the main API by default - backends and AnyEvent::Base
1559 # implementations can overwrite these.
1560
1561 sub io($$$) {
1562 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1563 }
1564
1565 sub timer($$$) {
1566 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1567 }
1568
1569 sub signal($$) {
1570 AnyEvent->signal (signal => $_[0], cb => $_[1])
1571 }
1572
1573 sub child($$) {
1574 AnyEvent->child (pid => $_[0], cb => $_[1])
1575 }
1576
1577 sub idle($) {
1578 AnyEvent->idle (cb => $_[0]);
1579 }
1580
1581 sub cv(;&) {
1582 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1583 }
1584
1585 sub now() {
1586 AnyEvent->now
1587 }
1588
1589 sub now_update() {
1590 AnyEvent->now_update
1591 }
1592
1593 sub time() {
1594 AnyEvent->time
1595 }
1596
1597 *postpone = \&AnyEvent::postpone;
1598 *log = \&AnyEvent::log;
1599 };
1600 die if $@;
1601}
1602
1603BEGIN { _reset }
1604
1232package AnyEvent::Base; 1605package AnyEvent::Base;
1233 1606
1234# default implementations for many methods 1607# default implementations for many methods
1235 1608
1236sub _time { 1609sub time {
1610 eval q{ # poor man's autoloading {}
1237 # probe for availability of Time::HiRes 1611 # probe for availability of Time::HiRes
1238 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1612 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1239 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1613 *time = sub { Time::HiRes::time () };
1240 *_time = \&Time::HiRes::time; 1614 *AE::time = \& Time::HiRes::time ;
1615 *now = \&time;
1616 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1241 # if (eval "use POSIX (); (POSIX::times())... 1617 # if (eval "use POSIX (); (POSIX::times())...
1242 } else { 1618 } else {
1619 *time = sub { CORE::time };
1620 *AE::time = sub (){ CORE::time };
1621 *now = \&time;
1243 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1622 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1244 *_time = sub { time }; # epic fail 1623 }
1245 } 1624 };
1625 die if $@;
1246 1626
1247 &_time 1627 &time
1248} 1628}
1249 1629
1250sub time { _time } 1630*now = \&time;
1251sub now { _time }
1252sub now_update { } 1631sub now_update { }
1253 1632
1633sub _poll {
1634 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1635}
1636
1254# default implementation for ->condvar 1637# default implementation for ->condvar
1638# in fact, the default should not be overwritten
1255 1639
1256sub condvar { 1640sub condvar {
1641 eval q{ # poor man's autoloading {}
1642 *condvar = sub {
1257 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" 1643 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1644 };
1645
1646 *AE::cv = sub (;&) {
1647 bless { @_ ? (_ae_cb => shift) : () }, "AnyEvent::CondVar"
1648 };
1649 };
1650 die if $@;
1651
1652 &condvar
1258} 1653}
1259 1654
1260# default implementation for ->signal 1655# default implementation for ->signal
1261 1656
1262our $HAVE_ASYNC_INTERRUPT; 1657our $HAVE_ASYNC_INTERRUPT;
1658
1659sub _have_async_interrupt() {
1660 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT}
1661 && eval "use Async::Interrupt 1.02 (); 1")
1662 unless defined $HAVE_ASYNC_INTERRUPT;
1663
1664 $HAVE_ASYNC_INTERRUPT
1665}
1666
1263our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1667our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1264our (%SIG_ASY, %SIG_ASY_W); 1668our (%SIG_ASY, %SIG_ASY_W);
1265our ($SIG_COUNT, $SIG_TW); 1669our ($SIG_COUNT, $SIG_TW);
1266 1670
1267sub _signal_exec {
1268 $HAVE_ASYNC_INTERRUPT
1269 ? $SIGPIPE_R->drain
1270 : sysread $SIGPIPE_R, my $dummy, 9;
1271
1272 while (%SIG_EV) {
1273 for (keys %SIG_EV) {
1274 delete $SIG_EV{$_};
1275 $_->() for values %{ $SIG_CB{$_} || {} };
1276 }
1277 }
1278}
1279
1280# install a dumym wakeupw atcher to reduce signal catching latency 1671# install a dummy wakeup watcher to reduce signal catching latency
1672# used by Impls
1281sub _sig_add() { 1673sub _sig_add() {
1282 unless ($SIG_COUNT++) { 1674 unless ($SIG_COUNT++) {
1283 # try to align timer on a full-second boundary, if possible 1675 # try to align timer on a full-second boundary, if possible
1284 my $NOW = AnyEvent->now; 1676 my $NOW = AE::now;
1285 1677
1286 $SIG_TW = AnyEvent->timer ( 1678 $SIG_TW = AE::timer
1287 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW), 1679 $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1288 interval => $MAX_SIGNAL_LATENCY, 1680 $MAX_SIGNAL_LATENCY,
1289 cb => sub { }, # just for the PERL_ASYNC_CHECK 1681 sub { } # just for the PERL_ASYNC_CHECK
1290 ); 1682 ;
1291 } 1683 }
1292} 1684}
1293 1685
1294sub _sig_del { 1686sub _sig_del {
1295 undef $SIG_TW 1687 undef $SIG_TW
1296 unless --$SIG_COUNT; 1688 unless --$SIG_COUNT;
1297} 1689}
1298 1690
1691our $_sig_name_init; $_sig_name_init = sub {
1692 eval q{ # poor man's autoloading {}
1693 undef $_sig_name_init;
1694
1695 if (_have_async_interrupt) {
1696 *sig2num = \&Async::Interrupt::sig2num;
1697 *sig2name = \&Async::Interrupt::sig2name;
1698 } else {
1699 require Config;
1700
1701 my %signame2num;
1702 @signame2num{ split ' ', $Config::Config{sig_name} }
1703 = split ' ', $Config::Config{sig_num};
1704
1705 my @signum2name;
1706 @signum2name[values %signame2num] = keys %signame2num;
1707
1708 *sig2num = sub($) {
1709 $_[0] > 0 ? shift : $signame2num{+shift}
1710 };
1711 *sig2name = sub ($) {
1712 $_[0] > 0 ? $signum2name[+shift] : shift
1713 };
1714 }
1715 };
1716 die if $@;
1717};
1718
1719sub sig2num ($) { &$_sig_name_init; &sig2num }
1720sub sig2name($) { &$_sig_name_init; &sig2name }
1721
1299sub _signal { 1722sub signal {
1300 my (undef, %arg) = @_; 1723 eval q{ # poor man's autoloading {}
1724 # probe for availability of Async::Interrupt
1725 if (_have_async_interrupt) {
1726 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1301 1727
1302 my $signal = uc $arg{signal} 1728 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1303 or Carp::croak "required option 'signal' is missing"; 1729 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1304 1730
1305 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1731 } else {
1732 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1306 1733
1307 if ($HAVE_ASYNC_INTERRUPT) { 1734 if (AnyEvent::WIN32) {
1308 # async::interrupt 1735 require AnyEvent::Util;
1309 1736
1310 $SIG_ASY{$signal} ||= do { 1737 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1311 my $asy = new Async::Interrupt 1738 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
1312 cb => sub { undef $SIG_EV{$signal} }, 1739 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case
1313 signal => $signal, 1740 } else {
1314 pipe => [$SIGPIPE_R->filenos], 1741 pipe $SIGPIPE_R, $SIGPIPE_W;
1742 fcntl $SIGPIPE_R, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_R;
1743 fcntl $SIGPIPE_W, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_W; # just in case
1744
1745 # not strictly required, as $^F is normally 2, but let's make sure...
1746 fcntl $SIGPIPE_R, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1747 fcntl $SIGPIPE_W, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1315 ; 1748 }
1316 $asy->pipe_autodrain (0);
1317 1749
1318 $asy 1750 $SIGPIPE_R
1751 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1752
1753 $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;
1754 }
1755
1756 *signal = $HAVE_ASYNC_INTERRUPT
1757 ? sub {
1758 my (undef, %arg) = @_;
1759
1760 # async::interrupt
1761 my $signal = sig2num $arg{signal};
1762 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1763
1764 $SIG_ASY{$signal} ||= new Async::Interrupt
1765 cb => sub { undef $SIG_EV{$signal} },
1766 signal => $signal,
1767 pipe => [$SIGPIPE_R->filenos],
1768 pipe_autodrain => 0,
1769 ;
1770
1771 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1772 }
1773 : sub {
1774 my (undef, %arg) = @_;
1775
1776 # pure perl
1777 my $signal = sig2name $arg{signal};
1778 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1779
1780 $SIG{$signal} ||= sub {
1781 local $!;
1782 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1783 undef $SIG_EV{$signal};
1784 };
1785
1786 # can't do signal processing without introducing races in pure perl,
1787 # so limit the signal latency.
1788 _sig_add;
1789
1790 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1791 }
1792 ;
1793
1794 *AnyEvent::Base::signal::DESTROY = sub {
1795 my ($signal, $cb) = @{$_[0]};
1796
1797 _sig_del;
1798
1799 delete $SIG_CB{$signal}{$cb};
1800
1801 $HAVE_ASYNC_INTERRUPT
1802 ? delete $SIG_ASY{$signal}
1803 : # delete doesn't work with older perls - they then
1804 # print weird messages, or just unconditionally exit
1805 # instead of getting the default action.
1806 undef $SIG{$signal}
1807 unless keys %{ $SIG_CB{$signal} };
1319 }; 1808 };
1320 1809
1321 } else { 1810 *_signal_exec = sub {
1322 # pure perl 1811 $HAVE_ASYNC_INTERRUPT
1812 ? $SIGPIPE_R->drain
1813 : sysread $SIGPIPE_R, (my $dummy), 9;
1323 1814
1324 $SIG{$signal} ||= sub { 1815 while (%SIG_EV) {
1325 local $!; 1816 for (keys %SIG_EV) {
1326 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1817 delete $SIG_EV{$_};
1327 undef $SIG_EV{$signal}; 1818 &$_ for values %{ $SIG_CB{$_} || {} };
1819 }
1820 }
1328 }; 1821 };
1329
1330 # can't do signal processing without introducing races in pure perl,
1331 # so limit the signal latency.
1332 _sig_add;
1333 } 1822 };
1823 die if $@;
1334 1824
1335 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1336}
1337
1338sub signal {
1339 # probe for availability of Async::Interrupt
1340 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 0.6 (); 1") {
1341 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1342
1343 $HAVE_ASYNC_INTERRUPT = 1;
1344 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1345 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1346
1347 } else {
1348 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1349
1350 require Fcntl;
1351
1352 if (AnyEvent::WIN32) {
1353 require AnyEvent::Util;
1354
1355 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1356 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R) if $SIGPIPE_R;
1357 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case
1358 } else {
1359 pipe $SIGPIPE_R, $SIGPIPE_W;
1360 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
1361 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
1362
1363 # not strictly required, as $^F is normally 2, but let's make sure...
1364 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1365 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1366 }
1367
1368 $SIGPIPE_R
1369 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1370
1371 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1372 }
1373
1374 *signal = \&_signal;
1375 &signal 1825 &signal
1376}
1377
1378sub AnyEvent::Base::signal::DESTROY {
1379 my ($signal, $cb) = @{$_[0]};
1380
1381 _sig_del;
1382
1383 delete $SIG_CB{$signal}{$cb};
1384
1385 $HAVE_ASYNC_INTERRUPT
1386 ? delete $SIG_ASY{$signal}
1387 : # delete doesn't work with older perls - they then
1388 # print weird messages, or just unconditionally exit
1389 # instead of getting the default action.
1390 undef $SIG{$signal}
1391 unless keys %{ $SIG_CB{$signal} };
1392} 1826}
1393 1827
1394# default implementation for ->child 1828# default implementation for ->child
1395 1829
1396our %PID_CB; 1830our %PID_CB;
1397our $CHLD_W; 1831our $CHLD_W;
1398our $CHLD_DELAY_W; 1832our $CHLD_DELAY_W;
1399our $WNOHANG;
1400 1833
1401sub _sigchld { 1834# used by many Impl's
1402 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1835sub _emit_childstatus($$) {
1403 $_->($pid, $?) 1836 my (undef, $rpid, $rstatus) = @_;
1837
1838 $_->($rpid, $rstatus)
1404 for values %{ $PID_CB{$pid} || {} }, 1839 for values %{ $PID_CB{$rpid} || {} },
1405 values %{ $PID_CB{0} || {} }; 1840 values %{ $PID_CB{0} || {} };
1406 }
1407} 1841}
1408 1842
1409sub child { 1843sub child {
1844 eval q{ # poor man's autoloading {}
1845 *_sigchld = sub {
1846 my $pid;
1847
1848 AnyEvent->_emit_childstatus ($pid, $?)
1849 while ($pid = waitpid -1, WNOHANG) > 0;
1850 };
1851
1852 *child = sub {
1410 my (undef, %arg) = @_; 1853 my (undef, %arg) = @_;
1411 1854
1412 defined (my $pid = $arg{pid} + 0) 1855 my $pid = $arg{pid};
1413 or Carp::croak "required option 'pid' is missing"; 1856 my $cb = $arg{cb};
1414 1857
1415 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1858 $PID_CB{$pid}{$cb+0} = $cb;
1416 1859
1417 # WNOHANG is almost cetrainly 1 everywhere
1418 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1419 ? 1
1420 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1421
1422 unless ($CHLD_W) { 1860 unless ($CHLD_W) {
1423 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1861 $CHLD_W = AE::signal CHLD => \&_sigchld;
1424 # child could be a zombie already, so make at least one round 1862 # child could be a zombie already, so make at least one round
1425 &_sigchld; 1863 &_sigchld;
1426 } 1864 }
1427 1865
1428 bless [$pid, $arg{cb}], "AnyEvent::Base::child" 1866 bless [$pid, $cb+0], "AnyEvent::Base::child"
1429} 1867 };
1430 1868
1431sub AnyEvent::Base::child::DESTROY { 1869 *AnyEvent::Base::child::DESTROY = sub {
1432 my ($pid, $cb) = @{$_[0]}; 1870 my ($pid, $icb) = @{$_[0]};
1433 1871
1434 delete $PID_CB{$pid}{$cb}; 1872 delete $PID_CB{$pid}{$icb};
1435 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1873 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1436 1874
1437 undef $CHLD_W unless keys %PID_CB; 1875 undef $CHLD_W unless keys %PID_CB;
1876 };
1877 };
1878 die if $@;
1879
1880 &child
1438} 1881}
1439 1882
1440# idle emulation is done by simply using a timer, regardless 1883# idle emulation is done by simply using a timer, regardless
1441# of whether the process is idle or not, and not letting 1884# of whether the process is idle or not, and not letting
1442# the callback use more than 50% of the time. 1885# the callback use more than 50% of the time.
1443sub idle { 1886sub idle {
1887 eval q{ # poor man's autoloading {}
1888 *idle = sub {
1444 my (undef, %arg) = @_; 1889 my (undef, %arg) = @_;
1445 1890
1446 my ($cb, $w, $rcb) = $arg{cb}; 1891 my ($cb, $w, $rcb) = $arg{cb};
1447 1892
1448 $rcb = sub { 1893 $rcb = sub {
1449 if ($cb) { 1894 if ($cb) {
1450 $w = _time; 1895 $w = AE::time;
1451 &$cb; 1896 &$cb;
1452 $w = _time - $w; 1897 $w = AE::time - $w;
1453 1898
1454 # never use more then 50% of the time for the idle watcher, 1899 # never use more then 50% of the time for the idle watcher,
1455 # within some limits 1900 # within some limits
1456 $w = 0.0001 if $w < 0.0001; 1901 $w = 0.0001 if $w < 0.0001;
1457 $w = 5 if $w > 5; 1902 $w = 5 if $w > 5;
1458 1903
1459 $w = AnyEvent->timer (after => $w, cb => $rcb); 1904 $w = AE::timer $w, 0, $rcb;
1460 } else { 1905 } else {
1461 # clean up... 1906 # clean up...
1462 undef $w; 1907 undef $w;
1463 undef $rcb; 1908 undef $rcb;
1909 }
1910 };
1911
1912 $w = AE::timer 0.05, 0, $rcb;
1913
1914 bless \\$cb, "AnyEvent::Base::idle"
1464 } 1915 };
1916
1917 *AnyEvent::Base::idle::DESTROY = sub {
1918 undef $${$_[0]};
1919 };
1465 }; 1920 };
1921 die if $@;
1466 1922
1467 $w = AnyEvent->timer (after => 0.05, cb => $rcb); 1923 &idle
1468
1469 bless \\$cb, "AnyEvent::Base::idle"
1470}
1471
1472sub AnyEvent::Base::idle::DESTROY {
1473 undef $${$_[0]};
1474} 1924}
1475 1925
1476package AnyEvent::CondVar; 1926package AnyEvent::CondVar;
1477 1927
1478our @ISA = AnyEvent::CondVar::Base::; 1928our @ISA = AnyEvent::CondVar::Base::;
1929
1930# only to be used for subclassing
1931sub new {
1932 my $class = shift;
1933 bless AnyEvent->condvar (@_), $class
1934}
1479 1935
1480package AnyEvent::CondVar::Base; 1936package AnyEvent::CondVar::Base;
1481 1937
1482#use overload 1938#use overload
1483# '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1939# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1493 1949
1494sub _send { 1950sub _send {
1495 # nop 1951 # nop
1496} 1952}
1497 1953
1954sub _wait {
1955 AnyEvent->_poll until $_[0]{_ae_sent};
1956}
1957
1498sub send { 1958sub send {
1499 my $cv = shift; 1959 my $cv = shift;
1500 $cv->{_ae_sent} = [@_]; 1960 $cv->{_ae_sent} = [@_];
1501 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb}; 1961 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
1502 $cv->_send; 1962 $cv->_send;
1509 1969
1510sub ready { 1970sub ready {
1511 $_[0]{_ae_sent} 1971 $_[0]{_ae_sent}
1512} 1972}
1513 1973
1514sub _wait {
1515 $WAITING
1516 and !$_[0]{_ae_sent}
1517 and Carp::croak "AnyEvent::CondVar: recursive blocking wait detected";
1518
1519 local $WAITING = 1;
1520 AnyEvent->one_event while !$_[0]{_ae_sent};
1521}
1522
1523sub recv { 1974sub recv {
1975 unless ($_[0]{_ae_sent}) {
1976 $WAITING
1977 and Carp::croak "AnyEvent::CondVar: recursive blocking wait attempted";
1978
1979 local $WAITING = 1;
1524 $_[0]->_wait; 1980 $_[0]->_wait;
1981 }
1525 1982
1526 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak}; 1983 $_[0]{_ae_croak}
1527 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0] 1984 and Carp::croak $_[0]{_ae_croak};
1985
1986 wantarray
1987 ? @{ $_[0]{_ae_sent} }
1988 : $_[0]{_ae_sent}[0]
1528} 1989}
1529 1990
1530sub cb { 1991sub cb {
1531 $_[0]{_ae_cb} = $_[1] if @_ > 1; 1992 my $cv = shift;
1993
1994 @_
1995 and $cv->{_ae_cb} = shift
1996 and $cv->{_ae_sent}
1997 and (delete $cv->{_ae_cb})->($cv);
1998
1532 $_[0]{_ae_cb} 1999 $cv->{_ae_cb}
1533} 2000}
1534 2001
1535sub begin { 2002sub begin {
1536 ++$_[0]{_ae_counter}; 2003 ++$_[0]{_ae_counter};
1537 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 2004 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
1542 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } }; 2009 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
1543} 2010}
1544 2011
1545# undocumented/compatibility with pre-3.4 2012# undocumented/compatibility with pre-3.4
1546*broadcast = \&send; 2013*broadcast = \&send;
1547*wait = \&_wait; 2014*wait = \&recv;
1548 2015
1549=head1 ERROR AND EXCEPTION HANDLING 2016=head1 ERROR AND EXCEPTION HANDLING
1550 2017
1551In general, AnyEvent does not do any error handling - it relies on the 2018In general, AnyEvent does not do any error handling - it relies on the
1552caller to do that if required. The L<AnyEvent::Strict> module (see also 2019caller to do that if required. The L<AnyEvent::Strict> module (see also
1564$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2031$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1565so on. 2032so on.
1566 2033
1567=head1 ENVIRONMENT VARIABLES 2034=head1 ENVIRONMENT VARIABLES
1568 2035
1569The following environment variables are used by this module or its 2036AnyEvent supports a number of environment variables that tune the
1570submodules. 2037runtime behaviour. They are usually evaluated when AnyEvent is
2038loaded, initialised, or a submodule that uses them is loaded. Many of
2039them also cause AnyEvent to load additional modules - for example,
2040C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2041loaded.
1571 2042
1572Note that AnyEvent will remove I<all> environment variables starting with 2043All the environment variables documented here start with
1573C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2044C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1574enabled. 2045namespace. Other modules are encouraged (but by no means required) to use
2046C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2047namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2048be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2049variables starting with C<AE_>, see below).
2050
2051All variables can also be set via the C<AE_> prefix, that is, instead
2052of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2053case there is a clash btween anyevent and another program that uses
2054C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2055variable to the empty string, as those variables take precedence.
2056
2057When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2058to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2059exists. If taint mode is on, then AnyEvent will remove I<all> environment
2060variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2061with C<undef> or the empty string, if the corresaponding C<AE_> variable
2062is set).
2063
2064The exact algorithm is currently:
2065
2066 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2067 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2068 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2069
2070This ensures that child processes will not see the C<AE_> variables.
2071
2072The following environment variables are currently known to AnyEvent:
1575 2073
1576=over 4 2074=over 4
1577 2075
1578=item C<PERL_ANYEVENT_VERBOSE> 2076=item C<PERL_ANYEVENT_VERBOSE>
1579 2077
1580By default, AnyEvent will be completely silent except in fatal 2078By default, AnyEvent will only log messages with loglevel C<3>
1581conditions. You can set this environment variable to make AnyEvent more 2079(C<critical>) or higher (see L<AnyEvent::Log>). You can set this
2080environment variable to a numerical loglevel to make AnyEvent more (or
1582talkative. 2081less) talkative.
1583 2082
2083If you want to do more than just set the global logging level
2084you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2085complex specifications.
2086
2087When set to C<0> (C<off>), then no messages whatsoever will be logged with
2088the default logging settings.
2089
1584When set to C<1> or higher, causes AnyEvent to warn about unexpected 2090When set to C<5> or higher (C<warn>), causes AnyEvent to warn about
1585conditions, such as not being able to load the event model specified by 2091unexpected conditions, such as not being able to load the event model
1586C<PERL_ANYEVENT_MODEL>. 2092specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2093exception - this is the minimum recommended level.
1587 2094
1588When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2095When set to C<7> or higher (info), cause AnyEvent to report which event model it
1589model it chooses. 2096chooses.
1590 2097
1591When set to C<8> or higher, then AnyEvent will report extra information on 2098When set to C<8> or higher (debug), then AnyEvent will report extra information on
1592which optional modules it loads and how it implements certain features. 2099which optional modules it loads and how it implements certain features.
2100
2101=item C<PERL_ANYEVENT_LOG>
2102
2103Accepts rather complex logging specifications. For example, you could log
2104all C<debug> messages of some module to stderr, warnings and above to
2105stderr, and errors and above to syslog, with:
2106
2107 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2108
2109For the rather extensive details, see L<AnyEvent::Log>.
2110
2111This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2112so will take effect even before AnyEvent has initialised itself.
2113
2114Note that specifying this environment variable causes the L<AnyEvent::Log>
2115module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2116using the latter saves a few hundred kB of memory until the first message
2117is being logged.
1593 2118
1594=item C<PERL_ANYEVENT_STRICT> 2119=item C<PERL_ANYEVENT_STRICT>
1595 2120
1596AnyEvent does not do much argument checking by default, as thorough 2121AnyEvent does not do much argument checking by default, as thorough
1597argument checking is very costly. Setting this variable to a true value 2122argument checking is very costly. Setting this variable to a true value
1599check the arguments passed to most method calls. If it finds any problems, 2124check the arguments passed to most method calls. If it finds any problems,
1600it will croak. 2125it will croak.
1601 2126
1602In other words, enables "strict" mode. 2127In other words, enables "strict" mode.
1603 2128
1604Unlike C<use strict> (or it's modern cousin, C<< use L<common::sense> 2129Unlike C<use strict> (or its modern cousin, C<< use L<common::sense>
1605>>, it is definitely recommended to keep it off in production. Keeping 2130>>, it is definitely recommended to keep it off in production. Keeping
1606C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2131C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1607can be very useful, however. 2132can be very useful, however.
1608 2133
2134=item C<PERL_ANYEVENT_DEBUG_SHELL>
2135
2136If this env variable is nonempty, then its contents will be interpreted by
2137C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
2138replacing every occurance of C<$$> by the process pid). The shell object
2139is saved in C<$AnyEvent::Debug::SHELL>.
2140
2141This happens when the first watcher is created.
2142
2143For example, to bind a debug shell on a unix domain socket in
2144F<< /tmp/debug<pid>.sock >>, you could use this:
2145
2146 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2147 # connect with e.g.: socat readline /tmp/debug123.sock
2148
2149Or to bind to tcp port 4545 on localhost:
2150
2151 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
2152 # connect with e.g.: telnet localhost 4545
2153
2154Note that creating sockets in F</tmp> or on localhost is very unsafe on
2155multiuser systems.
2156
2157=item C<PERL_ANYEVENT_DEBUG_WRAP>
2158
2159Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2160debugging purposes. See C<AnyEvent::Debug::wrap> for details.
2161
1609=item C<PERL_ANYEVENT_MODEL> 2162=item C<PERL_ANYEVENT_MODEL>
1610 2163
1611This can be used to specify the event model to be used by AnyEvent, before 2164This can be used to specify the event model to be used by AnyEvent, before
1612auto detection and -probing kicks in. It must be a string consisting 2165auto detection and -probing kicks in.
1613entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 2166
2167It normally is a string consisting entirely of ASCII letters (e.g. C<EV>
2168or C<IOAsync>). The string C<AnyEvent::Impl::> gets prepended and the
1614and the resulting module name is loaded and if the load was successful, 2169resulting module name is loaded and - if the load was successful - used as
1615used as event model. If it fails to load AnyEvent will proceed with 2170event model backend. If it fails to load then AnyEvent will proceed with
1616auto detection and -probing. 2171auto detection and -probing.
1617 2172
1618This functionality might change in future versions. 2173If the string ends with C<::> instead (e.g. C<AnyEvent::Impl::EV::>) then
2174nothing gets prepended and the module name is used as-is (hint: C<::> at
2175the end of a string designates a module name and quotes it appropriately).
1619 2176
1620For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 2177For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
1621could start your program like this: 2178could start your program like this:
1622 2179
1623 PERL_ANYEVENT_MODEL=Perl perl ... 2180 PERL_ANYEVENT_MODEL=Perl perl ...
1624 2181
1625=item C<PERL_ANYEVENT_PROTOCOLS> 2182=item C<PERL_ANYEVENT_PROTOCOLS>
1641but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2198but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1642- only support IPv4, never try to resolve or contact IPv6 2199- only support IPv4, never try to resolve or contact IPv6
1643addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2200addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1644IPv6, but prefer IPv6 over IPv4. 2201IPv6, but prefer IPv6 over IPv4.
1645 2202
2203=item C<PERL_ANYEVENT_HOSTS>
2204
2205This variable, if specified, overrides the F</etc/hosts> file used by
2206L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2207from that file instead.
2208
1646=item C<PERL_ANYEVENT_EDNS0> 2209=item C<PERL_ANYEVENT_EDNS0>
1647 2210
1648Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2211Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
1649for DNS. This extension is generally useful to reduce DNS traffic, but 2212DNS. This extension is generally useful to reduce DNS traffic, especially
1650some (broken) firewalls drop such DNS packets, which is why it is off by 2213when DNSSEC is involved, but some (broken) firewalls drop such DNS
1651default. 2214packets, which is why it is off by default.
1652 2215
1653Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2216Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1654EDNS0 in its DNS requests. 2217EDNS0 in its DNS requests.
1655 2218
1656=item C<PERL_ANYEVENT_MAX_FORKS> 2219=item C<PERL_ANYEVENT_MAX_FORKS>
1662 2225
1663The default value for the C<max_outstanding> parameter for the default DNS 2226The default value for the C<max_outstanding> parameter for the default DNS
1664resolver - this is the maximum number of parallel DNS requests that are 2227resolver - this is the maximum number of parallel DNS requests that are
1665sent to the DNS server. 2228sent to the DNS server.
1666 2229
2230=item C<PERL_ANYEVENT_MAX_SIGNAL_LATENCY>
2231
2232Perl has inherently racy signal handling (you can basically choose between
2233losing signals and memory corruption) - pure perl event loops (including
2234C<AnyEvent::Loop>, when C<Async::Interrupt> isn't available) therefore
2235have to poll regularly to avoid losing signals.
2236
2237Some event loops are racy, but don't poll regularly, and some event loops
2238are written in C but are still racy. For those event loops, AnyEvent
2239installs a timer that regularly wakes up the event loop.
2240
2241By default, the interval for this timer is C<10> seconds, but you can
2242override this delay with this environment variable (or by setting
2243the C<$AnyEvent::MAX_SIGNAL_LATENCY> variable before creating signal
2244watchers).
2245
2246Lower values increase CPU (and energy) usage, higher values can introduce
2247long delays when reaping children or waiting for signals.
2248
2249The L<AnyEvent::Async> module, if available, will be used to avoid this
2250polling (with most event loops).
2251
1667=item C<PERL_ANYEVENT_RESOLV_CONF> 2252=item C<PERL_ANYEVENT_RESOLV_CONF>
1668 2253
1669The file to use instead of F</etc/resolv.conf> (or OS-specific 2254The absolute path to a F<resolv.conf>-style file to use instead of
1670configuration) in the default resolver. When set to the empty string, no 2255F</etc/resolv.conf> (or the OS-specific configuration) in the default
1671default config will be used. 2256resolver, or the empty string to select the default configuration.
1672 2257
1673=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2258=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1674 2259
1675When neither C<ca_file> nor C<ca_path> was specified during 2260When neither C<ca_file> nor C<ca_path> was specified during
1676L<AnyEvent::TLS> context creation, and either of these environment 2261L<AnyEvent::TLS> context creation, and either of these environment
1677variables exist, they will be used to specify CA certificate locations 2262variables are nonempty, they will be used to specify CA certificate
1678instead of a system-dependent default. 2263locations instead of a system-dependent default.
1679 2264
1680=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2265=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1681 2266
1682When these are set to C<1>, then the respective modules are not 2267When these are set to C<1>, then the respective modules are not
1683loaded. Mostly good for testing AnyEvent itself. 2268loaded. Mostly good for testing AnyEvent itself.
1746 warn "read: $input\n"; # output what has been read 2331 warn "read: $input\n"; # output what has been read
1747 $cv->send if $input =~ /^q/i; # quit program if /^q/i 2332 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1748 }, 2333 },
1749 ); 2334 );
1750 2335
1751 my $time_watcher; # can only be used once
1752
1753 sub new_timer {
1754 $timer = AnyEvent->timer (after => 1, cb => sub { 2336 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
1755 warn "timeout\n"; # print 'timeout' about every second 2337 warn "timeout\n"; # print 'timeout' at most every second
1756 &new_timer; # and restart the time
1757 }); 2338 });
1758 }
1759
1760 new_timer; # create first timer
1761 2339
1762 $cv->recv; # wait until user enters /^q/i 2340 $cv->recv; # wait until user enters /^q/i
1763 2341
1764=head1 REAL-WORLD EXAMPLE 2342=head1 REAL-WORLD EXAMPLE
1765 2343
1838 2416
1839The actual code goes further and collects all errors (C<die>s, exceptions) 2417The actual code goes further and collects all errors (C<die>s, exceptions)
1840that occurred during request processing. The C<result> method detects 2418that occurred during request processing. The C<result> method detects
1841whether an exception as thrown (it is stored inside the $txn object) 2419whether an exception as thrown (it is stored inside the $txn object)
1842and just throws the exception, which means connection errors and other 2420and just throws the exception, which means connection errors and other
1843problems get reported tot he code that tries to use the result, not in a 2421problems get reported to the code that tries to use the result, not in a
1844random callback. 2422random callback.
1845 2423
1846All of this enables the following usage styles: 2424All of this enables the following usage styles:
1847 2425
18481. Blocking: 24261. Blocking:
1896through AnyEvent. The benchmark creates a lot of timers (with a zero 2474through AnyEvent. The benchmark creates a lot of timers (with a zero
1897timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 2475timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1898which it is), lets them fire exactly once and destroys them again. 2476which it is), lets them fire exactly once and destroys them again.
1899 2477
1900Source code for this benchmark is found as F<eg/bench> in the AnyEvent 2478Source code for this benchmark is found as F<eg/bench> in the AnyEvent
1901distribution. 2479distribution. It uses the L<AE> interface, which makes a real difference
2480for the EV and Perl backends only.
1902 2481
1903=head3 Explanation of the columns 2482=head3 Explanation of the columns
1904 2483
1905I<watcher> is the number of event watchers created/destroyed. Since 2484I<watcher> is the number of event watchers created/destroyed. Since
1906different event models feature vastly different performances, each event 2485different event models feature vastly different performances, each event
1927watcher. 2506watcher.
1928 2507
1929=head3 Results 2508=head3 Results
1930 2509
1931 name watchers bytes create invoke destroy comment 2510 name watchers bytes create invoke destroy comment
1932 EV/EV 400000 224 0.47 0.35 0.27 EV native interface 2511 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
1933 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 2512 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
1934 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 2513 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
1935 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 2514 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
1936 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 2515 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
1937 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 2516 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
1938 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll 2517 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
1939 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll 2518 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
1940 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 2519 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
1941 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 2520 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
1942 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 2521 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
1943 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 2522 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
1944 2523
1945=head3 Discussion 2524=head3 Discussion
1946 2525
1947The benchmark does I<not> measure scalability of the event loop very 2526The benchmark does I<not> measure scalability of the event loop very
1948well. For example, a select-based event loop (such as the pure perl one) 2527well. For example, a select-based event loop (such as the pure perl one)
1960benchmark machine, handling an event takes roughly 1600 CPU cycles with 2539benchmark machine, handling an event takes roughly 1600 CPU cycles with
1961EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU 2540EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU
1962cycles with POE. 2541cycles with POE.
1963 2542
1964C<EV> is the sole leader regarding speed and memory use, which are both 2543C<EV> is the sole leader regarding speed and memory use, which are both
1965maximal/minimal, respectively. Even when going through AnyEvent, it uses 2544maximal/minimal, respectively. When using the L<AE> API there is zero
2545overhead (when going through the AnyEvent API create is about 5-6 times
2546slower, with other times being equal, so still uses far less memory than
1966far less memory than any other event loop and is still faster than Event 2547any other event loop and is still faster than Event natively).
1967natively.
1968 2548
1969The pure perl implementation is hit in a few sweet spots (both the 2549The pure perl implementation is hit in a few sweet spots (both the
1970constant timeout and the use of a single fd hit optimisations in the perl 2550constant timeout and the use of a single fd hit optimisations in the perl
1971interpreter and the backend itself). Nevertheless this shows that it 2551interpreter and the backend itself). Nevertheless this shows that it
1972adds very little overhead in itself. Like any select-based backend its 2552adds very little overhead in itself. Like any select-based backend its
2020(even when used without AnyEvent), but most event loops have acceptable 2600(even when used without AnyEvent), but most event loops have acceptable
2021performance with or without AnyEvent. 2601performance with or without AnyEvent.
2022 2602
2023=item * The overhead AnyEvent adds is usually much smaller than the overhead of 2603=item * The overhead AnyEvent adds is usually much smaller than the overhead of
2024the actual event loop, only with extremely fast event loops such as EV 2604the actual event loop, only with extremely fast event loops such as EV
2025adds AnyEvent significant overhead. 2605does AnyEvent add significant overhead.
2026 2606
2027=item * You should avoid POE like the plague if you want performance or 2607=item * You should avoid POE like the plague if you want performance or
2028reasonable memory usage. 2608reasonable memory usage.
2029 2609
2030=back 2610=back
2046In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100 2626In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
2047(1%) are active. This mirrors the activity of large servers with many 2627(1%) are active. This mirrors the activity of large servers with many
2048connections, most of which are idle at any one point in time. 2628connections, most of which are idle at any one point in time.
2049 2629
2050Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 2630Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
2051distribution. 2631distribution. It uses the L<AE> interface, which makes a real difference
2632for the EV and Perl backends only.
2052 2633
2053=head3 Explanation of the columns 2634=head3 Explanation of the columns
2054 2635
2055I<sockets> is the number of sockets, and twice the number of "servers" (as 2636I<sockets> is the number of sockets, and twice the number of "servers" (as
2056each server has a read and write socket end). 2637each server has a read and write socket end).
2064a new one that moves the timeout into the future. 2645a new one that moves the timeout into the future.
2065 2646
2066=head3 Results 2647=head3 Results
2067 2648
2068 name sockets create request 2649 name sockets create request
2069 EV 20000 69.01 11.16 2650 EV 20000 62.66 7.99
2070 Perl 20000 73.32 35.87 2651 Perl 20000 68.32 32.64
2071 IOAsync 20000 157.00 98.14 epoll 2652 IOAsync 20000 174.06 101.15 epoll
2072 IOAsync 20000 159.31 616.06 poll 2653 IOAsync 20000 174.67 610.84 poll
2073 Event 20000 212.62 257.32 2654 Event 20000 202.69 242.91
2074 Glib 20000 651.16 1896.30 2655 Glib 20000 557.01 1689.52
2075 POE 20000 349.67 12317.24 uses POE::Loop::Event 2656 POE 20000 341.54 12086.32 uses POE::Loop::Event
2076 2657
2077=head3 Discussion 2658=head3 Discussion
2078 2659
2079This benchmark I<does> measure scalability and overall performance of the 2660This benchmark I<does> measure scalability and overall performance of the
2080particular event loop. 2661particular event loop.
2206As you can see, the AnyEvent + EV combination even beats the 2787As you can see, the AnyEvent + EV combination even beats the
2207hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl 2788hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
2208backend easily beats IO::Lambda and POE. 2789backend easily beats IO::Lambda and POE.
2209 2790
2210And even the 100% non-blocking version written using the high-level (and 2791And even the 100% non-blocking version written using the high-level (and
2211slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a 2792slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda
2212large margin, even though it does all of DNS, tcp-connect and socket I/O 2793higher level ("unoptimised") abstractions by a large margin, even though
2213in a non-blocking way. 2794it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
2214 2795
2215The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and 2796The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
2216F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are 2797F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2217part of the IO::lambda distribution and were used without any changes. 2798part of the IO::Lambda distribution and were used without any changes.
2218 2799
2219 2800
2220=head1 SIGNALS 2801=head1 SIGNALS
2221 2802
2222AnyEvent currently installs handlers for these signals: 2803AnyEvent currently installs handlers for these signals:
2259 unless defined $SIG{PIPE}; 2840 unless defined $SIG{PIPE};
2260 2841
2261=head1 RECOMMENDED/OPTIONAL MODULES 2842=head1 RECOMMENDED/OPTIONAL MODULES
2262 2843
2263One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and 2844One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2264it's built-in modules) are required to use it. 2845its built-in modules) are required to use it.
2265 2846
2266That does not mean that AnyEvent won't take advantage of some additional 2847That does not mean that AnyEvent won't take advantage of some additional
2267modules if they are installed. 2848modules if they are installed.
2268 2849
2269This section epxlains which additional modules will be used, and how they 2850This section explains which additional modules will be used, and how they
2270affect AnyEvent's operetion. 2851affect AnyEvent's operation.
2271 2852
2272=over 4 2853=over 4
2273 2854
2274=item L<Async::Interrupt> 2855=item L<Async::Interrupt>
2275 2856
2280catch the signals) with some delay (default is 10 seconds, look for 2861catch the signals) with some delay (default is 10 seconds, look for
2281C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2862C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2282 2863
2283If this module is available, then it will be used to implement signal 2864If this module is available, then it will be used to implement signal
2284catching, which means that signals will not be delayed, and the event loop 2865catching, which means that signals will not be delayed, and the event loop
2285will not be interrupted regularly, which is more efficient (And good for 2866will not be interrupted regularly, which is more efficient (and good for
2286battery life on laptops). 2867battery life on laptops).
2287 2868
2288This affects not just the pure-perl event loop, but also other event loops 2869This affects not just the pure-perl event loop, but also other event loops
2289that have no signal handling on their own (e.g. Glib, Tk, Qt). 2870that have no signal handling on their own (e.g. Glib, Tk, Qt).
2290 2871
2302automatic timer adjustments even when no monotonic clock is available, 2883automatic timer adjustments even when no monotonic clock is available,
2303can take avdantage of advanced kernel interfaces such as C<epoll> and 2884can take avdantage of advanced kernel interfaces such as C<epoll> and
2304C<kqueue>, and is the fastest backend I<by far>. You can even embed 2885C<kqueue>, and is the fastest backend I<by far>. You can even embed
2305L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>). 2886L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2306 2887
2888If you only use backends that rely on another event loop (e.g. C<Tk>),
2889then this module will do nothing for you.
2890
2307=item L<Guard> 2891=item L<Guard>
2308 2892
2309The guard module, when used, will be used to implement 2893The guard module, when used, will be used to implement
2310C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a 2894C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2311lot less memory), but otherwise doesn't affect guard operation much. It is 2895lot less memory), but otherwise doesn't affect guard operation much. It is
2312purely used for performance. 2896purely used for performance.
2313 2897
2314=item L<JSON> and L<JSON::XS> 2898=item L<JSON> and L<JSON::XS>
2315 2899
2316This module is required when you want to read or write JSON data via 2900One of these modules is required when you want to read or write JSON data
2317L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2901via L<AnyEvent::Handle>. L<JSON> is also written in pure-perl, but can take
2318advantage of the ulta-high-speed L<JSON::XS> module when it is installed. 2902advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2319
2320In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2321installed.
2322 2903
2323=item L<Net::SSLeay> 2904=item L<Net::SSLeay>
2324 2905
2325Implementing TLS/SSL in Perl is certainly interesting, but not very 2906Implementing TLS/SSL in Perl is certainly interesting, but not very
2326worthwhile: If this module is installed, then L<AnyEvent::Handle> (with 2907worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2327the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL. 2908the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2328 2909
2329=item L<Time::HiRes> 2910=item L<Time::HiRes>
2330 2911
2331This module is part of perl since release 5.008. It will be used when the 2912This module is part of perl since release 5.008. It will be used when the
2332chosen event library does not come with a timing source on it's own. The 2913chosen event library does not come with a timing source of its own. The
2333pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to 2914pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to
2334try to use a monotonic clock for timing stability. 2915try to use a monotonic clock for timing stability.
2335 2916
2336=back 2917=back
2337 2918
2338 2919
2339=head1 FORK 2920=head1 FORK
2340 2921
2341Most event libraries are not fork-safe. The ones who are usually are 2922Most event libraries are not fork-safe. The ones who are usually are
2342because they rely on inefficient but fork-safe C<select> or C<poll> 2923because they rely on inefficient but fork-safe C<select> or C<poll> calls
2343calls. Only L<EV> is fully fork-aware. 2924- higher performance APIs such as BSD's kqueue or the dreaded Linux epoll
2925are usually badly thought-out hacks that are incompatible with fork in
2926one way or another. Only L<EV> is fully fork-aware and ensures that you
2927continue event-processing in both parent and child (or both, if you know
2928what you are doing).
2929
2930This means that, in general, you cannot fork and do event processing in
2931the child if the event library was initialised before the fork (which
2932usually happens when the first AnyEvent watcher is created, or the library
2933is loaded).
2344 2934
2345If you have to fork, you must either do so I<before> creating your first 2935If you have to fork, you must either do so I<before> creating your first
2346watcher OR you must not use AnyEvent at all in the child OR you must do 2936watcher OR you must not use AnyEvent at all in the child OR you must do
2347something completely out of the scope of AnyEvent. 2937something completely out of the scope of AnyEvent.
2938
2939The problem of doing event processing in the parent I<and> the child
2940is much more complicated: even for backends that I<are> fork-aware or
2941fork-safe, their behaviour is not usually what you want: fork clones all
2942watchers, that means all timers, I/O watchers etc. are active in both
2943parent and child, which is almost never what you want. USing C<exec>
2944to start worker children from some kind of manage rprocess is usually
2945preferred, because it is much easier and cleaner, at the expense of having
2946to have another binary.
2348 2947
2349 2948
2350=head1 SECURITY CONSIDERATIONS 2949=head1 SECURITY CONSIDERATIONS
2351 2950
2352AnyEvent can be forced to load any event model via 2951AnyEvent can be forced to load any event model via
2382pronounced). 2981pronounced).
2383 2982
2384 2983
2385=head1 SEE ALSO 2984=head1 SEE ALSO
2386 2985
2387Utility functions: L<AnyEvent::Util>. 2986Tutorial/Introduction: L<AnyEvent::Intro>.
2388 2987
2389Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 2988FAQ: L<AnyEvent::FAQ>.
2390L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2989
2990Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2991(simply logging).
2992
2993Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2994L<AnyEvent::Debug> (interactive shell, watcher tracing).
2995
2996Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2997L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2998L<Qt>, L<POE>, L<FLTK>.
2391 2999
2392Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 3000Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2393L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 3001L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2394L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 3002L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2395L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>. 3003L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
3004L<AnyEvent::Impl::FLTK>.
2396 3005
2397Non-blocking file handles, sockets, TCP clients and 3006Non-blocking handles, pipes, stream sockets, TCP clients and
2398servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 3007servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2399 3008
2400Asynchronous DNS: L<AnyEvent::DNS>. 3009Asynchronous DNS: L<AnyEvent::DNS>.
2401 3010
2402Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, 3011Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
2403L<Coro::Event>,
2404 3012
2405Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>, 3013Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::IRC>,
2406L<AnyEvent::HTTP>. 3014L<AnyEvent::HTTP>.
2407 3015
2408 3016
2409=head1 AUTHOR 3017=head1 AUTHOR
2410 3018

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines