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.266 by root, Thu Jul 30 03:41:56 2009 UTC vs.
Revision 1.381 by root, Thu Sep 1 22:09:25 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 do 432callbacks to signals in a generic way, which is a pity, as you cannot
405race-free signal handling in perl. AnyEvent will try to do it's best, but 433do race-free signal handling in perl, requiring C libraries for
434this. AnyEvent will try to do its best, which means in some cases,
406in some cases, signals will be delayed. The maximum time a signal might 435signals will be delayed. The maximum time a signal might be delayed is
407be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 436specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This
408seconds). This variable can be changed only before the first signal 437variable can be changed only before the first signal watcher is created,
409watcher is created, and should be left alone otherwise. Higher values 438and should be left alone otherwise. This variable determines how often
439AnyEvent polls for signals (in case a wake-up was missed). Higher values
410will cause fewer spurious wake-ups, which is better for power and CPU 440will cause fewer spurious wake-ups, which is better for power and CPU
441saving.
442
411saving. All these problems can be avoided by installing the optional 443All these problems can be avoided by installing the optional
412L<Async::Interrupt> module. This will not work with inherently broken 444L<Async::Interrupt> module, which works with most event loops. It will not
413event loops such as L<Event> or L<Event::Lib> (and not with L<POE> 445work with inherently broken event loops such as L<Event> or L<Event::Lib>
414currently, as POE does it's own workaround with one-second latency). With 446(and not with L<POE> currently, as POE does its own workaround with
415those, you just have to suffer the delays. 447one-second latency). For those, you just have to suffer the delays.
416 448
417=head2 CHILD PROCESS WATCHERS 449=head2 CHILD PROCESS WATCHERS
418 450
419 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 451 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
420 452
421You 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.
422 454
423The 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,
424using 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
425croak). The watcher will be triggered only when the child process has 457croak). The watcher will be triggered only when the child process has
426finished and an exit status is available, not on any trace events 458finished and an exit status is available, not on any trace events
427(stopped/continued). 459(stopped/continued).
428 460
450thing 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
451watcher before you C<fork> the child (alternatively, you can call 483watcher before you C<fork> the child (alternatively, you can call
452C<AnyEvent::detect>). 484C<AnyEvent::detect>).
453 485
454As 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
455emulated 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
456mentioned in the description of signal watchers apply. 488problems mentioned in the description of signal watchers apply.
457 489
458Example: fork a process and wait for it 490Example: fork a process and wait for it
459 491
460 my $done = AnyEvent->condvar; 492 my $done = AnyEvent->condvar;
461 493
475 507
476=head2 IDLE WATCHERS 508=head2 IDLE WATCHERS
477 509
478 $w = AnyEvent->idle (cb => <callback>); 510 $w = AnyEvent->idle (cb => <callback>);
479 511
480Sometimes there is a need to do something, but it is not so important 512This will repeatedly invoke the callback after the process becomes idle,
481to 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.
482"nothing better to do" is usually defined to be "no other events need
483attention by the event loop".
484 514
485Idle watchers ideally get invoked when the event loop has nothing 515Idle watchers are useful when there is a need to do something, but it
486better 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
487events. 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.
488 523
489Most event loops unfortunately do not really support idle watchers (only 524Unfortunately, most event loops do not really support idle watchers (only
490EV, 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
491will simply call the callback "from time to time". 526will simply call the callback "from time to time".
492 527
493Example: read lines from STDIN, but only process them when the 528Example: read lines from STDIN, but only process them when the
494program is otherwise idle: 529program is otherwise idle:
522will actively watch for new events and call your callbacks. 557will actively watch for new events and call your callbacks.
523 558
524AnyEvent is slightly different: it expects somebody else to run the event 559AnyEvent is slightly different: it expects somebody else to run the event
525loop 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).
526 561
527The instrument to do that is called a "condition variable", so called 562The tool to do that is called a "condition variable", so called because
528because they represent a condition that must become true. 563they represent a condition that must become true.
529 564
530Now 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.
531 566
532Condition variables can be created by calling the C<< AnyEvent->condvar 567Condition variables can be created by calling the C<< AnyEvent->condvar
533>> method, usually without arguments. The only argument pair allowed is 568>> method, usually without arguments. The only argument pair allowed is
538After creation, the condition variable is "false" until it becomes "true" 573After creation, the condition variable is "false" until it becomes "true"
539by 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
540were 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<<
541->send >> method). 576->send >> method).
542 577
543Condition variables are similar to callbacks, except that you can 578Since condition variables are the most complex part of the AnyEvent API, here are
544optionally 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:
545in time where multiple outstanding events have been processed. And yet 580
546another way to call them is transactions - each condition variable can be 581=over 4
547used to represent a transaction, which finishes at some point and delivers 582
548a 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
549compute/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
550 601
551Condition variables are very useful to signal that something has finished, 602Condition variables are very useful to signal that something has finished,
552for example, if you write a module that does asynchronous http requests, 603for example, if you write a module that does asynchronous http requests,
553then a condition variable would be the ideal candidate to signal the 604then a condition variable would be the ideal candidate to signal the
554availability of results. The user can either act when the callback is 605availability of results. The user can either act when the callback is
567 618
568Condition variables are represented by hash refs in perl, and the keys 619Condition variables are represented by hash refs in perl, and the keys
569used 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
570easy (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
571AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call 622AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call
572it's C<new> method in your own C<new> method. 623its C<new> method in your own C<new> method.
573 624
574There are two "sides" to a condition variable - the "producer side" which 625There are two "sides" to a condition variable - the "producer side" which
575eventually calls C<< -> send >>, and the "consumer side", which waits 626eventually calls C<< -> send >>, and the "consumer side", which waits
576for the send to occur. 627for the send to occur.
577 628
578Example: wait for a timer. 629Example: wait for a timer.
579 630
580 # wait till the result is ready 631 # condition: "wait till the timer is fired"
581 my $result_ready = AnyEvent->condvar; 632 my $timer_fired = AnyEvent->condvar;
582 633
583 # do something such as adding a timer 634 # create the timer - we could wait for, say
584 # or socket watcher the calls $result_ready->send 635 # a handle becomign ready, or even an
585 # when the "result" is ready. 636 # AnyEvent::HTTP request to finish, but
586 # in this case, we simply use a timer: 637 # in this case, we simply use a timer:
587 my $w = AnyEvent->timer ( 638 my $w = AnyEvent->timer (
588 after => 1, 639 after => 1,
589 cb => sub { $result_ready->send }, 640 cb => sub { $timer_fired->send },
590 ); 641 );
591 642
592 # this "blocks" (while handling events) till the callback 643 # this "blocks" (while handling events) till the callback
593 # calls -<send 644 # calls ->send
594 $result_ready->recv; 645 $timer_fired->recv;
595 646
596Example: 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
597variables are also callable directly. 648variables are also callable directly.
598 649
599 my $done = AnyEvent->condvar; 650 my $done = AnyEvent->condvar;
642they 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
643C<send>. 694C<send>.
644 695
645=item $cv->croak ($error) 696=item $cv->croak ($error)
646 697
647Similar to send, but causes all call's to C<< ->recv >> to invoke 698Similar to send, but causes all calls to C<< ->recv >> to invoke
648C<Carp::croak> with the given error message/object/scalar. 699C<Carp::croak> with the given error message/object/scalar.
649 700
650This can be used to signal any errors to the condition variable 701This can be used to signal any errors to the condition variable
651user/consumer. Doing it this way instead of calling C<croak> directly 702user/consumer. Doing it this way instead of calling C<croak> directly
652delays the error detetcion, but has the overwhelmign advantage that it 703delays the error detection, but has the overwhelming advantage that it
653diagnoses 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
654deep in some event clalback without connection to the actual code causing 705deep in some event callback with no connection to the actual code causing
655the problem. 706the problem.
656 707
657=item $cv->begin ([group callback]) 708=item $cv->begin ([group callback])
658 709
659=item $cv->end 710=item $cv->end
662one. 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
663to use a condition variable for the whole process. 714to use a condition variable for the whole process.
664 715
665Every 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
666C<< ->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
667>>, 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
668is 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
669callback 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.
670 722
671You 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
672sends), 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
673condition (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).
674 726
696one 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
697sending. 749sending.
698 750
699The ping example mentioned above is slightly more complicated, as the 751The ping example mentioned above is slightly more complicated, as the
700there 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
701begung can potentially be zero: 753begun can potentially be zero:
702 754
703 my $cv = AnyEvent->condvar; 755 my $cv = AnyEvent->condvar;
704 756
705 my %result; 757 my %result;
706 $cv->begin (sub { $cv->send (\%result) }); 758 $cv->begin (sub { shift->send (\%result) });
707 759
708 for my $host (@list_of_hosts) { 760 for my $host (@list_of_hosts) {
709 $cv->begin; 761 $cv->begin;
710 ping_host_then_call_callback $host, sub { 762 ping_host_then_call_callback $host, sub {
711 $result{$host} = ...; 763 $result{$host} = ...;
727to 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
728C<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
729doesn't execute once). 781doesn't execute once).
730 782
731This is the general pattern when you "fan out" into multiple (but 783This is the general pattern when you "fan out" into multiple (but
732potentially 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
733the 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
734subrequest you start, call C<begin> and for each subrequest you finish, 786subrequest you start, call C<begin> and for each subrequest you finish,
735call C<end>. 787call C<end>.
736 788
737=back 789=back
744=over 4 796=over 4
745 797
746=item $cv->recv 798=item $cv->recv
747 799
748Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak 800Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
749>> methods have been called on c<$cv>, while servicing other watchers 801>> methods have been called on C<$cv>, while servicing other watchers
750normally. 802normally.
751 803
752You 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
753will return immediately. 805will return immediately.
754 806
771caller 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
772condition variables with some kind of request results and supporting 824condition variables with some kind of request results and supporting
773callbacks so the caller knows that getting the result will not block, 825callbacks so the caller knows that getting the result will not block,
774while still supporting blocking waits if the caller so desires). 826while still supporting blocking waits if the caller so desires).
775 827
776You 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
777only calling C<< ->recv >> from within that callback (or at a later 829only calling C<< ->recv >> from within that callback (or at a later
778time). 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
779waits otherwise. 831waits otherwise.
780 832
781=item $bool = $cv->ready 833=item $bool = $cv->ready
787 839
788This is a mutator function that returns the callback set and optionally 840This is a mutator function that returns the callback set and optionally
789replaces it before doing so. 841replaces it before doing so.
790 842
791The callback will be called when the condition becomes "true", i.e. when 843The callback will be called when the condition becomes "true", i.e. when
792C<send> or C<croak> are called, with the only argument being the condition 844C<send> or C<croak> are called, with the only argument being the
793variable itself. Calling C<recv> inside the callback or at any later time 845condition variable itself. If the condition is already true, the
794is guaranteed not to block. 846callback is called immediately when it is set. Calling C<recv> inside
847the callback or at any later time is guaranteed not to block.
795 848
796=back 849=back
797 850
798=head1 SUPPORTED EVENT LOOPS/BACKENDS 851=head1 SUPPORTED EVENT LOOPS/BACKENDS
799 852
802=over 4 855=over 4
803 856
804=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.
805 858
806EV 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
807use. 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
808that, will fall back to its own pure-perl implementation, which is 861pure-perl implementation, which is available everywhere as it comes with
809available everywhere as it comes with AnyEvent itself. 862AnyEvent itself.
810 863
811 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 864 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
812 AnyEvent::Impl::Event based on Event, very stable, few glitches.
813 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 865 AnyEvent::Impl::Perl pure-perl AnyEvent::Loop, fast and portable.
814 866
815=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.
816 868
817These 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
818is 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
819them. This means that AnyEvent will automatically pick the right backend 871them. This means that AnyEvent will automatically pick the right backend
820when the main program loads an event module before anything starts to 872when the main program loads an event module before anything starts to
821create watchers. Nothing special needs to be done by the main program. 873create watchers. Nothing special needs to be done by the main program.
822 874
875 AnyEvent::Impl::Event based on Event, very stable, few glitches.
823 AnyEvent::Impl::Glib based on Glib, slow but very stable. 876 AnyEvent::Impl::Glib based on Glib, slow but very stable.
824 AnyEvent::Impl::Tk based on Tk, very broken. 877 AnyEvent::Impl::Tk based on Tk, very broken.
825 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
826 AnyEvent::Impl::POE based on POE, very slow, some limitations. 879 AnyEvent::Impl::POE based on POE, very slow, some limitations.
827 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).
828 884
829=item Backends with special needs. 885=item Backends with special needs.
830 886
831Qt requires the Qt::Application to be instantiated first, but will 887Qt requires the Qt::Application to be instantiated first, but will
832otherwise be picked up automatically. As long as the main program 888otherwise be picked up automatically. As long as the main program
833instantiates the application before any AnyEvent watchers are created, 889instantiates the application before any AnyEvent watchers are created,
834everything should just work. 890everything should just work.
835 891
836 AnyEvent::Impl::Qt based on Qt. 892 AnyEvent::Impl::Qt based on Qt.
837 893
838Support for IO::Async can only be partial, as it is too broken and
839architecturally limited to even support the AnyEvent API. It also
840is the only event loop that needs the loop to be set explicitly, so
841it can only be used by a main program knowing about AnyEvent. See
842L<AnyEvent::Impl::Async> for the gory details.
843
844 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
845
846=item Event loops that are indirectly supported via other backends. 894=item Event loops that are indirectly supported via other backends.
847 895
848Some event loops can be supported via other modules: 896Some event loops can be supported via other modules:
849 897
850There is no direct support for WxWidgets (L<Wx>) or L<Prima>. 898There is no direct support for WxWidgets (L<Wx>) or L<Prima>.
875Contains C<undef> until the first watcher is being created, before the 923Contains C<undef> until the first watcher is being created, before the
876backend has been autodetected. 924backend has been autodetected.
877 925
878Afterwards 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
879name 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
880of 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
881case 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
882will be C<urxvt::anyevent>). 930will be C<urxvt::anyevent>).
883 931
884=item AnyEvent::detect 932=item AnyEvent::detect
885 933
886Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 934Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
887if necessary. You should only call this function right before you would 935if necessary. You should only call this function right before you would
888have 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
889runtime, 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).
890 942
891If you need to do some initialisation before AnyEvent watchers are 943If you need to do some initialisation before AnyEvent watchers are
892created, use C<post_detect>. 944created, use C<post_detect>.
893 945
894=item $guard = AnyEvent::post_detect { BLOCK } 946=item $guard = AnyEvent::post_detect { BLOCK }
895 947
896Arranges 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
897autodetected (or immediately if this has already happened). 949autodetected (or immediately if that has already happened).
898 950
899The 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
900(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
901created, 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
902other initialisations - see the sources of L<AnyEvent::Strict> or 954other initialisations - see the sources of L<AnyEvent::Strict> or
911that automatically removes the callback again when it is destroyed (or 963that automatically removes the callback again when it is destroyed (or
912C<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
913a case where this is useful. 965a case where this is useful.
914 966
915Example: 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
916C<$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.
917 969
918 our WATCHER; 970 our WATCHER;
919 971
920 my $guard = AnyEvent::post_detect { 972 my $guard = AnyEvent::post_detect {
921 $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);
929 $WATCHER ||= $guard; 981 $WATCHER ||= $guard;
930 982
931=item @AnyEvent::post_detect 983=item @AnyEvent::post_detect
932 984
933If 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
934before or after loading AnyEvent), then they will called directly after 986before or after loading AnyEvent), then they will be called directly
935the event loop has been chosen. 987after the event loop has been chosen.
936 988
937You should check C<$AnyEvent::MODEL> before adding to this array, though: 989You should check C<$AnyEvent::MODEL> before adding to this array, though:
938if 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
939array will be ignored. 991array will be ignored.
940 992
941Best use C<AnyEvent::post_detect { BLOCK }> when your application allows 993Best use C<AnyEvent::post_detect { BLOCK }> when your application allows
942it,as it takes care of these details. 994it, as it takes care of these details.
943 995
944This variable is mainly useful for modules that can do something useful 996This variable is mainly useful for modules that can do something useful
945when 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
946not 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
947into AnyEvent passively, without loading it. 999into AnyEvent passively, without loading it.
948 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
949=back 1072=back
950 1073
951=head1 WHAT TO DO IN A MODULE 1074=head1 WHAT TO DO IN A MODULE
952 1075
953As 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
963because 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
964events is to stay interactive. 1087events is to stay interactive.
965 1088
966It 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
967requests 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
968called C<results> that returns the results, it should call C<< ->recv >> 1091called C<results> that returns the results, it may call C<< ->recv >>
969freely, 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).
970 1093
971=head1 WHAT TO DO IN THE MAIN PROGRAM 1094=head1 WHAT TO DO IN THE MAIN PROGRAM
972 1095
973There 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
974dictate which event model to use. 1097dictate which event model to use.
975 1098
976If 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
977do 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
978decide 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.
979 1104
980If 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
981Gtk2 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
982event module before loading AnyEvent or any module that uses it: generally 1107event module before loading AnyEvent or any module that uses it: generally
983speaking, 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
984modules might create watchers when they are loaded, and AnyEvent will 1109modules might create watchers when they are loaded, and AnyEvent will
985decide 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
986might chose the wrong one unless you load the correct one yourself. 1111might choose the wrong one unless you load the correct one yourself.
987 1112
988You can chose to use a pure-perl implementation by loading the 1113You can chose to use a pure-perl implementation by loading the
989C<AnyEvent::Impl::Perl> module, which gives you similar behaviour 1114C<AnyEvent::Loop> module, which gives you similar behaviour
990everywhere, but letting AnyEvent chose the model is generally better. 1115everywhere, but letting AnyEvent chose the model is generally better.
991 1116
992=head2 MAINLOOP EMULATION 1117=head2 MAINLOOP EMULATION
993 1118
994Sometimes (often for short test scripts, or even standalone programs who 1119Sometimes (often for short test scripts, or even standalone programs who
1007 1132
1008 1133
1009=head1 OTHER MODULES 1134=head1 OTHER MODULES
1010 1135
1011The following is a non-exhaustive list of additional modules that use 1136The following is a non-exhaustive list of additional modules that use
1012AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1137AnyEvent as a client and can therefore be mixed easily with other
1013modules 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
1014come 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 :)
1015 1143
1016=over 4 1144=over 4
1017 1145
1018=item L<AnyEvent::Util> 1146=item L<AnyEvent::Util>
1019 1147
1020Contains various utility functions that replace often-used but blocking 1148Contains various utility functions that replace often-used blocking
1021functions such as C<inet_aton> by event-/callback-based versions. 1149functions such as C<inet_aton> with event/callback-based versions.
1022 1150
1023=item L<AnyEvent::Socket> 1151=item L<AnyEvent::Socket>
1024 1152
1025Provides various utility functions for (internet protocol) sockets, 1153Provides various utility functions for (internet protocol) sockets,
1026addresses and name resolution. Also functions to create non-blocking tcp 1154addresses and name resolution. Also functions to create non-blocking tcp
1028 1156
1029=item L<AnyEvent::Handle> 1157=item L<AnyEvent::Handle>
1030 1158
1031Provide read and write buffers, manages watchers for reads and writes, 1159Provide read and write buffers, manages watchers for reads and writes,
1032supports 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
1033non-blocking SSL/TLS (via L<AnyEvent::TLS>. 1161non-blocking SSL/TLS (via L<AnyEvent::TLS>).
1034 1162
1035=item L<AnyEvent::DNS> 1163=item L<AnyEvent::DNS>
1036 1164
1037Provides rich asynchronous DNS resolver capabilities. 1165Provides rich asynchronous DNS resolver capabilities.
1038 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
1039=item L<AnyEvent::HTTP> 1173=item L<AnyEvent::AIO>
1040 1174
1041A 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
1042HTTP 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.
1043 1197
1044=item L<AnyEvent::HTTPD> 1198=item L<AnyEvent::HTTPD>
1045 1199
1046Provides a simple web application server framework. 1200A simple embedded webserver.
1047 1201
1048=item L<AnyEvent::FastPing> 1202=item L<AnyEvent::FastPing>
1049 1203
1050The fastest ping in the west. 1204The fastest ping in the west.
1051 1205
1052=item L<AnyEvent::DBI>
1053
1054Executes L<DBI> requests asynchronously in a proxy process.
1055
1056=item L<AnyEvent::AIO>
1057
1058Truly asynchronous I/O, should be in the toolbox of every event
1059programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
1060together.
1061
1062=item L<AnyEvent::BDB>
1063
1064Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
1065L<BDB> and AnyEvent together.
1066
1067=item L<AnyEvent::GPSD>
1068
1069A non-blocking interface to gpsd, a daemon delivering GPS information.
1070
1071=item L<AnyEvent::IRC>
1072
1073AnyEvent based IRC client module family (replacing the older Net::IRC3).
1074
1075=item L<AnyEvent::XMPP>
1076
1077AnyEvent based XMPP (Jabber protocol) module family (replacing the older
1078Net::XMPP2>.
1079
1080=item L<AnyEvent::IGS>
1081
1082A non-blocking interface to the Internet Go Server protocol (used by
1083L<App::IGS>).
1084
1085=item L<Net::FCP>
1086
1087AnyEvent-based implementation of the Freenet Client Protocol, birthplace
1088of AnyEvent.
1089
1090=item L<Event::ExecFlow>
1091
1092High level API for event-based execution flow control.
1093
1094=item L<Coro> 1206=item L<Coro>
1095 1207
1096Has 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 };
1097 1221
1098=back 1222=back
1099 1223
1100=cut 1224=cut
1101 1225
1102package AnyEvent; 1226package AnyEvent;
1103 1227
1104# basically a tuned-down version of common::sense 1228# basically a tuned-down version of common::sense
1105sub common_sense { 1229sub common_sense {
1106 # no warnings 1230 # from common:.sense 3.4
1107 ${^WARNING_BITS} ^= ${^WARNING_BITS}; 1231 ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "\x3c\x3f\x33\x00\x0f\xf0\x0f\xc0\xf0\xfc\x33\x00";
1108 # use strict vars subs 1232 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1109 $^H |= 0x00000600; 1233 $^H |= 0x00000600;
1110} 1234}
1111 1235
1112BEGIN { AnyEvent::common_sense } 1236BEGIN { AnyEvent::common_sense }
1113 1237
1114use Carp (); 1238use Carp ();
1115 1239
1116our $VERSION = 4.881; 1240our $VERSION = '6.02';
1117our $MODEL; 1241our $MODEL;
1118 1242
1119our $AUTOLOAD;
1120our @ISA; 1243our @ISA;
1121 1244
1122our @REGISTRY; 1245our @REGISTRY;
1123 1246
1124our $WIN32;
1125
1126our $VERBOSE; 1247our $VERBOSE;
1127 1248
1128BEGIN { 1249BEGIN {
1129 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1250 require "AnyEvent/constants.pl";
1251
1130 eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; 1252 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1131 1253
1132 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1254 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1133 if ${^TAINT}; 1255 if ${^TAINT};
1134 1256
1135 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1257 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1258 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1136 1259
1260 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1261 if ${^TAINT};
1262
1263 # $ENV{PERL_ANYEVENT_xxx} now valid
1264
1265 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 3;
1137} 1266}
1138 1267
1139our $MAX_SIGNAL_LATENCY = 10; 1268our $MAX_SIGNAL_LATENCY = 10;
1140 1269
1141our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1270our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1145 $PROTOCOL{$_} = ++$idx 1274 $PROTOCOL{$_} = ++$idx
1146 for reverse split /\s*,\s*/, 1275 for reverse split /\s*,\s*/,
1147 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1276 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1148} 1277}
1149 1278
1279our @post_detect;
1280
1281sub post_detect(&) {
1282 my ($cb) = @_;
1283
1284 push @post_detect, $cb;
1285
1286 defined wantarray
1287 ? bless \$cb, "AnyEvent::Util::postdetect"
1288 : ()
1289}
1290
1291sub AnyEvent::Util::postdetect::DESTROY {
1292 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1293}
1294
1295our $POSTPONE_W;
1296our @POSTPONE;
1297
1298sub _postpone_exec {
1299 undef $POSTPONE_W;
1300
1301 &{ shift @POSTPONE }
1302 while @POSTPONE;
1303}
1304
1305sub postpone(&) {
1306 push @POSTPONE, shift;
1307
1308 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1309
1310 ()
1311}
1312
1313sub log($$;@) {
1314 # only load the big bloated module when we actually are about to log something
1315 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!)
1316 require AnyEvent::Log;
1317 # AnyEvent::Log overwrites this function
1318 goto &log;
1319 }
1320
1321 0 # not logged
1322}
1323
1324if (length $ENV{PERL_ANYEVENT_LOG}) {
1325 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1326}
1327
1150my @models = ( 1328our @models = (
1151 [EV:: => AnyEvent::Impl::EV:: , 1], 1329 [EV:: => AnyEvent::Impl::EV:: , 1],
1330 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
1331 # everything below here will not (normally) be autoprobed
1332 # as the pure perl backend should work everywhere
1333 # and is usually faster
1152 [Event:: => AnyEvent::Impl::Event::, 1], 1334 [Event:: => AnyEvent::Impl::Event::, 1],
1153 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1154 # everything below here will not (normally) be autoprobed
1155 # as the pureperl backend should work everywhere
1156 # and is usually faster
1157 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1335 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1158 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1336 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1159 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package 1337 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1160 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1338 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1161 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1339 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1162 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1340 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1163 [Wx:: => AnyEvent::Impl::POE::], 1341 [Wx:: => AnyEvent::Impl::POE::],
1164 [Prima:: => AnyEvent::Impl::POE::], 1342 [Prima:: => AnyEvent::Impl::POE::],
1165 # IO::Async is just too broken - we would need workarounds for its 1343 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1166 # byzantine signal and broken child handling, among others. 1344 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1167 # IO::Async is rather hard to detect, as it doesn't have any 1345 [FLTK:: => AnyEvent::Impl::FLTK::],
1168 # obvious default class.
1169# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1170# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1171# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1172); 1346);
1173 1347
1174our %method = map +($_ => 1), 1348our @isa_hook;
1349
1350sub _isa_set {
1351 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1352
1353 @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1354 for 1 .. $#pkg;
1355
1356 grep $_ && $_->[1], @isa_hook
1357 and AE::_reset ();
1358}
1359
1360# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1361sub _isa_hook($$;$) {
1362 my ($i, $pkg, $reset_ae) = @_;
1363
1364 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1365
1366 _isa_set;
1367}
1368
1369# all autoloaded methods reserve the complete glob, not just the method slot.
1370# due to bugs in perls method cache implementation.
1175 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1371our @methods = qw(io timer time now now_update signal child idle condvar);
1176 1372
1177our @post_detect;
1178
1179sub post_detect(&) { 1373sub detect() {
1180 my ($cb) = @_; 1374 return $MODEL if $MODEL; # some programs keep references to detect
1181 1375
1182 if ($MODEL) { 1376 local $!; # for good measure
1183 $cb->(); 1377 local $SIG{__DIE__}; # we use eval
1184 1378
1185 undef 1379 # free some memory
1380 *detect = sub () { $MODEL };
1381 # undef &func doesn't correctly update the method cache. grmbl.
1382 # so we delete the whole glob. grmbl.
1383 # otoh, perl doesn't let me undef an active usb, but it lets me free
1384 # a glob with an active sub. hrm. i hope it works, but perl is
1385 # usually buggy in this department. sigh.
1386 delete @{"AnyEvent::"}{@methods};
1387 undef @methods;
1388
1389 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1390 my $model = $1;
1391 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1392 if (eval "require $model") {
1393 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1394 $MODEL = $model;
1186 } else { 1395 } else {
1187 push @post_detect, $cb; 1396 AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1188 1397 }
1189 defined wantarray
1190 ? bless \$cb, "AnyEvent::Util::postdetect"
1191 : ()
1192 } 1398 }
1193}
1194 1399
1195sub AnyEvent::Util::postdetect::DESTROY { 1400 # check for already loaded models
1196 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1197}
1198
1199sub detect() {
1200 unless ($MODEL) { 1401 unless ($MODEL) {
1201 local $SIG{__DIE__}; 1402 for (@REGISTRY, @models) {
1202 1403 my ($package, $model) = @$_;
1203 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1404 if (${"$package\::VERSION"} > 0) {
1204 my $model = "AnyEvent::Impl::$1";
1205 if (eval "require $model") { 1405 if (eval "require $model") {
1406 AnyEvent::log 7 => "autodetected model '$model', using it.";
1206 $MODEL = $model; 1407 $MODEL = $model;
1207 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2; 1408 last;
1208 } else { 1409 }
1209 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
1210 } 1410 }
1211 } 1411 }
1212 1412
1213 # check for already loaded models
1214 unless ($MODEL) { 1413 unless ($MODEL) {
1414 # try to autoload a model
1215 for (@REGISTRY, @models) { 1415 for (@REGISTRY, @models) {
1216 my ($package, $model) = @$_; 1416 my ($package, $model, $autoload) = @$_;
1417 if (
1418 $autoload
1419 and eval "require $package"
1217 if (${"$package\::VERSION"} > 0) { 1420 and ${"$package\::VERSION"} > 0
1218 if (eval "require $model") { 1421 and eval "require $model"
1422 ) {
1423 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1219 $MODEL = $model; 1424 $MODEL = $model;
1220 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1221 last; 1425 last;
1222 }
1223 } 1426 }
1224 } 1427 }
1225 1428
1226 unless ($MODEL) {
1227 # try to autoload a model
1228 for (@REGISTRY, @models) {
1229 my ($package, $model, $autoload) = @$_;
1230 if (
1231 $autoload
1232 and eval "require $package"
1233 and ${"$package\::VERSION"} > 0
1234 and eval "require $model"
1235 ) {
1236 $MODEL = $model;
1237 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1238 last;
1239 }
1240 }
1241
1242 $MODEL 1429 $MODEL
1243 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n"; 1430 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1244 }
1245 } 1431 }
1246
1247 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1248
1249 unshift @ISA, $MODEL;
1250
1251 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
1252
1253 (shift @post_detect)->() while @post_detect;
1254 } 1432 }
1255 1433
1434 # free memory only needed for probing
1435 undef @models;
1436 undef @REGISTRY;
1437
1438 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1439
1440 # now nuke some methods that are overridden by the backend.
1441 # SUPER usage is not allowed in these.
1442 for (qw(time signal child idle)) {
1443 undef &{"AnyEvent::Base::$_"}
1444 if defined &{"$MODEL\::$_"};
1445 }
1446
1447 _isa_set;
1448
1449 # we're officially open!
1450
1451 if ($ENV{PERL_ANYEVENT_STRICT}) {
1452 require AnyEvent::Strict;
1453 }
1454
1455 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1456 require AnyEvent::Debug;
1457 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1458 }
1459
1460 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1461 require AnyEvent::Socket;
1462 require AnyEvent::Debug;
1463
1464 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1465 $shell =~ s/\$\$/$$/g;
1466
1467 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1468 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1469 }
1470
1471 # now the anyevent environment is set up as the user told us to, so
1472 # call the actual user code - post detects
1473
1474 (shift @post_detect)->() while @post_detect;
1475 undef @post_detect;
1476
1477 *post_detect = sub(&) {
1478 shift->();
1479
1480 undef
1481 };
1482
1256 $MODEL 1483 $MODEL
1257} 1484}
1258 1485
1259sub AUTOLOAD { 1486for my $name (@methods) {
1260 (my $func = $AUTOLOAD) =~ s/.*://; 1487 *$name = sub {
1261 1488 detect;
1262 $method{$func} 1489 # we use goto because
1263 or Carp::croak "$func: not a valid method for AnyEvent objects"; 1490 # a) it makes the thunk more transparent
1264 1491 # b) it allows us to delete the thunk later
1265 detect unless $MODEL; 1492 goto &{ UNIVERSAL::can AnyEvent => "SUPER::$name" }
1266 1493 };
1267 my $class = shift;
1268 $class->$func (@_);
1269} 1494}
1270 1495
1271# utility function to dup a filehandle. this is used by many backends 1496# utility function to dup a filehandle. this is used by many backends
1272# to support binding more than one watcher per filehandle (they usually 1497# to support binding more than one watcher per filehandle (they usually
1273# allow only one watcher per fd, so we dup it to get a different one). 1498# allow only one watcher per fd, so we dup it to get a different one).
1283 # we assume CLOEXEC is already set by perl in all important cases 1508 # we assume CLOEXEC is already set by perl in all important cases
1284 1509
1285 ($fh2, $rw) 1510 ($fh2, $rw)
1286} 1511}
1287 1512
1513=head1 SIMPLIFIED AE API
1514
1515Starting with version 5.0, AnyEvent officially supports a second, much
1516simpler, API that is designed to reduce the calling, typing and memory
1517overhead by using function call syntax and a fixed number of parameters.
1518
1519See the L<AE> manpage for details.
1520
1521=cut
1522
1523package AE;
1524
1525our $VERSION = $AnyEvent::VERSION;
1526
1527sub _reset() {
1528 eval q{
1529 # fall back to the main API by default - backends and AnyEvent::Base
1530 # implementations can overwrite these.
1531
1532 sub io($$$) {
1533 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1534 }
1535
1536 sub timer($$$) {
1537 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1538 }
1539
1540 sub signal($$) {
1541 AnyEvent->signal (signal => $_[0], cb => $_[1])
1542 }
1543
1544 sub child($$) {
1545 AnyEvent->child (pid => $_[0], cb => $_[1])
1546 }
1547
1548 sub idle($) {
1549 AnyEvent->idle (cb => $_[0]);
1550 }
1551
1552 sub cv(;&) {
1553 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1554 }
1555
1556 sub now() {
1557 AnyEvent->now
1558 }
1559
1560 sub now_update() {
1561 AnyEvent->now_update
1562 }
1563
1564 sub time() {
1565 AnyEvent->time
1566 }
1567
1568 *postpone = \&AnyEvent::postpone;
1569 *log = \&AnyEvent::log;
1570 };
1571 die if $@;
1572}
1573
1574BEGIN { _reset }
1575
1288package AnyEvent::Base; 1576package AnyEvent::Base;
1289 1577
1290# default implementations for many methods 1578# default implementations for many methods
1291 1579
1292sub _time { 1580sub time {
1581 eval q{ # poor man's autoloading {}
1293 # probe for availability of Time::HiRes 1582 # probe for availability of Time::HiRes
1294 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1583 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1295 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1584 *time = sub { Time::HiRes::time () };
1296 *_time = \&Time::HiRes::time; 1585 *AE::time = \& Time::HiRes::time ;
1586 *now = \&time;
1587 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1297 # if (eval "use POSIX (); (POSIX::times())... 1588 # if (eval "use POSIX (); (POSIX::times())...
1298 } else { 1589 } else {
1590 *time = sub { CORE::time };
1591 *AE::time = sub (){ CORE::time };
1592 *now = \&time;
1299 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1593 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1300 *_time = sub { time }; # epic fail 1594 }
1301 } 1595 };
1596 die if $@;
1302 1597
1303 &_time 1598 &time
1304} 1599}
1305 1600
1306sub time { _time } 1601*now = \&time;
1307sub now { _time }
1308sub now_update { } 1602sub now_update { }
1309 1603
1604sub _poll {
1605 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1606}
1607
1310# default implementation for ->condvar 1608# default implementation for ->condvar
1609# in fact, the default should not be overwritten
1311 1610
1312sub condvar { 1611sub condvar {
1612 eval q{ # poor man's autoloading {}
1613 *condvar = sub {
1313 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" 1614 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1615 };
1616
1617 *AE::cv = sub (;&) {
1618 bless { @_ ? (_ae_cb => shift) : () }, "AnyEvent::CondVar"
1619 };
1620 };
1621 die if $@;
1622
1623 &condvar
1314} 1624}
1315 1625
1316# default implementation for ->signal 1626# default implementation for ->signal
1317 1627
1318our $HAVE_ASYNC_INTERRUPT; 1628our $HAVE_ASYNC_INTERRUPT;
1319 1629
1320sub _have_async_interrupt() { 1630sub _have_async_interrupt() {
1321 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} 1631 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT}
1322 && eval "use Async::Interrupt 1.0 (); 1") 1632 && eval "use Async::Interrupt 1.02 (); 1")
1323 unless defined $HAVE_ASYNC_INTERRUPT; 1633 unless defined $HAVE_ASYNC_INTERRUPT;
1324 1634
1325 $HAVE_ASYNC_INTERRUPT 1635 $HAVE_ASYNC_INTERRUPT
1326} 1636}
1327 1637
1328our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1638our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1329our (%SIG_ASY, %SIG_ASY_W); 1639our (%SIG_ASY, %SIG_ASY_W);
1330our ($SIG_COUNT, $SIG_TW); 1640our ($SIG_COUNT, $SIG_TW);
1331 1641
1332sub _signal_exec {
1333 $HAVE_ASYNC_INTERRUPT
1334 ? $SIGPIPE_R->drain
1335 : sysread $SIGPIPE_R, my $dummy, 9;
1336
1337 while (%SIG_EV) {
1338 for (keys %SIG_EV) {
1339 delete $SIG_EV{$_};
1340 $_->() for values %{ $SIG_CB{$_} || {} };
1341 }
1342 }
1343}
1344
1345# install a dummy wakeup watcher to reduce signal catching latency 1642# install a dummy wakeup watcher to reduce signal catching latency
1643# used by Impls
1346sub _sig_add() { 1644sub _sig_add() {
1347 unless ($SIG_COUNT++) { 1645 unless ($SIG_COUNT++) {
1348 # try to align timer on a full-second boundary, if possible 1646 # try to align timer on a full-second boundary, if possible
1349 my $NOW = AnyEvent->now; 1647 my $NOW = AE::now;
1350 1648
1351 $SIG_TW = AnyEvent->timer ( 1649 $SIG_TW = AE::timer
1352 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW), 1650 $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1353 interval => $MAX_SIGNAL_LATENCY, 1651 $MAX_SIGNAL_LATENCY,
1354 cb => sub { }, # just for the PERL_ASYNC_CHECK 1652 sub { } # just for the PERL_ASYNC_CHECK
1355 ); 1653 ;
1356 } 1654 }
1357} 1655}
1358 1656
1359sub _sig_del { 1657sub _sig_del {
1360 undef $SIG_TW 1658 undef $SIG_TW
1361 unless --$SIG_COUNT; 1659 unless --$SIG_COUNT;
1362} 1660}
1363 1661
1364our $_sig_name_init; $_sig_name_init = sub { 1662our $_sig_name_init; $_sig_name_init = sub {
1365 eval q{ # poor man's autoloading 1663 eval q{ # poor man's autoloading {}
1366 undef $_sig_name_init; 1664 undef $_sig_name_init;
1367 1665
1368 if (_have_async_interrupt) { 1666 if (_have_async_interrupt) {
1369 *sig2num = \&Async::Interrupt::sig2num; 1667 *sig2num = \&Async::Interrupt::sig2num;
1370 *sig2name = \&Async::Interrupt::sig2name; 1668 *sig2name = \&Async::Interrupt::sig2name;
1394 1692
1395sub signal { 1693sub signal {
1396 eval q{ # poor man's autoloading {} 1694 eval q{ # poor man's autoloading {}
1397 # probe for availability of Async::Interrupt 1695 # probe for availability of Async::Interrupt
1398 if (_have_async_interrupt) { 1696 if (_have_async_interrupt) {
1399 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1697 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1400 1698
1401 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1699 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1402 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec); 1700 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1403 1701
1404 } else { 1702 } else {
1405 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1703 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1406
1407 require Fcntl;
1408 1704
1409 if (AnyEvent::WIN32) { 1705 if (AnyEvent::WIN32) {
1410 require AnyEvent::Util; 1706 require AnyEvent::Util;
1411 1707
1412 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1708 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1413 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R; 1709 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
1414 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case 1710 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case
1415 } else { 1711 } else {
1416 pipe $SIGPIPE_R, $SIGPIPE_W; 1712 pipe $SIGPIPE_R, $SIGPIPE_W;
1417 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R; 1713 fcntl $SIGPIPE_R, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_R;
1418 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case 1714 fcntl $SIGPIPE_W, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_W; # just in case
1419 1715
1420 # not strictly required, as $^F is normally 2, but let's make sure... 1716 # not strictly required, as $^F is normally 2, but let's make sure...
1421 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC; 1717 fcntl $SIGPIPE_R, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1422 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC; 1718 fcntl $SIGPIPE_W, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1423 } 1719 }
1424 1720
1425 $SIGPIPE_R 1721 $SIGPIPE_R
1426 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1722 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1427 1723
1428 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1724 $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;
1429 } 1725 }
1430 1726
1431 *signal = sub { 1727 *signal = $HAVE_ASYNC_INTERRUPT
1728 ? sub {
1432 my (undef, %arg) = @_; 1729 my (undef, %arg) = @_;
1433 1730
1434 my $signal = uc $arg{signal}
1435 or Carp::croak "required option 'signal' is missing";
1436
1437 if ($HAVE_ASYNC_INTERRUPT) {
1438 # async::interrupt 1731 # async::interrupt
1439
1440 $signal = sig2num $signal; 1732 my $signal = sig2num $arg{signal};
1441 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1733 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1442 1734
1443 $SIG_ASY{$signal} ||= new Async::Interrupt 1735 $SIG_ASY{$signal} ||= new Async::Interrupt
1444 cb => sub { undef $SIG_EV{$signal} }, 1736 cb => sub { undef $SIG_EV{$signal} },
1445 signal => $signal, 1737 signal => $signal,
1446 pipe => [$SIGPIPE_R->filenos], 1738 pipe => [$SIGPIPE_R->filenos],
1447 pipe_autodrain => 0, 1739 pipe_autodrain => 0,
1448 ; 1740 ;
1449 1741
1450 } else { 1742 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1743 }
1744 : sub {
1745 my (undef, %arg) = @_;
1746
1451 # pure perl 1747 # pure perl
1452
1453 # AE::Util has been loaded in signal
1454 $signal = sig2name $signal; 1748 my $signal = sig2name $arg{signal};
1455 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1749 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1456 1750
1457 $SIG{$signal} ||= sub { 1751 $SIG{$signal} ||= sub {
1458 local $!; 1752 local $!;
1459 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1753 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1460 undef $SIG_EV{$signal}; 1754 undef $SIG_EV{$signal};
1461 }; 1755 };
1462 1756
1463 # can't do signal processing without introducing races in pure perl, 1757 # can't do signal processing without introducing races in pure perl,
1464 # so limit the signal latency. 1758 # so limit the signal latency.
1465 _sig_add; 1759 _sig_add;
1466 }
1467 1760
1468 bless [$signal, $arg{cb}], "AnyEvent::Base::signal" 1761 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1762 }
1469 }; 1763 ;
1470 1764
1471 *AnyEvent::Base::signal::DESTROY = sub { 1765 *AnyEvent::Base::signal::DESTROY = sub {
1472 my ($signal, $cb) = @{$_[0]}; 1766 my ($signal, $cb) = @{$_[0]};
1473 1767
1474 _sig_del; 1768 _sig_del;
1481 # print weird messages, or just unconditionally exit 1775 # print weird messages, or just unconditionally exit
1482 # instead of getting the default action. 1776 # instead of getting the default action.
1483 undef $SIG{$signal} 1777 undef $SIG{$signal}
1484 unless keys %{ $SIG_CB{$signal} }; 1778 unless keys %{ $SIG_CB{$signal} };
1485 }; 1779 };
1780
1781 *_signal_exec = sub {
1782 $HAVE_ASYNC_INTERRUPT
1783 ? $SIGPIPE_R->drain
1784 : sysread $SIGPIPE_R, (my $dummy), 9;
1785
1786 while (%SIG_EV) {
1787 for (keys %SIG_EV) {
1788 delete $SIG_EV{$_};
1789 &$_ for values %{ $SIG_CB{$_} || {} };
1790 }
1791 }
1792 };
1486 }; 1793 };
1487 die if $@; 1794 die if $@;
1795
1488 &signal 1796 &signal
1489} 1797}
1490 1798
1491# default implementation for ->child 1799# default implementation for ->child
1492 1800
1493our %PID_CB; 1801our %PID_CB;
1494our $CHLD_W; 1802our $CHLD_W;
1495our $CHLD_DELAY_W; 1803our $CHLD_DELAY_W;
1496our $WNOHANG;
1497 1804
1805# used by many Impl's
1498sub _emit_childstatus($$) { 1806sub _emit_childstatus($$) {
1499 my (undef, $rpid, $rstatus) = @_; 1807 my (undef, $rpid, $rstatus) = @_;
1500 1808
1501 $_->($rpid, $rstatus) 1809 $_->($rpid, $rstatus)
1502 for values %{ $PID_CB{$rpid} || {} }, 1810 for values %{ $PID_CB{$rpid} || {} },
1503 values %{ $PID_CB{0} || {} }; 1811 values %{ $PID_CB{0} || {} };
1504} 1812}
1505 1813
1506sub _sigchld {
1507 my $pid;
1508
1509 AnyEvent->_emit_childstatus ($pid, $?)
1510 while ($pid = waitpid -1, $WNOHANG) > 0;
1511}
1512
1513sub child { 1814sub child {
1815 eval q{ # poor man's autoloading {}
1816 *_sigchld = sub {
1817 my $pid;
1818
1819 AnyEvent->_emit_childstatus ($pid, $?)
1820 while ($pid = waitpid -1, WNOHANG) > 0;
1821 };
1822
1823 *child = sub {
1514 my (undef, %arg) = @_; 1824 my (undef, %arg) = @_;
1515 1825
1516 defined (my $pid = $arg{pid} + 0) 1826 my $pid = $arg{pid};
1517 or Carp::croak "required option 'pid' is missing"; 1827 my $cb = $arg{cb};
1518 1828
1519 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1829 $PID_CB{$pid}{$cb+0} = $cb;
1520 1830
1521 # WNOHANG is almost cetrainly 1 everywhere
1522 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1523 ? 1
1524 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1525
1526 unless ($CHLD_W) { 1831 unless ($CHLD_W) {
1527 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1832 $CHLD_W = AE::signal CHLD => \&_sigchld;
1528 # child could be a zombie already, so make at least one round 1833 # child could be a zombie already, so make at least one round
1529 &_sigchld; 1834 &_sigchld;
1530 } 1835 }
1531 1836
1532 bless [$pid, $arg{cb}], "AnyEvent::Base::child" 1837 bless [$pid, $cb+0], "AnyEvent::Base::child"
1533} 1838 };
1534 1839
1535sub AnyEvent::Base::child::DESTROY { 1840 *AnyEvent::Base::child::DESTROY = sub {
1536 my ($pid, $cb) = @{$_[0]}; 1841 my ($pid, $icb) = @{$_[0]};
1537 1842
1538 delete $PID_CB{$pid}{$cb}; 1843 delete $PID_CB{$pid}{$icb};
1539 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1844 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1540 1845
1541 undef $CHLD_W unless keys %PID_CB; 1846 undef $CHLD_W unless keys %PID_CB;
1847 };
1848 };
1849 die if $@;
1850
1851 &child
1542} 1852}
1543 1853
1544# idle emulation is done by simply using a timer, regardless 1854# idle emulation is done by simply using a timer, regardless
1545# of whether the process is idle or not, and not letting 1855# of whether the process is idle or not, and not letting
1546# the callback use more than 50% of the time. 1856# the callback use more than 50% of the time.
1547sub idle { 1857sub idle {
1858 eval q{ # poor man's autoloading {}
1859 *idle = sub {
1548 my (undef, %arg) = @_; 1860 my (undef, %arg) = @_;
1549 1861
1550 my ($cb, $w, $rcb) = $arg{cb}; 1862 my ($cb, $w, $rcb) = $arg{cb};
1551 1863
1552 $rcb = sub { 1864 $rcb = sub {
1553 if ($cb) { 1865 if ($cb) {
1554 $w = _time; 1866 $w = AE::time;
1555 &$cb; 1867 &$cb;
1556 $w = _time - $w; 1868 $w = AE::time - $w;
1557 1869
1558 # never use more then 50% of the time for the idle watcher, 1870 # never use more then 50% of the time for the idle watcher,
1559 # within some limits 1871 # within some limits
1560 $w = 0.0001 if $w < 0.0001; 1872 $w = 0.0001 if $w < 0.0001;
1561 $w = 5 if $w > 5; 1873 $w = 5 if $w > 5;
1562 1874
1563 $w = AnyEvent->timer (after => $w, cb => $rcb); 1875 $w = AE::timer $w, 0, $rcb;
1564 } else { 1876 } else {
1565 # clean up... 1877 # clean up...
1566 undef $w; 1878 undef $w;
1567 undef $rcb; 1879 undef $rcb;
1880 }
1881 };
1882
1883 $w = AE::timer 0.05, 0, $rcb;
1884
1885 bless \\$cb, "AnyEvent::Base::idle"
1568 } 1886 };
1887
1888 *AnyEvent::Base::idle::DESTROY = sub {
1889 undef $${$_[0]};
1890 };
1569 }; 1891 };
1892 die if $@;
1570 1893
1571 $w = AnyEvent->timer (after => 0.05, cb => $rcb); 1894 &idle
1572
1573 bless \\$cb, "AnyEvent::Base::idle"
1574}
1575
1576sub AnyEvent::Base::idle::DESTROY {
1577 undef $${$_[0]};
1578} 1895}
1579 1896
1580package AnyEvent::CondVar; 1897package AnyEvent::CondVar;
1581 1898
1582our @ISA = AnyEvent::CondVar::Base::; 1899our @ISA = AnyEvent::CondVar::Base::;
1900
1901# only to be used for subclassing
1902sub new {
1903 my $class = shift;
1904 bless AnyEvent->condvar (@_), $class
1905}
1583 1906
1584package AnyEvent::CondVar::Base; 1907package AnyEvent::CondVar::Base;
1585 1908
1586#use overload 1909#use overload
1587# '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1910# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1597 1920
1598sub _send { 1921sub _send {
1599 # nop 1922 # nop
1600} 1923}
1601 1924
1925sub _wait {
1926 AnyEvent->_poll until $_[0]{_ae_sent};
1927}
1928
1602sub send { 1929sub send {
1603 my $cv = shift; 1930 my $cv = shift;
1604 $cv->{_ae_sent} = [@_]; 1931 $cv->{_ae_sent} = [@_];
1605 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb}; 1932 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
1606 $cv->_send; 1933 $cv->_send;
1613 1940
1614sub ready { 1941sub ready {
1615 $_[0]{_ae_sent} 1942 $_[0]{_ae_sent}
1616} 1943}
1617 1944
1618sub _wait {
1619 $WAITING
1620 and !$_[0]{_ae_sent}
1621 and Carp::croak "AnyEvent::CondVar: recursive blocking wait detected";
1622
1623 local $WAITING = 1;
1624 AnyEvent->one_event while !$_[0]{_ae_sent};
1625}
1626
1627sub recv { 1945sub recv {
1946 unless ($_[0]{_ae_sent}) {
1947 $WAITING
1948 and Carp::croak "AnyEvent::CondVar: recursive blocking wait attempted";
1949
1950 local $WAITING = 1;
1628 $_[0]->_wait; 1951 $_[0]->_wait;
1952 }
1629 1953
1630 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak}; 1954 $_[0]{_ae_croak}
1631 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0] 1955 and Carp::croak $_[0]{_ae_croak};
1956
1957 wantarray
1958 ? @{ $_[0]{_ae_sent} }
1959 : $_[0]{_ae_sent}[0]
1632} 1960}
1633 1961
1634sub cb { 1962sub cb {
1635 $_[0]{_ae_cb} = $_[1] if @_ > 1; 1963 my $cv = shift;
1964
1965 @_
1966 and $cv->{_ae_cb} = shift
1967 and $cv->{_ae_sent}
1968 and (delete $cv->{_ae_cb})->($cv);
1969
1636 $_[0]{_ae_cb} 1970 $cv->{_ae_cb}
1637} 1971}
1638 1972
1639sub begin { 1973sub begin {
1640 ++$_[0]{_ae_counter}; 1974 ++$_[0]{_ae_counter};
1641 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 1975 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
1646 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } }; 1980 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
1647} 1981}
1648 1982
1649# undocumented/compatibility with pre-3.4 1983# undocumented/compatibility with pre-3.4
1650*broadcast = \&send; 1984*broadcast = \&send;
1651*wait = \&_wait; 1985*wait = \&recv;
1652
1653#############################################################################
1654# "new" API, currently only emulation of it
1655#############################################################################
1656
1657package AE;
1658
1659sub io($$$) {
1660 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1661}
1662
1663sub timer($$$) {
1664 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]);
1665}
1666
1667sub signal($$) {
1668 AnyEvent->signal (signal => $_[0], cb => $_[1]);
1669}
1670
1671sub child($$) {
1672 AnyEvent->child (pid => $_[0], cb => $_[1]);
1673}
1674
1675sub idle($) {
1676 AnyEvent->idle (cb => $_[0]);
1677}
1678
1679sub cv() {
1680 AnyEvent->condvar
1681}
1682
1683sub now() {
1684 AnyEvent->now
1685}
1686
1687sub now_update() {
1688 AnyEvent->now_update
1689}
1690
1691sub time() {
1692 AnyEvent->time
1693}
1694 1986
1695=head1 ERROR AND EXCEPTION HANDLING 1987=head1 ERROR AND EXCEPTION HANDLING
1696 1988
1697In general, AnyEvent does not do any error handling - it relies on the 1989In general, AnyEvent does not do any error handling - it relies on the
1698caller to do that if required. The L<AnyEvent::Strict> module (see also 1990caller to do that if required. The L<AnyEvent::Strict> module (see also
1710$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2002$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1711so on. 2003so on.
1712 2004
1713=head1 ENVIRONMENT VARIABLES 2005=head1 ENVIRONMENT VARIABLES
1714 2006
1715The following environment variables are used by this module or its 2007AnyEvent supports a number of environment variables that tune the
1716submodules. 2008runtime behaviour. They are usually evaluated when AnyEvent is
2009loaded, initialised, or a submodule that uses them is loaded. Many of
2010them also cause AnyEvent to load additional modules - for example,
2011C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2012loaded.
1717 2013
1718Note that AnyEvent will remove I<all> environment variables starting with 2014All the environment variables documented here start with
1719C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2015C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1720enabled. 2016namespace. Other modules are encouraged (but by no means required) to use
2017C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2018namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2019be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2020variables starting with C<AE_>, see below).
2021
2022All variables can also be set via the C<AE_> prefix, that is, instead
2023of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2024case there is a clash btween anyevent and another program that uses
2025C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2026variable to the empty string, as those variables take precedence.
2027
2028When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2029to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2030exists. If taint mode is on, then AnyEvent will remove I<all> environment
2031variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2032with C<undef> or the empty string, if the corresaponding C<AE_> variable
2033is set).
2034
2035The exact algorithm is currently:
2036
2037 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2038 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2039 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2040
2041This ensures that child processes will not see the C<AE_> variables.
2042
2043The following environment variables are currently known to AnyEvent:
1721 2044
1722=over 4 2045=over 4
1723 2046
1724=item C<PERL_ANYEVENT_VERBOSE> 2047=item C<PERL_ANYEVENT_VERBOSE>
1725 2048
1726By default, AnyEvent will be completely silent except in fatal 2049By default, AnyEvent will only log messages with loglevel C<3>
1727conditions. You can set this environment variable to make AnyEvent more 2050(C<critical>) or higher (see L<AnyEvent::Log>). You can set this
2051environment variable to a numerical loglevel to make AnyEvent more (or
1728talkative. 2052less) talkative.
1729 2053
2054If you want to do more than just set the global logging level
2055you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2056complex specifications.
2057
2058When set to C<0> (C<off>), then no messages whatsoever will be logged with
2059the default logging settings.
2060
1730When set to C<1> or higher, causes AnyEvent to warn about unexpected 2061When set to C<5> or higher (C<warn>), causes AnyEvent to warn about
1731conditions, such as not being able to load the event model specified by 2062unexpected conditions, such as not being able to load the event model
1732C<PERL_ANYEVENT_MODEL>. 2063specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2064exception - this is the minimum recommended level.
1733 2065
1734When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2066When set to C<7> or higher (info), cause AnyEvent to report which event model it
1735model it chooses. 2067chooses.
1736 2068
1737When set to C<8> or higher, then AnyEvent will report extra information on 2069When set to C<8> or higher (debug), then AnyEvent will report extra information on
1738which optional modules it loads and how it implements certain features. 2070which optional modules it loads and how it implements certain features.
2071
2072=item C<PERL_ANYEVENT_LOG>
2073
2074Accepts rather complex logging specifications. For example, you could log
2075all C<debug> messages of some module to stderr, warnings and above to
2076stderr, and errors and above to syslog, with:
2077
2078 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2079
2080For the rather extensive details, see L<AnyEvent::Log>.
2081
2082This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2083so will take effect even before AnyEvent has initialised itself.
2084
2085Note that specifying this environment variable causes the L<AnyEvent::Log>
2086module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2087using the latter saves a few hundred kB of memory until the first message
2088is being logged.
1739 2089
1740=item C<PERL_ANYEVENT_STRICT> 2090=item C<PERL_ANYEVENT_STRICT>
1741 2091
1742AnyEvent does not do much argument checking by default, as thorough 2092AnyEvent does not do much argument checking by default, as thorough
1743argument checking is very costly. Setting this variable to a true value 2093argument checking is very costly. Setting this variable to a true value
1745check the arguments passed to most method calls. If it finds any problems, 2095check the arguments passed to most method calls. If it finds any problems,
1746it will croak. 2096it will croak.
1747 2097
1748In other words, enables "strict" mode. 2098In other words, enables "strict" mode.
1749 2099
1750Unlike C<use strict> (or it's modern cousin, C<< use L<common::sense> 2100Unlike C<use strict> (or its modern cousin, C<< use L<common::sense>
1751>>, it is definitely recommended to keep it off in production. Keeping 2101>>, it is definitely recommended to keep it off in production. Keeping
1752C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2102C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1753can be very useful, however. 2103can be very useful, however.
1754 2104
2105=item C<PERL_ANYEVENT_DEBUG_SHELL>
2106
2107If this env variable is set, then its contents will be interpreted by
2108C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
2109C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
2110that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
2111
2112This happens when the first watcher is created.
2113
2114For example, to bind a debug shell on a unix domain socket in
2115F<< /tmp/debug<pid>.sock >>, you could use this:
2116
2117 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2118
2119Note that creating sockets in F</tmp> is very unsafe on multiuser
2120systems.
2121
2122=item C<PERL_ANYEVENT_DEBUG_WRAP>
2123
2124Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2125debugging purposes. See C<AnyEvent::Debug::wrap> for details.
2126
1755=item C<PERL_ANYEVENT_MODEL> 2127=item C<PERL_ANYEVENT_MODEL>
1756 2128
1757This can be used to specify the event model to be used by AnyEvent, before 2129This can be used to specify the event model to be used by AnyEvent, before
1758auto detection and -probing kicks in. It must be a string consisting 2130auto detection and -probing kicks in.
1759entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 2131
2132It normally is a string consisting entirely of ASCII letters (e.g. C<EV>
2133or C<IOAsync>). The string C<AnyEvent::Impl::> gets prepended and the
1760and the resulting module name is loaded and if the load was successful, 2134resulting module name is loaded and - if the load was successful - used as
1761used as event model. If it fails to load AnyEvent will proceed with 2135event model backend. If it fails to load then AnyEvent will proceed with
1762auto detection and -probing. 2136auto detection and -probing.
1763 2137
1764This functionality might change in future versions. 2138If the string ends with C<::> instead (e.g. C<AnyEvent::Impl::EV::>) then
2139nothing gets prepended and the module name is used as-is (hint: C<::> at
2140the end of a string designates a module name and quotes it appropriately).
1765 2141
1766For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 2142For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
1767could start your program like this: 2143could start your program like this:
1768 2144
1769 PERL_ANYEVENT_MODEL=Perl perl ... 2145 PERL_ANYEVENT_MODEL=Perl perl ...
1770 2146
1771=item C<PERL_ANYEVENT_PROTOCOLS> 2147=item C<PERL_ANYEVENT_PROTOCOLS>
1787but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2163but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1788- only support IPv4, never try to resolve or contact IPv6 2164- only support IPv4, never try to resolve or contact IPv6
1789addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2165addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1790IPv6, but prefer IPv6 over IPv4. 2166IPv6, but prefer IPv6 over IPv4.
1791 2167
2168=item C<PERL_ANYEVENT_HOSTS>
2169
2170This variable, if specified, overrides the F</etc/hosts> file used by
2171L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2172from that file instead.
2173
1792=item C<PERL_ANYEVENT_EDNS0> 2174=item C<PERL_ANYEVENT_EDNS0>
1793 2175
1794Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2176Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
1795for DNS. This extension is generally useful to reduce DNS traffic, but 2177DNS. This extension is generally useful to reduce DNS traffic, especially
1796some (broken) firewalls drop such DNS packets, which is why it is off by 2178when DNSSEC is involved, but some (broken) firewalls drop such DNS
1797default. 2179packets, which is why it is off by default.
1798 2180
1799Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2181Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1800EDNS0 in its DNS requests. 2182EDNS0 in its DNS requests.
1801 2183
1802=item C<PERL_ANYEVENT_MAX_FORKS> 2184=item C<PERL_ANYEVENT_MAX_FORKS>
1810resolver - this is the maximum number of parallel DNS requests that are 2192resolver - this is the maximum number of parallel DNS requests that are
1811sent to the DNS server. 2193sent to the DNS server.
1812 2194
1813=item C<PERL_ANYEVENT_RESOLV_CONF> 2195=item C<PERL_ANYEVENT_RESOLV_CONF>
1814 2196
1815The file to use instead of F</etc/resolv.conf> (or OS-specific 2197The absolute path to a F<resolv.conf>-style file to use instead of
1816configuration) in the default resolver. When set to the empty string, no 2198F</etc/resolv.conf> (or the OS-specific configuration) in the default
1817default config will be used. 2199resolver, or the empty string to select the default configuration.
1818 2200
1819=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2201=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1820 2202
1821When neither C<ca_file> nor C<ca_path> was specified during 2203When neither C<ca_file> nor C<ca_path> was specified during
1822L<AnyEvent::TLS> context creation, and either of these environment 2204L<AnyEvent::TLS> context creation, and either of these environment
1823variables exist, they will be used to specify CA certificate locations 2205variables are nonempty, they will be used to specify CA certificate
1824instead of a system-dependent default. 2206locations instead of a system-dependent default.
1825 2207
1826=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2208=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1827 2209
1828When these are set to C<1>, then the respective modules are not 2210When these are set to C<1>, then the respective modules are not
1829loaded. Mostly good for testing AnyEvent itself. 2211loaded. Mostly good for testing AnyEvent itself.
1892 warn "read: $input\n"; # output what has been read 2274 warn "read: $input\n"; # output what has been read
1893 $cv->send if $input =~ /^q/i; # quit program if /^q/i 2275 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1894 }, 2276 },
1895 ); 2277 );
1896 2278
1897 my $time_watcher; # can only be used once
1898
1899 sub new_timer {
1900 $timer = AnyEvent->timer (after => 1, cb => sub { 2279 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
1901 warn "timeout\n"; # print 'timeout' about every second 2280 warn "timeout\n"; # print 'timeout' at most every second
1902 &new_timer; # and restart the time
1903 }); 2281 });
1904 }
1905
1906 new_timer; # create first timer
1907 2282
1908 $cv->recv; # wait until user enters /^q/i 2283 $cv->recv; # wait until user enters /^q/i
1909 2284
1910=head1 REAL-WORLD EXAMPLE 2285=head1 REAL-WORLD EXAMPLE
1911 2286
1984 2359
1985The actual code goes further and collects all errors (C<die>s, exceptions) 2360The actual code goes further and collects all errors (C<die>s, exceptions)
1986that occurred during request processing. The C<result> method detects 2361that occurred during request processing. The C<result> method detects
1987whether an exception as thrown (it is stored inside the $txn object) 2362whether an exception as thrown (it is stored inside the $txn object)
1988and just throws the exception, which means connection errors and other 2363and just throws the exception, which means connection errors and other
1989problems get reported tot he code that tries to use the result, not in a 2364problems get reported to the code that tries to use the result, not in a
1990random callback. 2365random callback.
1991 2366
1992All of this enables the following usage styles: 2367All of this enables the following usage styles:
1993 2368
19941. Blocking: 23691. Blocking:
2042through AnyEvent. The benchmark creates a lot of timers (with a zero 2417through AnyEvent. The benchmark creates a lot of timers (with a zero
2043timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 2418timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
2044which it is), lets them fire exactly once and destroys them again. 2419which it is), lets them fire exactly once and destroys them again.
2045 2420
2046Source code for this benchmark is found as F<eg/bench> in the AnyEvent 2421Source code for this benchmark is found as F<eg/bench> in the AnyEvent
2047distribution. 2422distribution. It uses the L<AE> interface, which makes a real difference
2423for the EV and Perl backends only.
2048 2424
2049=head3 Explanation of the columns 2425=head3 Explanation of the columns
2050 2426
2051I<watcher> is the number of event watchers created/destroyed. Since 2427I<watcher> is the number of event watchers created/destroyed. Since
2052different event models feature vastly different performances, each event 2428different event models feature vastly different performances, each event
2073watcher. 2449watcher.
2074 2450
2075=head3 Results 2451=head3 Results
2076 2452
2077 name watchers bytes create invoke destroy comment 2453 name watchers bytes create invoke destroy comment
2078 EV/EV 400000 224 0.47 0.35 0.27 EV native interface 2454 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
2079 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 2455 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
2080 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 2456 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
2081 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 2457 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
2082 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 2458 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
2083 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 2459 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
2084 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll 2460 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
2085 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll 2461 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
2086 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 2462 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
2087 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 2463 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
2088 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 2464 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
2089 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 2465 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
2090 2466
2091=head3 Discussion 2467=head3 Discussion
2092 2468
2093The benchmark does I<not> measure scalability of the event loop very 2469The benchmark does I<not> measure scalability of the event loop very
2094well. For example, a select-based event loop (such as the pure perl one) 2470well. For example, a select-based event loop (such as the pure perl one)
2106benchmark machine, handling an event takes roughly 1600 CPU cycles with 2482benchmark machine, handling an event takes roughly 1600 CPU cycles with
2107EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU 2483EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU
2108cycles with POE. 2484cycles with POE.
2109 2485
2110C<EV> is the sole leader regarding speed and memory use, which are both 2486C<EV> is the sole leader regarding speed and memory use, which are both
2111maximal/minimal, respectively. Even when going through AnyEvent, it uses 2487maximal/minimal, respectively. When using the L<AE> API there is zero
2488overhead (when going through the AnyEvent API create is about 5-6 times
2489slower, with other times being equal, so still uses far less memory than
2112far less memory than any other event loop and is still faster than Event 2490any other event loop and is still faster than Event natively).
2113natively.
2114 2491
2115The pure perl implementation is hit in a few sweet spots (both the 2492The pure perl implementation is hit in a few sweet spots (both the
2116constant timeout and the use of a single fd hit optimisations in the perl 2493constant timeout and the use of a single fd hit optimisations in the perl
2117interpreter and the backend itself). Nevertheless this shows that it 2494interpreter and the backend itself). Nevertheless this shows that it
2118adds very little overhead in itself. Like any select-based backend its 2495adds very little overhead in itself. Like any select-based backend its
2166(even when used without AnyEvent), but most event loops have acceptable 2543(even when used without AnyEvent), but most event loops have acceptable
2167performance with or without AnyEvent. 2544performance with or without AnyEvent.
2168 2545
2169=item * The overhead AnyEvent adds is usually much smaller than the overhead of 2546=item * The overhead AnyEvent adds is usually much smaller than the overhead of
2170the actual event loop, only with extremely fast event loops such as EV 2547the actual event loop, only with extremely fast event loops such as EV
2171adds AnyEvent significant overhead. 2548does AnyEvent add significant overhead.
2172 2549
2173=item * You should avoid POE like the plague if you want performance or 2550=item * You should avoid POE like the plague if you want performance or
2174reasonable memory usage. 2551reasonable memory usage.
2175 2552
2176=back 2553=back
2192In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100 2569In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
2193(1%) are active. This mirrors the activity of large servers with many 2570(1%) are active. This mirrors the activity of large servers with many
2194connections, most of which are idle at any one point in time. 2571connections, most of which are idle at any one point in time.
2195 2572
2196Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 2573Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
2197distribution. 2574distribution. It uses the L<AE> interface, which makes a real difference
2575for the EV and Perl backends only.
2198 2576
2199=head3 Explanation of the columns 2577=head3 Explanation of the columns
2200 2578
2201I<sockets> is the number of sockets, and twice the number of "servers" (as 2579I<sockets> is the number of sockets, and twice the number of "servers" (as
2202each server has a read and write socket end). 2580each server has a read and write socket end).
2210a new one that moves the timeout into the future. 2588a new one that moves the timeout into the future.
2211 2589
2212=head3 Results 2590=head3 Results
2213 2591
2214 name sockets create request 2592 name sockets create request
2215 EV 20000 69.01 11.16 2593 EV 20000 62.66 7.99
2216 Perl 20000 73.32 35.87 2594 Perl 20000 68.32 32.64
2217 IOAsync 20000 157.00 98.14 epoll 2595 IOAsync 20000 174.06 101.15 epoll
2218 IOAsync 20000 159.31 616.06 poll 2596 IOAsync 20000 174.67 610.84 poll
2219 Event 20000 212.62 257.32 2597 Event 20000 202.69 242.91
2220 Glib 20000 651.16 1896.30 2598 Glib 20000 557.01 1689.52
2221 POE 20000 349.67 12317.24 uses POE::Loop::Event 2599 POE 20000 341.54 12086.32 uses POE::Loop::Event
2222 2600
2223=head3 Discussion 2601=head3 Discussion
2224 2602
2225This benchmark I<does> measure scalability and overall performance of the 2603This benchmark I<does> measure scalability and overall performance of the
2226particular event loop. 2604particular event loop.
2352As you can see, the AnyEvent + EV combination even beats the 2730As you can see, the AnyEvent + EV combination even beats the
2353hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl 2731hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
2354backend easily beats IO::Lambda and POE. 2732backend easily beats IO::Lambda and POE.
2355 2733
2356And even the 100% non-blocking version written using the high-level (and 2734And even the 100% non-blocking version written using the high-level (and
2357slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a 2735slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda
2358large margin, even though it does all of DNS, tcp-connect and socket I/O 2736higher level ("unoptimised") abstractions by a large margin, even though
2359in a non-blocking way. 2737it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
2360 2738
2361The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and 2739The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
2362F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are 2740F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2363part of the IO::lambda distribution and were used without any changes. 2741part of the IO::Lambda distribution and were used without any changes.
2364 2742
2365 2743
2366=head1 SIGNALS 2744=head1 SIGNALS
2367 2745
2368AnyEvent currently installs handlers for these signals: 2746AnyEvent currently installs handlers for these signals:
2405 unless defined $SIG{PIPE}; 2783 unless defined $SIG{PIPE};
2406 2784
2407=head1 RECOMMENDED/OPTIONAL MODULES 2785=head1 RECOMMENDED/OPTIONAL MODULES
2408 2786
2409One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and 2787One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2410it's built-in modules) are required to use it. 2788its built-in modules) are required to use it.
2411 2789
2412That does not mean that AnyEvent won't take advantage of some additional 2790That does not mean that AnyEvent won't take advantage of some additional
2413modules if they are installed. 2791modules if they are installed.
2414 2792
2415This section epxlains which additional modules will be used, and how they 2793This section explains which additional modules will be used, and how they
2416affect AnyEvent's operetion. 2794affect AnyEvent's operation.
2417 2795
2418=over 4 2796=over 4
2419 2797
2420=item L<Async::Interrupt> 2798=item L<Async::Interrupt>
2421 2799
2426catch the signals) with some delay (default is 10 seconds, look for 2804catch the signals) with some delay (default is 10 seconds, look for
2427C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2805C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2428 2806
2429If this module is available, then it will be used to implement signal 2807If this module is available, then it will be used to implement signal
2430catching, which means that signals will not be delayed, and the event loop 2808catching, which means that signals will not be delayed, and the event loop
2431will not be interrupted regularly, which is more efficient (And good for 2809will not be interrupted regularly, which is more efficient (and good for
2432battery life on laptops). 2810battery life on laptops).
2433 2811
2434This affects not just the pure-perl event loop, but also other event loops 2812This affects not just the pure-perl event loop, but also other event loops
2435that have no signal handling on their own (e.g. Glib, Tk, Qt). 2813that have no signal handling on their own (e.g. Glib, Tk, Qt).
2436 2814
2448automatic timer adjustments even when no monotonic clock is available, 2826automatic timer adjustments even when no monotonic clock is available,
2449can take avdantage of advanced kernel interfaces such as C<epoll> and 2827can take avdantage of advanced kernel interfaces such as C<epoll> and
2450C<kqueue>, and is the fastest backend I<by far>. You can even embed 2828C<kqueue>, and is the fastest backend I<by far>. You can even embed
2451L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>). 2829L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2452 2830
2831If you only use backends that rely on another event loop (e.g. C<Tk>),
2832then this module will do nothing for you.
2833
2453=item L<Guard> 2834=item L<Guard>
2454 2835
2455The guard module, when used, will be used to implement 2836The guard module, when used, will be used to implement
2456C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a 2837C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2457lot less memory), but otherwise doesn't affect guard operation much. It is 2838lot less memory), but otherwise doesn't affect guard operation much. It is
2458purely used for performance. 2839purely used for performance.
2459 2840
2460=item L<JSON> and L<JSON::XS> 2841=item L<JSON> and L<JSON::XS>
2461 2842
2462This module is required when you want to read or write JSON data via 2843One of these modules is required when you want to read or write JSON data
2463L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2844via L<AnyEvent::Handle>. L<JSON> is also written in pure-perl, but can take
2464advantage of the ultra-high-speed L<JSON::XS> module when it is installed. 2845advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2465
2466In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2467installed.
2468 2846
2469=item L<Net::SSLeay> 2847=item L<Net::SSLeay>
2470 2848
2471Implementing TLS/SSL in Perl is certainly interesting, but not very 2849Implementing TLS/SSL in Perl is certainly interesting, but not very
2472worthwhile: If this module is installed, then L<AnyEvent::Handle> (with 2850worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2473the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL. 2851the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2474 2852
2475=item L<Time::HiRes> 2853=item L<Time::HiRes>
2476 2854
2477This module is part of perl since release 5.008. It will be used when the 2855This module is part of perl since release 5.008. It will be used when the
2478chosen event library does not come with a timing source on it's own. The 2856chosen event library does not come with a timing source of its own. The
2479pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to 2857pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to
2480try to use a monotonic clock for timing stability. 2858try to use a monotonic clock for timing stability.
2481 2859
2482=back 2860=back
2483 2861
2484 2862
2485=head1 FORK 2863=head1 FORK
2486 2864
2487Most event libraries are not fork-safe. The ones who are usually are 2865Most event libraries are not fork-safe. The ones who are usually are
2488because they rely on inefficient but fork-safe C<select> or C<poll> 2866because they rely on inefficient but fork-safe C<select> or C<poll> calls
2489calls. Only L<EV> is fully fork-aware. 2867- higher performance APIs such as BSD's kqueue or the dreaded Linux epoll
2868are usually badly thought-out hacks that are incompatible with fork in
2869one way or another. Only L<EV> is fully fork-aware and ensures that you
2870continue event-processing in both parent and child (or both, if you know
2871what you are doing).
2872
2873This means that, in general, you cannot fork and do event processing in
2874the child if the event library was initialised before the fork (which
2875usually happens when the first AnyEvent watcher is created, or the library
2876is loaded).
2490 2877
2491If you have to fork, you must either do so I<before> creating your first 2878If you have to fork, you must either do so I<before> creating your first
2492watcher OR you must not use AnyEvent at all in the child OR you must do 2879watcher OR you must not use AnyEvent at all in the child OR you must do
2493something completely out of the scope of AnyEvent. 2880something completely out of the scope of AnyEvent.
2881
2882The problem of doing event processing in the parent I<and> the child
2883is much more complicated: even for backends that I<are> fork-aware or
2884fork-safe, their behaviour is not usually what you want: fork clones all
2885watchers, that means all timers, I/O watchers etc. are active in both
2886parent and child, which is almost never what you want. USing C<exec>
2887to start worker children from some kind of manage rprocess is usually
2888preferred, because it is much easier and cleaner, at the expense of having
2889to have another binary.
2494 2890
2495 2891
2496=head1 SECURITY CONSIDERATIONS 2892=head1 SECURITY CONSIDERATIONS
2497 2893
2498AnyEvent can be forced to load any event model via 2894AnyEvent can be forced to load any event model via
2528pronounced). 2924pronounced).
2529 2925
2530 2926
2531=head1 SEE ALSO 2927=head1 SEE ALSO
2532 2928
2533Utility functions: L<AnyEvent::Util>. 2929Tutorial/Introduction: L<AnyEvent::Intro>.
2534 2930
2535Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 2931FAQ: L<AnyEvent::FAQ>.
2536L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2932
2933Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2934(simply logging).
2935
2936Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2937L<AnyEvent::Debug> (interactive shell, watcher tracing).
2938
2939Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2940L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2941L<Qt>, L<POE>, L<FLTK>.
2537 2942
2538Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2943Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2539L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2944L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2540L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2945L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2541L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 2946L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
2947L<AnyEvent::Impl::FLTK>.
2542 2948
2543Non-blocking file handles, sockets, TCP clients and 2949Non-blocking handles, pipes, stream sockets, TCP clients and
2544servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2950servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2545 2951
2546Asynchronous DNS: L<AnyEvent::DNS>. 2952Asynchronous DNS: L<AnyEvent::DNS>.
2547 2953
2548Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, 2954Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
2549L<Coro::Event>,
2550 2955
2551Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>, 2956Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::IRC>,
2552L<AnyEvent::HTTP>. 2957L<AnyEvent::HTTP>.
2553 2958
2554 2959
2555=head1 AUTHOR 2960=head1 AUTHOR
2556 2961

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines