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.269 by root, Fri Jul 31 20:16:29 2009 UTC vs.
Revision 1.384 by root, Mon Sep 5 07:21:54 2011 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines