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.312 by root, Mon Feb 15 18:02:35 2010 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
425=head3 Signal Races, Delays and Workarounds 429=head3 Signal Races, Delays and Workarounds
426 430
427Many 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
428callbacks to signals in a generic way, which is a pity, as you cannot 432callbacks to signals in a generic way, which is a pity, as you cannot
429do race-free signal handling in perl, requiring C libraries for 433do race-free signal handling in perl, requiring C libraries for
430this. AnyEvent will try to do it's best, which means in some cases, 434this. AnyEvent will try to do its best, which means in some cases,
431signals will be delayed. The maximum time a signal might be delayed is 435signals will be delayed. The maximum time a signal might be delayed is
432specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This 436specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This
433variable can be changed only before the first signal watcher is created, 437variable can be changed only before the first signal watcher is created,
434and should be left alone otherwise. This variable determines how often 438and should be left alone otherwise. This variable determines how often
435AnyEvent polls for signals (in case a wake-up was missed). Higher values 439AnyEvent polls for signals (in case a wake-up was missed). Higher values
437saving. 441saving.
438 442
439All these problems can be avoided by installing the optional 443All these problems can be avoided by installing the optional
440L<Async::Interrupt> module, which works with most event loops. It will not 444L<Async::Interrupt> module, which works with most event loops. It will not
441work with inherently broken event loops such as L<Event> or L<Event::Lib> 445work with inherently broken event loops such as L<Event> or L<Event::Lib>
442(and not with L<POE> currently, as POE does it's own workaround with 446(and not with L<POE> currently, as POE does its own workaround with
443one-second latency). For those, you just have to suffer the delays. 447one-second latency). For those, you just have to suffer the delays.
444 448
445=head2 CHILD PROCESS WATCHERS 449=head2 CHILD PROCESS WATCHERS
446 450
447 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 451 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
448 452
449You 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.
450 454
451The 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,
452using 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
453croak). The watcher will be triggered only when the child process has 457croak). The watcher will be triggered only when the child process has
454finished and an exit status is available, not on any trace events 458finished and an exit status is available, not on any trace events
455(stopped/continued). 459(stopped/continued).
456 460
478thing 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
479watcher before you C<fork> the child (alternatively, you can call 483watcher before you C<fork> the child (alternatively, you can call
480C<AnyEvent::detect>). 484C<AnyEvent::detect>).
481 485
482As 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
483emulated 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
484mentioned in the description of signal watchers apply. 488problems mentioned in the description of signal watchers apply.
485 489
486Example: fork a process and wait for it 490Example: fork a process and wait for it
487 491
488 my $done = AnyEvent->condvar; 492 my $done = AnyEvent->condvar;
489 493
503 507
504=head2 IDLE WATCHERS 508=head2 IDLE WATCHERS
505 509
506 $w = AnyEvent->idle (cb => <callback>); 510 $w = AnyEvent->idle (cb => <callback>);
507 511
508Repeatedly invoke the callback after the process becomes idle, until 512This will repeatedly invoke the callback after the process becomes idle,
509either the watcher is destroyed or new events have been detected. 513until either the watcher is destroyed or new events have been detected.
510 514
511Idle watchers are useful when there is a need to do something, but it 515Idle watchers are useful when there is a need to do something, but it
512is not so important (or wise) to do it instantly. The callback will be 516is not so important (or wise) to do it instantly. The callback will be
513invoked only when there is "nothing better to do", which is usually 517invoked only when there is "nothing better to do", which is usually
514defined as "all outstanding events have been handled and no new events 518defined as "all outstanding events have been handled and no new events
553will actively watch for new events and call your callbacks. 557will actively watch for new events and call your callbacks.
554 558
555AnyEvent is slightly different: it expects somebody else to run the event 559AnyEvent is slightly different: it expects somebody else to run the event
556loop 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).
557 561
558The instrument to do that is called a "condition variable", so called 562The tool to do that is called a "condition variable", so called because
559because they represent a condition that must become true. 563they represent a condition that must become true.
560 564
561Now 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.
562 566
563Condition variables can be created by calling the C<< AnyEvent->condvar 567Condition variables can be created by calling the C<< AnyEvent->condvar
564>> method, usually without arguments. The only argument pair allowed is 568>> method, usually without arguments. The only argument pair allowed is
569After creation, the condition variable is "false" until it becomes "true" 573After creation, the condition variable is "false" until it becomes "true"
570by 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
571were 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<<
572->send >> method). 576->send >> method).
573 577
574Condition variables are similar to callbacks, except that you can 578Since condition variables are the most complex part of the AnyEvent API, here are
575optionally 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:
576in time where multiple outstanding events have been processed. And yet 580
577another way to call them is transactions - each condition variable can be 581=over 4
578used to represent a transaction, which finishes at some point and delivers 582
579a 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
580compute/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
581 601
582Condition variables are very useful to signal that something has finished, 602Condition variables are very useful to signal that something has finished,
583for example, if you write a module that does asynchronous http requests, 603for example, if you write a module that does asynchronous http requests,
584then a condition variable would be the ideal candidate to signal the 604then a condition variable would be the ideal candidate to signal the
585availability of results. The user can either act when the callback is 605availability of results. The user can either act when the callback is
598 618
599Condition variables are represented by hash refs in perl, and the keys 619Condition variables are represented by hash refs in perl, and the keys
600used 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
601easy (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
602AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call 622AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call
603it's C<new> method in your own C<new> method. 623its C<new> method in your own C<new> method.
604 624
605There are two "sides" to a condition variable - the "producer side" which 625There are two "sides" to a condition variable - the "producer side" which
606eventually calls C<< -> send >>, and the "consumer side", which waits 626eventually calls C<< -> send >>, and the "consumer side", which waits
607for the send to occur. 627for the send to occur.
608 628
609Example: wait for a timer. 629Example: wait for a timer.
610 630
611 # wait till the result is ready 631 # condition: "wait till the timer is fired"
612 my $result_ready = AnyEvent->condvar; 632 my $timer_fired = AnyEvent->condvar;
613 633
614 # do something such as adding a timer 634 # create the timer - we could wait for, say
615 # or socket watcher the calls $result_ready->send 635 # a handle becomign ready, or even an
616 # when the "result" is ready. 636 # AnyEvent::HTTP request to finish, but
617 # in this case, we simply use a timer: 637 # in this case, we simply use a timer:
618 my $w = AnyEvent->timer ( 638 my $w = AnyEvent->timer (
619 after => 1, 639 after => 1,
620 cb => sub { $result_ready->send }, 640 cb => sub { $timer_fired->send },
621 ); 641 );
622 642
623 # this "blocks" (while handling events) till the callback 643 # this "blocks" (while handling events) till the callback
624 # calls ->send 644 # calls ->send
625 $result_ready->recv; 645 $timer_fired->recv;
626 646
627Example: 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
628variables are also callable directly. 648variables are also callable directly.
629 649
630 my $done = AnyEvent->condvar; 650 my $done = AnyEvent->condvar;
673they 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
674C<send>. 694C<send>.
675 695
676=item $cv->croak ($error) 696=item $cv->croak ($error)
677 697
678Similar to send, but causes all call's to C<< ->recv >> to invoke 698Similar to send, but causes all calls to C<< ->recv >> to invoke
679C<Carp::croak> with the given error message/object/scalar. 699C<Carp::croak> with the given error message/object/scalar.
680 700
681This can be used to signal any errors to the condition variable 701This can be used to signal any errors to the condition variable
682user/consumer. Doing it this way instead of calling C<croak> directly 702user/consumer. Doing it this way instead of calling C<croak> directly
683delays the error detetcion, but has the overwhelmign advantage that it 703delays the error detection, but has the overwhelming advantage that it
684diagnoses 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
685deep in some event clalback without connection to the actual code causing 705deep in some event callback with no connection to the actual code causing
686the problem. 706the problem.
687 707
688=item $cv->begin ([group callback]) 708=item $cv->begin ([group callback])
689 709
690=item $cv->end 710=item $cv->end
728one 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
729sending. 749sending.
730 750
731The ping example mentioned above is slightly more complicated, as the 751The ping example mentioned above is slightly more complicated, as the
732there 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
733begung can potentially be zero: 753begun can potentially be zero:
734 754
735 my $cv = AnyEvent->condvar; 755 my $cv = AnyEvent->condvar;
736 756
737 my %result; 757 my %result;
738 $cv->begin (sub { shift->send (\%result) }); 758 $cv->begin (sub { shift->send (\%result) });
759to 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
760C<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
761doesn't execute once). 781doesn't execute once).
762 782
763This is the general pattern when you "fan out" into multiple (but 783This is the general pattern when you "fan out" into multiple (but
764potentially 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
765the 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
766subrequest you start, call C<begin> and for each subrequest you finish, 786subrequest you start, call C<begin> and for each subrequest you finish,
767call C<end>. 787call C<end>.
768 788
769=back 789=back
776=over 4 796=over 4
777 797
778=item $cv->recv 798=item $cv->recv
779 799
780Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak 800Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
781>> methods have been called on c<$cv>, while servicing other watchers 801>> methods have been called on C<$cv>, while servicing other watchers
782normally. 802normally.
783 803
784You 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
785will return immediately. 805will return immediately.
786 806
803caller 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
804condition variables with some kind of request results and supporting 824condition variables with some kind of request results and supporting
805callbacks so the caller knows that getting the result will not block, 825callbacks so the caller knows that getting the result will not block,
806while still supporting blocking waits if the caller so desires). 826while still supporting blocking waits if the caller so desires).
807 827
808You 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
809only calling C<< ->recv >> from within that callback (or at a later 829only calling C<< ->recv >> from within that callback (or at a later
810time). 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
811waits otherwise. 831waits otherwise.
812 832
813=item $bool = $cv->ready 833=item $bool = $cv->ready
818=item $cb = $cv->cb ($cb->($cv)) 838=item $cb = $cv->cb ($cb->($cv))
819 839
820This is a mutator function that returns the callback set and optionally 840This is a mutator function that returns the callback set and optionally
821replaces it before doing so. 841replaces it before doing so.
822 842
823The callback will be called when the condition becomes (or already was) 843The callback will be called when the condition becomes "true", i.e. when
824"true", i.e. when C<send> or C<croak> are called (or were called), with 844C<send> or C<croak> are called, with the only argument being the
825the only argument being the condition variable itself. Calling C<recv> 845condition variable itself. If the condition is already true, the
846callback is called immediately when it is set. Calling C<recv> inside
826inside the callback or at any later time is guaranteed not to block. 847the callback or at any later time is guaranteed not to block.
827 848
828=back 849=back
829 850
830=head1 SUPPORTED EVENT LOOPS/BACKENDS 851=head1 SUPPORTED EVENT LOOPS/BACKENDS
831 852
839use. If EV is not installed, then AnyEvent will fall back to its own 860use. If EV is not installed, then AnyEvent will fall back to its own
840pure-perl implementation, which is available everywhere as it comes with 861pure-perl implementation, which is available everywhere as it comes with
841AnyEvent itself. 862AnyEvent itself.
842 863
843 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 864 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
844 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 865 AnyEvent::Impl::Perl pure-perl AnyEvent::Loop, fast and portable.
845 866
846=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.
847 868
848These 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
849is 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
850them. This means that AnyEvent will automatically pick the right backend 871them. This means that AnyEvent will automatically pick the right backend
851when the main program loads an event module before anything starts to 872when the main program loads an event module before anything starts to
852create watchers. Nothing special needs to be done by the main program. 873create watchers. Nothing special needs to be done by the main program.
853 874
855 AnyEvent::Impl::Glib based on Glib, slow but very stable. 876 AnyEvent::Impl::Glib based on Glib, slow but very stable.
856 AnyEvent::Impl::Tk based on Tk, very broken. 877 AnyEvent::Impl::Tk based on Tk, very broken.
857 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
858 AnyEvent::Impl::POE based on POE, very slow, some limitations. 879 AnyEvent::Impl::POE based on POE, very slow, some limitations.
859 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).
860 884
861=item Backends with special needs. 885=item Backends with special needs.
862 886
863Qt requires the Qt::Application to be instantiated first, but will 887Qt requires the Qt::Application to be instantiated first, but will
864otherwise be picked up automatically. As long as the main program 888otherwise be picked up automatically. As long as the main program
865instantiates the application before any AnyEvent watchers are created, 889instantiates the application before any AnyEvent watchers are created,
866everything should just work. 890everything should just work.
867 891
868 AnyEvent::Impl::Qt based on Qt. 892 AnyEvent::Impl::Qt based on Qt.
869 893
870Support for IO::Async can only be partial, as it is too broken and
871architecturally limited to even support the AnyEvent API. It also
872is the only event loop that needs the loop to be set explicitly, so
873it can only be used by a main program knowing about AnyEvent. See
874L<AnyEvent::Impl::Async> for the gory details.
875
876 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
877
878=item Event loops that are indirectly supported via other backends. 894=item Event loops that are indirectly supported via other backends.
879 895
880Some event loops can be supported via other modules: 896Some event loops can be supported via other modules:
881 897
882There is no direct support for WxWidgets (L<Wx>) or L<Prima>. 898There is no direct support for WxWidgets (L<Wx>) or L<Prima>.
907Contains C<undef> until the first watcher is being created, before the 923Contains C<undef> until the first watcher is being created, before the
908backend has been autodetected. 924backend has been autodetected.
909 925
910Afterwards 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
911name 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
912of 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
913case 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
914will be C<urxvt::anyevent>). 930will be C<urxvt::anyevent>).
915 931
916=item AnyEvent::detect 932=item AnyEvent::detect
917 933
918Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 934Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
919if necessary. You should only call this function right before you would 935if necessary. You should only call this function right before you would
920have 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
921runtime, 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).
922 942
923If you need to do some initialisation before AnyEvent watchers are 943If you need to do some initialisation before AnyEvent watchers are
924created, use C<post_detect>. 944created, use C<post_detect>.
925 945
926=item $guard = AnyEvent::post_detect { BLOCK } 946=item $guard = AnyEvent::post_detect { BLOCK }
927 947
928Arranges 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
929autodetected (or immediately if this has already happened). 949autodetected (or immediately if that has already happened).
930 950
931The 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
932(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
933created, 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
934other initialisations - see the sources of L<AnyEvent::Strict> or 954other initialisations - see the sources of L<AnyEvent::Strict> or
943that automatically removes the callback again when it is destroyed (or 963that automatically removes the callback again when it is destroyed (or
944C<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
945a case where this is useful. 965a case where this is useful.
946 966
947Example: 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
948C<$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.
949 969
950 our WATCHER; 970 our WATCHER;
951 971
952 my $guard = AnyEvent::post_detect { 972 my $guard = AnyEvent::post_detect {
953 $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);
961 $WATCHER ||= $guard; 981 $WATCHER ||= $guard;
962 982
963=item @AnyEvent::post_detect 983=item @AnyEvent::post_detect
964 984
965If 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
966before or after loading AnyEvent), then they will called directly after 986before or after loading AnyEvent), then they will be called directly
967the event loop has been chosen. 987after the event loop has been chosen.
968 988
969You should check C<$AnyEvent::MODEL> before adding to this array, though: 989You should check C<$AnyEvent::MODEL> before adding to this array, though:
970if 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
971array will be ignored. 991array will be ignored.
972 992
989 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent 1009 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
990 # as soon as it is 1010 # as soon as it is
991 push @AnyEvent::post_detect, sub { require Coro::AnyEvent }; 1011 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
992 } 1012 }
993 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
994=back 1072=back
995 1073
996=head1 WHAT TO DO IN A MODULE 1074=head1 WHAT TO DO IN A MODULE
997 1075
998As 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
1008because 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
1009events is to stay interactive. 1087events is to stay interactive.
1010 1088
1011It 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
1012requests 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
1013called C<results> that returns the results, it should call C<< ->recv >> 1091called C<results> that returns the results, it may call C<< ->recv >>
1014freely, 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).
1015 1093
1016=head1 WHAT TO DO IN THE MAIN PROGRAM 1094=head1 WHAT TO DO IN THE MAIN PROGRAM
1017 1095
1018There 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
1019dictate which event model to use. 1097dictate which event model to use.
1020 1098
1021If 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
1022do 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
1023decide 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.
1024 1104
1025If 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
1026Gtk2 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
1027event module before loading AnyEvent or any module that uses it: generally 1107event module before loading AnyEvent or any module that uses it: generally
1028speaking, 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
1029modules might create watchers when they are loaded, and AnyEvent will 1109modules might create watchers when they are loaded, and AnyEvent will
1030decide 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
1031might chose the wrong one unless you load the correct one yourself. 1111might choose the wrong one unless you load the correct one yourself.
1032 1112
1033You can chose to use a pure-perl implementation by loading the 1113You can chose to use a pure-perl implementation by loading the
1034C<AnyEvent::Impl::Perl> module, which gives you similar behaviour 1114C<AnyEvent::Loop> module, which gives you similar behaviour
1035everywhere, but letting AnyEvent chose the model is generally better. 1115everywhere, but letting AnyEvent chose the model is generally better.
1036 1116
1037=head2 MAINLOOP EMULATION 1117=head2 MAINLOOP EMULATION
1038 1118
1039Sometimes (often for short test scripts, or even standalone programs who 1119Sometimes (often for short test scripts, or even standalone programs who
1052 1132
1053 1133
1054=head1 OTHER MODULES 1134=head1 OTHER MODULES
1055 1135
1056The following is a non-exhaustive list of additional modules that use 1136The following is a non-exhaustive list of additional modules that use
1057AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1137AnyEvent as a client and can therefore be mixed easily with other
1058modules 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
1059come 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 :)
1060 1143
1061=over 4 1144=over 4
1062 1145
1063=item L<AnyEvent::Util> 1146=item L<AnyEvent::Util>
1064 1147
1065Contains various utility functions that replace often-used but blocking 1148Contains various utility functions that replace often-used blocking
1066functions such as C<inet_aton> by event-/callback-based versions. 1149functions such as C<inet_aton> with event/callback-based versions.
1067 1150
1068=item L<AnyEvent::Socket> 1151=item L<AnyEvent::Socket>
1069 1152
1070Provides various utility functions for (internet protocol) sockets, 1153Provides various utility functions for (internet protocol) sockets,
1071addresses and name resolution. Also functions to create non-blocking tcp 1154addresses and name resolution. Also functions to create non-blocking tcp
1073 1156
1074=item L<AnyEvent::Handle> 1157=item L<AnyEvent::Handle>
1075 1158
1076Provide read and write buffers, manages watchers for reads and writes, 1159Provide read and write buffers, manages watchers for reads and writes,
1077supports 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
1078non-blocking SSL/TLS (via L<AnyEvent::TLS>. 1161non-blocking SSL/TLS (via L<AnyEvent::TLS>).
1079 1162
1080=item L<AnyEvent::DNS> 1163=item L<AnyEvent::DNS>
1081 1164
1082Provides rich asynchronous DNS resolver capabilities. 1165Provides rich asynchronous DNS resolver capabilities.
1083 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
1084=item L<AnyEvent::HTTP> 1173=item L<AnyEvent::AIO>
1085 1174
1086A 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
1087HTTP 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.
1088 1197
1089=item L<AnyEvent::HTTPD> 1198=item L<AnyEvent::HTTPD>
1090 1199
1091Provides a simple web application server framework. 1200A simple embedded webserver.
1092 1201
1093=item L<AnyEvent::FastPing> 1202=item L<AnyEvent::FastPing>
1094 1203
1095The fastest ping in the west. 1204The fastest ping in the west.
1096 1205
1097=item L<AnyEvent::DBI>
1098
1099Executes L<DBI> requests asynchronously in a proxy process.
1100
1101=item L<AnyEvent::AIO>
1102
1103Truly asynchronous I/O, should be in the toolbox of every event
1104programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
1105together.
1106
1107=item L<AnyEvent::BDB>
1108
1109Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
1110L<BDB> and AnyEvent together.
1111
1112=item L<AnyEvent::GPSD>
1113
1114A non-blocking interface to gpsd, a daemon delivering GPS information.
1115
1116=item L<AnyEvent::IRC>
1117
1118AnyEvent based IRC client module family (replacing the older Net::IRC3).
1119
1120=item L<AnyEvent::XMPP>
1121
1122AnyEvent based XMPP (Jabber protocol) module family (replacing the older
1123Net::XMPP2>.
1124
1125=item L<AnyEvent::IGS>
1126
1127A non-blocking interface to the Internet Go Server protocol (used by
1128L<App::IGS>).
1129
1130=item L<Net::FCP>
1131
1132AnyEvent-based implementation of the Freenet Client Protocol, birthplace
1133of AnyEvent.
1134
1135=item L<Event::ExecFlow>
1136
1137High level API for event-based execution flow control.
1138
1139=item L<Coro> 1206=item L<Coro>
1140 1207
1141Has 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 };
1142 1221
1143=back 1222=back
1144 1223
1145=cut 1224=cut
1146 1225
1147package AnyEvent; 1226package AnyEvent;
1148 1227
1149# basically a tuned-down version of common::sense 1228# basically a tuned-down version of common::sense
1150sub common_sense { 1229sub common_sense {
1151 # from common:.sense 1.0 1230 # from common:.sense 3.4
1152 ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x00"; 1231 ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "\x3c\x3f\x33\x00\x0f\xf0\x0f\xc0\xf0\xfc\x33\x00";
1153 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl) 1232 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1154 $^H |= 0x00000600; 1233 $^H |= 0x00000600;
1155} 1234}
1156 1235
1157BEGIN { AnyEvent::common_sense } 1236BEGIN { AnyEvent::common_sense }
1158 1237
1159use Carp (); 1238use Carp ();
1160 1239
1161our $VERSION = '5.24'; 1240our $VERSION = '6.02';
1162our $MODEL; 1241our $MODEL;
1163 1242
1164our $AUTOLOAD;
1165our @ISA; 1243our @ISA;
1166 1244
1167our @REGISTRY; 1245our @REGISTRY;
1168 1246
1169our $VERBOSE; 1247our $VERBOSE;
1170 1248
1171BEGIN { 1249BEGIN {
1172 eval "sub CYGWIN(){" . (($^O =~ /cygwin/i) *1) . "}"; 1250 require "AnyEvent/constants.pl";
1173 eval "sub WIN32 (){" . (($^O =~ /mswin32/i)*1) . "}"; 1251
1174 eval "sub TAINT (){" . (${^TAINT} *1) . "}"; 1252 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1175 1253
1176 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1254 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1177 if ${^TAINT}; 1255 if ${^TAINT};
1178 1256
1179 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1257 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1258 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1180 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;
1181} 1266}
1182 1267
1183our $MAX_SIGNAL_LATENCY = 10; 1268our $MAX_SIGNAL_LATENCY = 10;
1184 1269
1185our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1270our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1189 $PROTOCOL{$_} = ++$idx 1274 $PROTOCOL{$_} = ++$idx
1190 for reverse split /\s*,\s*/, 1275 for reverse split /\s*,\s*/,
1191 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1276 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1192} 1277}
1193 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
1194my @models = ( 1328our @models = (
1195 [EV:: => AnyEvent::Impl::EV:: , 1], 1329 [EV:: => AnyEvent::Impl::EV:: , 1],
1196 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1], 1330 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
1197 # everything below here will not (normally) be autoprobed 1331 # everything below here will not (normally) be autoprobed
1198 # as the pureperl backend should work everywhere 1332 # as the pure perl backend should work everywhere
1199 # and is usually faster 1333 # and is usually faster
1200 [Event:: => AnyEvent::Impl::Event::, 1], 1334 [Event:: => AnyEvent::Impl::Event::, 1],
1201 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1335 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1202 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1336 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1203 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package 1337 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1204 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1338 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1205 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1339 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1206 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1340 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1207 [Wx:: => AnyEvent::Impl::POE::], 1341 [Wx:: => AnyEvent::Impl::POE::],
1208 [Prima:: => AnyEvent::Impl::POE::], 1342 [Prima:: => AnyEvent::Impl::POE::],
1209 # IO::Async is just too broken - we would need workarounds for its 1343 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1210 # byzantine signal and broken child handling, among others. 1344 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1211 # IO::Async is rather hard to detect, as it doesn't have any 1345 [FLTK:: => AnyEvent::Impl::FLTK::],
1212 # obvious default class.
1213 [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1214 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1215 [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1216 [AnyEvent::Impl::IOAsync:: => AnyEvent::Impl::IOAsync::], # requires special main program
1217); 1346);
1218 1347
1219our %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.
1220 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);
1221
1222our @post_detect;
1223
1224sub post_detect(&) {
1225 my ($cb) = @_;
1226
1227 if ($MODEL) {
1228 $cb->();
1229
1230 undef
1231 } else {
1232 push @post_detect, $cb;
1233
1234 defined wantarray
1235 ? bless \$cb, "AnyEvent::Util::postdetect"
1236 : ()
1237 }
1238}
1239
1240sub AnyEvent::Util::postdetect::DESTROY {
1241 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1242}
1243 1372
1244sub detect() { 1373sub detect() {
1374 return $MODEL if $MODEL; # some programs keep references to detect
1375
1376 local $!; # for good measure
1377 local $SIG{__DIE__}; # we use eval
1378
1245 # free some memory 1379 # free some memory
1246 *detect = sub () { $MODEL }; 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;
1247 1388
1248 local $!; # for good measure
1249 local $SIG{__DIE__};
1250
1251 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1389 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1252 my $model = "AnyEvent::Impl::$1"; 1390 my $model = $1;
1391 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1253 if (eval "require $model") { 1392 if (eval "require $model") {
1393 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1254 $MODEL = $model; 1394 $MODEL = $model;
1255 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1256 } else { 1395 } else {
1257 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1396 AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1258 } 1397 }
1259 } 1398 }
1260 1399
1261 # check for already loaded models 1400 # check for already loaded models
1262 unless ($MODEL) { 1401 unless ($MODEL) {
1263 for (@REGISTRY, @models) { 1402 for (@REGISTRY, @models) {
1264 my ($package, $model) = @$_; 1403 my ($package, $model) = @$_;
1265 if (${"$package\::VERSION"} > 0) { 1404 if (${"$package\::VERSION"} > 0) {
1266 if (eval "require $model") { 1405 if (eval "require $model") {
1406 AnyEvent::log 7 => "autodetected model '$model', using it.";
1267 $MODEL = $model; 1407 $MODEL = $model;
1268 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1269 last; 1408 last;
1270 } 1409 }
1271 } 1410 }
1272 } 1411 }
1273 1412
1279 $autoload 1418 $autoload
1280 and eval "require $package" 1419 and eval "require $package"
1281 and ${"$package\::VERSION"} > 0 1420 and ${"$package\::VERSION"} > 0
1282 and eval "require $model" 1421 and eval "require $model"
1283 ) { 1422 ) {
1423 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1284 $MODEL = $model; 1424 $MODEL = $model;
1285 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1286 last; 1425 last;
1287 } 1426 }
1288 } 1427 }
1289 1428
1290 $MODEL 1429 $MODEL
1291 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?";
1292 } 1431 }
1293 } 1432 }
1294 1433
1295 @models = (); # free probe data 1434 # free memory only needed for probing
1435 undef @models;
1436 undef @REGISTRY;
1296 1437
1297 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1438 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1298 unshift @ISA, $MODEL;
1299 1439
1300 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT}; 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
1301 1473
1302 (shift @post_detect)->() while @post_detect; 1474 (shift @post_detect)->() while @post_detect;
1475 undef @post_detect;
1476
1477 *post_detect = sub(&) {
1478 shift->();
1479
1480 undef
1481 };
1303 1482
1304 $MODEL 1483 $MODEL
1305} 1484}
1306 1485
1307sub AUTOLOAD { 1486for my $name (@methods) {
1308 (my $func = $AUTOLOAD) =~ s/.*://; 1487 *$name = sub {
1309
1310 $method{$func}
1311 or Carp::croak "$func: not a valid AnyEvent class method";
1312
1313 detect; 1488 detect;
1314 1489 # we use goto because
1315 my $class = shift; 1490 # a) it makes the thunk more transparent
1316 $class->$func (@_); 1491 # b) it allows us to delete the thunk later
1492 goto &{ UNIVERSAL::can AnyEvent => "SUPER::$name" }
1493 };
1317} 1494}
1318 1495
1319# 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
1320# to support binding more than one watcher per filehandle (they usually 1497# to support binding more than one watcher per filehandle (they usually
1321# 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).
1335 1512
1336=head1 SIMPLIFIED AE API 1513=head1 SIMPLIFIED AE API
1337 1514
1338Starting with version 5.0, AnyEvent officially supports a second, much 1515Starting with version 5.0, AnyEvent officially supports a second, much
1339simpler, API that is designed to reduce the calling, typing and memory 1516simpler, API that is designed to reduce the calling, typing and memory
1340overhead. 1517overhead by using function call syntax and a fixed number of parameters.
1341 1518
1342See the L<AE> manpage for details. 1519See the L<AE> manpage for details.
1343 1520
1344=cut 1521=cut
1345 1522
1346package AE; 1523package AE;
1347 1524
1348our $VERSION = $AnyEvent::VERSION; 1525our $VERSION = $AnyEvent::VERSION;
1349 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
1350sub io($$$) { 1532 sub io($$$) {
1351 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2]) 1533 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1352} 1534 }
1353 1535
1354sub timer($$$) { 1536 sub timer($$$) {
1355 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]) 1537 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1356} 1538 }
1357 1539
1358sub signal($$) { 1540 sub signal($$) {
1359 AnyEvent->signal (signal => $_[0], cb => $_[1]) 1541 AnyEvent->signal (signal => $_[0], cb => $_[1])
1360} 1542 }
1361 1543
1362sub child($$) { 1544 sub child($$) {
1363 AnyEvent->child (pid => $_[0], cb => $_[1]) 1545 AnyEvent->child (pid => $_[0], cb => $_[1])
1364} 1546 }
1365 1547
1366sub idle($) { 1548 sub idle($) {
1367 AnyEvent->idle (cb => $_[0]) 1549 AnyEvent->idle (cb => $_[0]);
1368} 1550 }
1369 1551
1370sub cv(;&) { 1552 sub cv(;&) {
1371 AnyEvent->condvar (@_ ? (cb => $_[0]) : ()) 1553 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1372} 1554 }
1373 1555
1374sub now() { 1556 sub now() {
1375 AnyEvent->now 1557 AnyEvent->now
1376} 1558 }
1377 1559
1378sub now_update() { 1560 sub now_update() {
1379 AnyEvent->now_update 1561 AnyEvent->now_update
1380} 1562 }
1381 1563
1382sub time() { 1564 sub time() {
1383 AnyEvent->time 1565 AnyEvent->time
1566 }
1567
1568 *postpone = \&AnyEvent::postpone;
1569 *log = \&AnyEvent::log;
1570 };
1571 die if $@;
1384} 1572}
1573
1574BEGIN { _reset }
1385 1575
1386package AnyEvent::Base; 1576package AnyEvent::Base;
1387 1577
1388# default implementations for many methods 1578# default implementations for many methods
1389 1579
1390sub _time() { 1580sub time {
1391 eval q{ # poor man's autoloading 1581 eval q{ # poor man's autoloading {}
1392 # probe for availability of Time::HiRes 1582 # probe for availability of Time::HiRes
1393 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1583 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1394 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1584 *time = sub { Time::HiRes::time () };
1395 *_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.";
1396 # if (eval "use POSIX (); (POSIX::times())... 1588 # if (eval "use POSIX (); (POSIX::times())...
1397 } else { 1589 } else {
1590 *time = sub { CORE::time };
1591 *AE::time = sub (){ CORE::time };
1592 *now = \&time;
1398 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!";
1399 *_time = sub (){ time }; # epic fail
1400 } 1594 }
1401 }; 1595 };
1402 die if $@; 1596 die if $@;
1403 1597
1404 &_time 1598 &time
1405} 1599}
1406 1600
1407sub time { _time } 1601*now = \&time;
1408sub now { _time }
1409sub now_update { } 1602sub now_update { }
1410 1603
1604sub _poll {
1605 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1606}
1607
1411# default implementation for ->condvar 1608# default implementation for ->condvar
1609# in fact, the default should not be overwritten
1412 1610
1413sub condvar { 1611sub condvar {
1612 eval q{ # poor man's autoloading {}
1613 *condvar = sub {
1414 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
1415} 1624}
1416 1625
1417# default implementation for ->signal 1626# default implementation for ->signal
1418 1627
1419our $HAVE_ASYNC_INTERRUPT; 1628our $HAVE_ASYNC_INTERRUPT;
1449 undef $SIG_TW 1658 undef $SIG_TW
1450 unless --$SIG_COUNT; 1659 unless --$SIG_COUNT;
1451} 1660}
1452 1661
1453our $_sig_name_init; $_sig_name_init = sub { 1662our $_sig_name_init; $_sig_name_init = sub {
1454 eval q{ # poor man's autoloading 1663 eval q{ # poor man's autoloading {}
1455 undef $_sig_name_init; 1664 undef $_sig_name_init;
1456 1665
1457 if (_have_async_interrupt) { 1666 if (_have_async_interrupt) {
1458 *sig2num = \&Async::Interrupt::sig2num; 1667 *sig2num = \&Async::Interrupt::sig2num;
1459 *sig2name = \&Async::Interrupt::sig2name; 1668 *sig2name = \&Async::Interrupt::sig2name;
1483 1692
1484sub signal { 1693sub signal {
1485 eval q{ # poor man's autoloading {} 1694 eval q{ # poor man's autoloading {}
1486 # probe for availability of Async::Interrupt 1695 # probe for availability of Async::Interrupt
1487 if (_have_async_interrupt) { 1696 if (_have_async_interrupt) {
1488 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.";
1489 1698
1490 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1699 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1491 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1700 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1492 1701
1493 } else { 1702 } else {
1494 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.";
1495
1496 require Fcntl;
1497 1704
1498 if (AnyEvent::WIN32) { 1705 if (AnyEvent::WIN32) {
1499 require AnyEvent::Util; 1706 require AnyEvent::Util;
1500 1707
1501 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1708 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1502 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R; 1709 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
1503 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
1504 } else { 1711 } else {
1505 pipe $SIGPIPE_R, $SIGPIPE_W; 1712 pipe $SIGPIPE_R, $SIGPIPE_W;
1506 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;
1507 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
1508 1715
1509 # 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...
1510 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC; 1717 fcntl $SIGPIPE_R, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1511 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC; 1718 fcntl $SIGPIPE_W, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1512 } 1719 }
1513 1720
1514 $SIGPIPE_R 1721 $SIGPIPE_R
1515 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";
1516 1723
1517 $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec; 1724 $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;
1518 } 1725 }
1519 1726
1520 *signal = sub { 1727 *signal = $HAVE_ASYNC_INTERRUPT
1728 ? sub {
1521 my (undef, %arg) = @_; 1729 my (undef, %arg) = @_;
1522 1730
1523 my $signal = uc $arg{signal}
1524 or Carp::croak "required option 'signal' is missing";
1525
1526 if ($HAVE_ASYNC_INTERRUPT) {
1527 # async::interrupt 1731 # async::interrupt
1528
1529 $signal = sig2num $signal; 1732 my $signal = sig2num $arg{signal};
1530 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1733 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1531 1734
1532 $SIG_ASY{$signal} ||= new Async::Interrupt 1735 $SIG_ASY{$signal} ||= new Async::Interrupt
1533 cb => sub { undef $SIG_EV{$signal} }, 1736 cb => sub { undef $SIG_EV{$signal} },
1534 signal => $signal, 1737 signal => $signal,
1535 pipe => [$SIGPIPE_R->filenos], 1738 pipe => [$SIGPIPE_R->filenos],
1536 pipe_autodrain => 0, 1739 pipe_autodrain => 0,
1537 ; 1740 ;
1538 1741
1539 } else { 1742 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1743 }
1744 : sub {
1745 my (undef, %arg) = @_;
1746
1540 # pure perl 1747 # pure perl
1541
1542 # AE::Util has been loaded in signal
1543 $signal = sig2name $signal; 1748 my $signal = sig2name $arg{signal};
1544 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1749 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1545 1750
1546 $SIG{$signal} ||= sub { 1751 $SIG{$signal} ||= sub {
1547 local $!; 1752 local $!;
1548 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1753 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1549 undef $SIG_EV{$signal}; 1754 undef $SIG_EV{$signal};
1550 }; 1755 };
1551 1756
1552 # can't do signal processing without introducing races in pure perl, 1757 # can't do signal processing without introducing races in pure perl,
1553 # so limit the signal latency. 1758 # so limit the signal latency.
1554 _sig_add; 1759 _sig_add;
1555 }
1556 1760
1557 bless [$signal, $arg{cb}], "AnyEvent::Base::signal" 1761 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1762 }
1558 }; 1763 ;
1559 1764
1560 *AnyEvent::Base::signal::DESTROY = sub { 1765 *AnyEvent::Base::signal::DESTROY = sub {
1561 my ($signal, $cb) = @{$_[0]}; 1766 my ($signal, $cb) = @{$_[0]};
1562 1767
1563 _sig_del; 1768 _sig_del;
1579 : sysread $SIGPIPE_R, (my $dummy), 9; 1784 : sysread $SIGPIPE_R, (my $dummy), 9;
1580 1785
1581 while (%SIG_EV) { 1786 while (%SIG_EV) {
1582 for (keys %SIG_EV) { 1787 for (keys %SIG_EV) {
1583 delete $SIG_EV{$_}; 1788 delete $SIG_EV{$_};
1584 $_->() for values %{ $SIG_CB{$_} || {} }; 1789 &$_ for values %{ $SIG_CB{$_} || {} };
1585 } 1790 }
1586 } 1791 }
1587 }; 1792 };
1588 }; 1793 };
1589 die if $@; 1794 die if $@;
1594# default implementation for ->child 1799# default implementation for ->child
1595 1800
1596our %PID_CB; 1801our %PID_CB;
1597our $CHLD_W; 1802our $CHLD_W;
1598our $CHLD_DELAY_W; 1803our $CHLD_DELAY_W;
1599our $WNOHANG;
1600 1804
1601# used by many Impl's 1805# used by many Impl's
1602sub _emit_childstatus($$) { 1806sub _emit_childstatus($$) {
1603 my (undef, $rpid, $rstatus) = @_; 1807 my (undef, $rpid, $rstatus) = @_;
1604 1808
1611 eval q{ # poor man's autoloading {} 1815 eval q{ # poor man's autoloading {}
1612 *_sigchld = sub { 1816 *_sigchld = sub {
1613 my $pid; 1817 my $pid;
1614 1818
1615 AnyEvent->_emit_childstatus ($pid, $?) 1819 AnyEvent->_emit_childstatus ($pid, $?)
1616 while ($pid = waitpid -1, $WNOHANG) > 0; 1820 while ($pid = waitpid -1, WNOHANG) > 0;
1617 }; 1821 };
1618 1822
1619 *child = sub { 1823 *child = sub {
1620 my (undef, %arg) = @_; 1824 my (undef, %arg) = @_;
1621 1825
1622 defined (my $pid = $arg{pid} + 0) 1826 my $pid = $arg{pid};
1623 or Carp::croak "required option 'pid' is missing"; 1827 my $cb = $arg{cb};
1624 1828
1625 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1829 $PID_CB{$pid}{$cb+0} = $cb;
1626
1627 # WNOHANG is almost cetrainly 1 everywhere
1628 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1629 ? 1
1630 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1631 1830
1632 unless ($CHLD_W) { 1831 unless ($CHLD_W) {
1633 $CHLD_W = AE::signal CHLD => \&_sigchld; 1832 $CHLD_W = AE::signal CHLD => \&_sigchld;
1634 # 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
1635 &_sigchld; 1834 &_sigchld;
1636 } 1835 }
1637 1836
1638 bless [$pid, $arg{cb}], "AnyEvent::Base::child" 1837 bless [$pid, $cb+0], "AnyEvent::Base::child"
1639 }; 1838 };
1640 1839
1641 *AnyEvent::Base::child::DESTROY = sub { 1840 *AnyEvent::Base::child::DESTROY = sub {
1642 my ($pid, $cb) = @{$_[0]}; 1841 my ($pid, $icb) = @{$_[0]};
1643 1842
1644 delete $PID_CB{$pid}{$cb}; 1843 delete $PID_CB{$pid}{$icb};
1645 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1844 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1646 1845
1647 undef $CHLD_W unless keys %PID_CB; 1846 undef $CHLD_W unless keys %PID_CB;
1648 }; 1847 };
1649 }; 1848 };
1662 1861
1663 my ($cb, $w, $rcb) = $arg{cb}; 1862 my ($cb, $w, $rcb) = $arg{cb};
1664 1863
1665 $rcb = sub { 1864 $rcb = sub {
1666 if ($cb) { 1865 if ($cb) {
1667 $w = _time; 1866 $w = AE::time;
1668 &$cb; 1867 &$cb;
1669 $w = _time - $w; 1868 $w = AE::time - $w;
1670 1869
1671 # 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,
1672 # within some limits 1871 # within some limits
1673 $w = 0.0001 if $w < 0.0001; 1872 $w = 0.0001 if $w < 0.0001;
1674 $w = 5 if $w > 5; 1873 $w = 5 if $w > 5;
1697 1896
1698package AnyEvent::CondVar; 1897package AnyEvent::CondVar;
1699 1898
1700our @ISA = AnyEvent::CondVar::Base::; 1899our @ISA = AnyEvent::CondVar::Base::;
1701 1900
1901# only to be used for subclassing
1902sub new {
1903 my $class = shift;
1904 bless AnyEvent->condvar (@_), $class
1905}
1906
1702package AnyEvent::CondVar::Base; 1907package AnyEvent::CondVar::Base;
1703 1908
1704#use overload 1909#use overload
1705# '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1910# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1706# fallback => 1; 1911# fallback => 1;
1715 1920
1716sub _send { 1921sub _send {
1717 # nop 1922 # nop
1718} 1923}
1719 1924
1925sub _wait {
1926 AnyEvent->_poll until $_[0]{_ae_sent};
1927}
1928
1720sub send { 1929sub send {
1721 my $cv = shift; 1930 my $cv = shift;
1722 $cv->{_ae_sent} = [@_]; 1931 $cv->{_ae_sent} = [@_];
1723 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb}; 1932 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
1724 $cv->_send; 1933 $cv->_send;
1731 1940
1732sub ready { 1941sub ready {
1733 $_[0]{_ae_sent} 1942 $_[0]{_ae_sent}
1734} 1943}
1735 1944
1736sub _wait {
1737 $WAITING
1738 and !$_[0]{_ae_sent}
1739 and Carp::croak "AnyEvent::CondVar: recursive blocking wait detected";
1740
1741 local $WAITING = 1;
1742 AnyEvent->one_event while !$_[0]{_ae_sent};
1743}
1744
1745sub 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;
1746 $_[0]->_wait; 1951 $_[0]->_wait;
1952 }
1747 1953
1748 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak}; 1954 $_[0]{_ae_croak}
1749 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]
1750} 1960}
1751 1961
1752sub cb { 1962sub cb {
1753 my $cv = shift; 1963 my $cv = shift;
1754 1964
1770 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } }; 1980 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
1771} 1981}
1772 1982
1773# undocumented/compatibility with pre-3.4 1983# undocumented/compatibility with pre-3.4
1774*broadcast = \&send; 1984*broadcast = \&send;
1775*wait = \&_wait; 1985*wait = \&recv;
1776 1986
1777=head1 ERROR AND EXCEPTION HANDLING 1987=head1 ERROR AND EXCEPTION HANDLING
1778 1988
1779In 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
1780caller 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
1792$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2002$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1793so on. 2003so on.
1794 2004
1795=head1 ENVIRONMENT VARIABLES 2005=head1 ENVIRONMENT VARIABLES
1796 2006
1797The following environment variables are used by this module or its 2007AnyEvent supports a number of environment variables that tune the
1798submodules. 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.
1799 2013
1800Note that AnyEvent will remove I<all> environment variables starting with 2014All the environment variables documented here start with
1801C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2015C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1802enabled. 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:
1803 2044
1804=over 4 2045=over 4
1805 2046
1806=item C<PERL_ANYEVENT_VERBOSE> 2047=item C<PERL_ANYEVENT_VERBOSE>
1807 2048
1808By default, AnyEvent will be completely silent except in fatal 2049By default, AnyEvent will only log messages with loglevel C<3>
1809conditions. 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
1810talkative. 2052less) talkative.
1811 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
1812When 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
1813conditions, such as not being able to load the event model specified by 2062unexpected conditions, such as not being able to load the event model
1814C<PERL_ANYEVENT_MODEL>. 2063specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2064exception - this is the minimum recommended level.
1815 2065
1816When 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
1817model it chooses. 2067chooses.
1818 2068
1819When 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
1820which 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.
1821 2089
1822=item C<PERL_ANYEVENT_STRICT> 2090=item C<PERL_ANYEVENT_STRICT>
1823 2091
1824AnyEvent does not do much argument checking by default, as thorough 2092AnyEvent does not do much argument checking by default, as thorough
1825argument checking is very costly. Setting this variable to a true value 2093argument checking is very costly. Setting this variable to a true value
1827check 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,
1828it will croak. 2096it will croak.
1829 2097
1830In other words, enables "strict" mode. 2098In other words, enables "strict" mode.
1831 2099
1832Unlike 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>
1833>>, it is definitely recommended to keep it off in production. Keeping 2101>>, it is definitely recommended to keep it off in production. Keeping
1834C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2102C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1835can be very useful, however. 2103can be very useful, however.
1836 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
1837=item C<PERL_ANYEVENT_MODEL> 2127=item C<PERL_ANYEVENT_MODEL>
1838 2128
1839This 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
1840auto detection and -probing kicks in. It must be a string consisting 2130auto detection and -probing kicks in.
1841entirely 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
1842and 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
1843used 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
1844auto detection and -probing. 2136auto detection and -probing.
1845 2137
1846This 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).
1847 2141
1848For 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
1849could start your program like this: 2143could start your program like this:
1850 2144
1851 PERL_ANYEVENT_MODEL=Perl perl ... 2145 PERL_ANYEVENT_MODEL=Perl perl ...
1852 2146
1853=item C<PERL_ANYEVENT_PROTOCOLS> 2147=item C<PERL_ANYEVENT_PROTOCOLS>
1869but 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>
1870- only support IPv4, never try to resolve or contact IPv6 2164- only support IPv4, never try to resolve or contact IPv6
1871addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2165addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1872IPv6, but prefer IPv6 over IPv4. 2166IPv6, but prefer IPv6 over IPv4.
1873 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
1874=item C<PERL_ANYEVENT_EDNS0> 2174=item C<PERL_ANYEVENT_EDNS0>
1875 2175
1876Used 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
1877for DNS. This extension is generally useful to reduce DNS traffic, but 2177DNS. This extension is generally useful to reduce DNS traffic, especially
1878some (broken) firewalls drop such DNS packets, which is why it is off by 2178when DNSSEC is involved, but some (broken) firewalls drop such DNS
1879default. 2179packets, which is why it is off by default.
1880 2180
1881Setting 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
1882EDNS0 in its DNS requests. 2182EDNS0 in its DNS requests.
1883 2183
1884=item C<PERL_ANYEVENT_MAX_FORKS> 2184=item C<PERL_ANYEVENT_MAX_FORKS>
1892resolver - this is the maximum number of parallel DNS requests that are 2192resolver - this is the maximum number of parallel DNS requests that are
1893sent to the DNS server. 2193sent to the DNS server.
1894 2194
1895=item C<PERL_ANYEVENT_RESOLV_CONF> 2195=item C<PERL_ANYEVENT_RESOLV_CONF>
1896 2196
1897The 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
1898configuration) in the default resolver. When set to the empty string, no 2198F</etc/resolv.conf> (or the OS-specific configuration) in the default
1899default config will be used. 2199resolver, or the empty string to select the default configuration.
1900 2200
1901=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2201=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1902 2202
1903When neither C<ca_file> nor C<ca_path> was specified during 2203When neither C<ca_file> nor C<ca_path> was specified during
1904L<AnyEvent::TLS> context creation, and either of these environment 2204L<AnyEvent::TLS> context creation, and either of these environment
1905variables exist, they will be used to specify CA certificate locations 2205variables are nonempty, they will be used to specify CA certificate
1906instead of a system-dependent default. 2206locations instead of a system-dependent default.
1907 2207
1908=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>
1909 2209
1910When 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
1911loaded. Mostly good for testing AnyEvent itself. 2211loaded. Mostly good for testing AnyEvent itself.
2059 2359
2060The 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)
2061that occurred during request processing. The C<result> method detects 2361that occurred during request processing. The C<result> method detects
2062whether an exception as thrown (it is stored inside the $txn object) 2362whether an exception as thrown (it is stored inside the $txn object)
2063and just throws the exception, which means connection errors and other 2363and just throws the exception, which means connection errors and other
2064problems 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
2065random callback. 2365random callback.
2066 2366
2067All of this enables the following usage styles: 2367All of this enables the following usage styles:
2068 2368
20691. Blocking: 23691. Blocking:
2243(even when used without AnyEvent), but most event loops have acceptable 2543(even when used without AnyEvent), but most event loops have acceptable
2244performance with or without AnyEvent. 2544performance with or without AnyEvent.
2245 2545
2246=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
2247the 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
2248adds AnyEvent significant overhead. 2548does AnyEvent add significant overhead.
2249 2549
2250=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
2251reasonable memory usage. 2551reasonable memory usage.
2252 2552
2253=back 2553=back
2483 unless defined $SIG{PIPE}; 2783 unless defined $SIG{PIPE};
2484 2784
2485=head1 RECOMMENDED/OPTIONAL MODULES 2785=head1 RECOMMENDED/OPTIONAL MODULES
2486 2786
2487One 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
2488it's built-in modules) are required to use it. 2788its built-in modules) are required to use it.
2489 2789
2490That 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
2491modules if they are installed. 2791modules if they are installed.
2492 2792
2493This section explains which additional modules will be used, and how they 2793This section explains which additional modules will be used, and how they
2526automatic timer adjustments even when no monotonic clock is available, 2826automatic timer adjustments even when no monotonic clock is available,
2527can take avdantage of advanced kernel interfaces such as C<epoll> and 2827can take avdantage of advanced kernel interfaces such as C<epoll> and
2528C<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
2529L<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>).
2530 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
2531=item L<Guard> 2834=item L<Guard>
2532 2835
2533The guard module, when used, will be used to implement 2836The guard module, when used, will be used to implement
2534C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a 2837C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2535lot 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
2536purely used for performance. 2839purely used for performance.
2537 2840
2538=item L<JSON> and L<JSON::XS> 2841=item L<JSON> and L<JSON::XS>
2539 2842
2540One of these modules is required when you want to read or write JSON data 2843One of these modules is required when you want to read or write JSON data
2541via L<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
2542advantage 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.
2543
2544In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2545installed.
2546 2846
2547=item L<Net::SSLeay> 2847=item L<Net::SSLeay>
2548 2848
2549Implementing TLS/SSL in Perl is certainly interesting, but not very 2849Implementing TLS/SSL in Perl is certainly interesting, but not very
2550worthwhile: If this module is installed, then L<AnyEvent::Handle> (with 2850worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2551the 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.
2552 2852
2553=item L<Time::HiRes> 2853=item L<Time::HiRes>
2554 2854
2555This 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
2556chosen 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
2557pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to 2857pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to
2558try to use a monotonic clock for timing stability. 2858try to use a monotonic clock for timing stability.
2559 2859
2560=back 2860=back
2561 2861
2562 2862
2624pronounced). 2924pronounced).
2625 2925
2626 2926
2627=head1 SEE ALSO 2927=head1 SEE ALSO
2628 2928
2629Utility functions: L<AnyEvent::Util>. 2929Tutorial/Introduction: L<AnyEvent::Intro>.
2630 2930
2631Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 2931FAQ: L<AnyEvent::FAQ>.
2632L<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>.
2633 2942
2634Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2943Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2635L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2944L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2636L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2945L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2637L<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>.
2638 2948
2639Non-blocking file handles, sockets, TCP clients and 2949Non-blocking handles, pipes, stream sockets, TCP clients and
2640servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2950servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2641 2951
2642Asynchronous DNS: L<AnyEvent::DNS>. 2952Asynchronous DNS: L<AnyEvent::DNS>.
2643 2953
2644Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, 2954Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
2645L<Coro::Event>,
2646 2955
2647Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>, 2956Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::IRC>,
2648L<AnyEvent::HTTP>. 2957L<AnyEvent::HTTP>.
2649 2958
2650 2959
2651=head1 AUTHOR 2960=head1 AUTHOR
2652 2961

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines