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.65 by root, Fri Apr 25 06:58:12 2008 UTC vs.
Revision 1.207 by root, Thu Apr 23 22:44:30 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - provide framework for multiple event loops
4 4
5EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops 5EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 use AnyEvent; 9 use AnyEvent;
10 10
11 # file descriptor readable
11 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 12 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
13
14 # one-shot or repeating timers
15 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
16 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
17
18 print AnyEvent->now; # prints current event loop time
19 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
20
21 # POSIX signal
22 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
23
24 # child process exit
25 my $w = AnyEvent->child (pid => $pid, cb => sub {
26 my ($pid, $status) = @_;
12 ... 27 ...
13 }); 28 });
14 29
15 my $w = AnyEvent->timer (after => $seconds, cb => sub { 30 # called when event loop idle (if applicable)
16 ... 31 my $w = AnyEvent->idle (cb => sub { ... });
17 });
18 32
19 my $w = AnyEvent->condvar; # stores whether a condition was flagged 33 my $w = AnyEvent->condvar; # stores whether a condition was flagged
34 $w->send; # wake up current and all future recv's
20 $w->wait; # enters "main loop" till $condvar gets ->broadcast 35 $w->recv; # enters "main loop" till $condvar gets ->send
21 $w->broadcast; # wake up current and all future wait's 36 # use a condvar in callback mode:
37 $w->cb (sub { $_[0]->recv });
38
39=head1 INTRODUCTION/TUTORIAL
40
41This manpage is mainly a reference manual. If you are interested
42in a tutorial or some gentle introduction, have a look at the
43L<AnyEvent::Intro> manpage.
22 44
23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 45=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24 46
25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 47Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26nowadays. So what is different about AnyEvent? 48nowadays. So what is different about AnyEvent?
27 49
28Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of 50Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
29policy> and AnyEvent is I<small and efficient>. 51policy> and AnyEvent is I<small and efficient>.
30 52
31First and foremost, I<AnyEvent is not an event model> itself, it only 53First and foremost, I<AnyEvent is not an event model> itself, it only
32interfaces to whatever event model the main program happens to use in a 54interfaces to whatever event model the main program happens to use, in a
33pragmatic way. For event models and certain classes of immortals alike, 55pragmatic way. For event models and certain classes of immortals alike,
34the statement "there can only be one" is a bitter reality: In general, 56the statement "there can only be one" is a bitter reality: In general,
35only one event loop can be active at the same time in a process. AnyEvent 57only one event loop can be active at the same time in a process. AnyEvent
36helps hiding the differences between those event loops. 58cannot change this, but it can hide the differences between those event
59loops.
37 60
38The goal of AnyEvent is to offer module authors the ability to do event 61The goal of AnyEvent is to offer module authors the ability to do event
39programming (waiting for I/O or timer events) without subscribing to a 62programming (waiting for I/O or timer events) without subscribing to a
40religion, a way of living, and most importantly: without forcing your 63religion, a way of living, and most importantly: without forcing your
41module users into the same thing by forcing them to use the same event 64module users into the same thing by forcing them to use the same event
42model you use. 65model you use.
43 66
44For modules like POE or IO::Async (which is a total misnomer as it is 67For modules like POE or IO::Async (which is a total misnomer as it is
45actually doing all I/O I<synchronously>...), using them in your module is 68actually doing all I/O I<synchronously>...), using them in your module is
46like joining a cult: After you joined, you are dependent on them and you 69like joining a cult: After you joined, you are dependent on them and you
47cannot use anything else, as it is simply incompatible to everything that 70cannot use anything else, as they are simply incompatible to everything
48isn't itself. What's worse, all the potential users of your module are 71that isn't them. What's worse, all the potential users of your
49I<also> forced to use the same event loop you use. 72module are I<also> forced to use the same event loop you use.
50 73
51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 74AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
52fine. AnyEvent + Tk works fine etc. etc. but none of these work together 75fine. AnyEvent + Tk works fine etc. etc. but none of these work together
53with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if 76with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if
54your module uses one of those, every user of your module has to use it, 77your module uses one of those, every user of your module has to use it,
55too. But if your module uses AnyEvent, it works transparently with all 78too. But if your module uses AnyEvent, it works transparently with all
56event models it supports (including stuff like POE and IO::Async, as long 79event models it supports (including stuff like IO::Async, as long as those
57as those use one of the supported event loops. It is trivial to add new 80use one of the supported event loops. It is trivial to add new event loops
58event loops to AnyEvent, too, so it is future-proof). 81to AnyEvent, too, so it is future-proof).
59 82
60In addition to being free of having to use I<the one and only true event 83In addition to being free of having to use I<the one and only true event
61model>, AnyEvent also is free of bloat and policy: with POE or similar 84model>, AnyEvent also is free of bloat and policy: with POE or similar
62modules, you get an enourmous amount of code and strict rules you have to 85modules, you get an enormous amount of code and strict rules you have to
63follow. AnyEvent, on the other hand, is lean and up to the point, by only 86follow. AnyEvent, on the other hand, is lean and up to the point, by only
64offering the functionality that is necessary, in as thin as a wrapper as 87offering the functionality that is necessary, in as thin as a wrapper as
65technically possible. 88technically possible.
66 89
90Of course, AnyEvent comes with a big (and fully optional!) toolbox
91of useful functionality, such as an asynchronous DNS resolver, 100%
92non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
93such as Windows) and lots of real-world knowledge and workarounds for
94platform bugs and differences.
95
67Of course, if you want lots of policy (this can arguably be somewhat 96Now, if you I<do want> lots of policy (this can arguably be somewhat
68useful) and you want to force your users to use the one and only event 97useful) and you want to force your users to use the one and only event
69model, you should I<not> use this module. 98model, you should I<not> use this module.
70
71 99
72=head1 DESCRIPTION 100=head1 DESCRIPTION
73 101
74L<AnyEvent> provides an identical interface to multiple event loops. This 102L<AnyEvent> provides an identical interface to multiple event loops. This
75allows module authors to utilise an event loop without forcing module 103allows module authors to utilise an event loop without forcing module
79The interface itself is vaguely similar, but not identical to the L<Event> 107The interface itself is vaguely similar, but not identical to the L<Event>
80module. 108module.
81 109
82During the first call of any watcher-creation method, the module tries 110During the first call of any watcher-creation method, the module tries
83to detect the currently loaded event loop by probing whether one of the 111to detect the currently loaded event loop by probing whether one of the
84following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>, 112following modules is already loaded: L<EV>,
85L<Event>, L<Glib>, L<Tk>, L<AnyEvent::Impl::Perl>, L<Event::Lib>, L<Qt>, 113L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>,
86L<POE>. The first one found is used. If none are found, the module tries 114L<POE>. The first one found is used. If none are found, the module tries
87to load these modules (excluding Event::Lib, Qt and POE as the pure perl 115to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl
88adaptor should always succeed) in the order given. The first one that can 116adaptor should always succeed) in the order given. The first one that can
89be successfully loaded will be used. If, after this, still none could be 117be successfully loaded will be used. If, after this, still none could be
90found, AnyEvent will fall back to a pure-perl event loop, which is not 118found, AnyEvent will fall back to a pure-perl event loop, which is not
91very efficient, but should work everywhere. 119very efficient, but should work everywhere.
92 120
103starts using it, all bets are off. Maybe you should tell their authors to 131starts using it, all bets are off. Maybe you should tell their authors to
104use AnyEvent so their modules work together with others seamlessly... 132use AnyEvent so their modules work together with others seamlessly...
105 133
106The pure-perl implementation of AnyEvent is called 134The pure-perl implementation of AnyEvent is called
107C<AnyEvent::Impl::Perl>. Like other event modules you can load it 135C<AnyEvent::Impl::Perl>. Like other event modules you can load it
108explicitly. 136explicitly and enjoy the high availability of that event loop :)
109 137
110=head1 WATCHERS 138=head1 WATCHERS
111 139
112AnyEvent has the central concept of a I<watcher>, which is an object that 140AnyEvent has the central concept of a I<watcher>, which is an object that
113stores relevant data for each kind of event you are waiting for, such as 141stores relevant data for each kind of event you are waiting for, such as
114the callback to call, the filehandle to watch, etc. 142the callback to call, the file handle to watch, etc.
115 143
116These watchers are normal Perl objects with normal Perl lifetime. After 144These watchers are normal Perl objects with normal Perl lifetime. After
117creating a watcher it will immediately "watch" for events and invoke the 145creating a watcher it will immediately "watch" for events and invoke the
118callback when the event occurs (of course, only when the event model 146callback when the event occurs (of course, only when the event model
119is in control). 147is in control).
120 148
149Note that B<callbacks must not permanently change global variables>
150potentially in use by the event loop (such as C<$_> or C<$[>) and that B<<
151callbacks must not C<die> >>. The former is good programming practise in
152Perl and the latter stems from the fact that exception handling differs
153widely between event loops.
154
121To disable the watcher you have to destroy it (e.g. by setting the 155To disable the watcher you have to destroy it (e.g. by setting the
122variable you store it in to C<undef> or otherwise deleting all references 156variable you store it in to C<undef> or otherwise deleting all references
123to it). 157to it).
124 158
125All watchers are created by calling a method on the C<AnyEvent> class. 159All watchers are created by calling a method on the C<AnyEvent> class.
127Many watchers either are used with "recursion" (repeating timers for 161Many watchers either are used with "recursion" (repeating timers for
128example), or need to refer to their watcher object in other ways. 162example), or need to refer to their watcher object in other ways.
129 163
130An any way to achieve that is this pattern: 164An any way to achieve that is this pattern:
131 165
132 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 166 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
133 # you can use $w here, for example to undef it 167 # you can use $w here, for example to undef it
134 undef $w; 168 undef $w;
135 }); 169 });
136 170
137Note that C<my $w; $w => combination. This is necessary because in Perl, 171Note that C<my $w; $w => combination. This is necessary because in Perl,
138my variables are only visible after the statement in which they are 172my variables are only visible after the statement in which they are
139declared. 173declared.
140 174
141=head2 IO WATCHERS 175=head2 I/O WATCHERS
142 176
143You can create an I/O watcher by calling the C<< AnyEvent->io >> method 177You can create an I/O watcher by calling the C<< AnyEvent->io >> method
144with the following mandatory key-value pairs as arguments: 178with the following mandatory key-value pairs as arguments:
145 179
146C<fh> the Perl I<file handle> (I<not> file descriptor) to watch for 180C<fh> is the Perl I<file handle> (I<not> file descriptor) to watch
181for events (AnyEvent might or might not keep a reference to this file
182handle). Note that only file handles pointing to things for which
183non-blocking operation makes sense are allowed. This includes sockets,
184most character devices, pipes, fifos and so on, but not for example files
185or block devices.
186
147events. C<poll> must be a string that is either C<r> or C<w>, which 187C<poll> must be a string that is either C<r> or C<w>, which creates a
148creates a watcher waiting for "r"eadable or "w"ritable events, 188watcher waiting for "r"eadable or "w"ritable events, respectively.
189
149respectively. C<cb> is the callback to invoke each time the file handle 190C<cb> is the callback to invoke each time the file handle becomes ready.
150becomes ready.
151 191
152As long as the I/O watcher exists it will keep the file descriptor or a 192Although the callback might get passed parameters, their value and
153copy of it alive/open. 193presence is undefined and you cannot rely on them. Portable AnyEvent
194callbacks cannot use arguments passed to I/O watcher callbacks.
154 195
196The I/O watcher might use the underlying file descriptor or a copy of it.
155It is not allowed to close a file handle as long as any watcher is active 197You must not close a file handle as long as any watcher is active on the
156on the underlying file descriptor. 198underlying file descriptor.
157 199
158Some event loops issue spurious readyness notifications, so you should 200Some event loops issue spurious readyness notifications, so you should
159always use non-blocking calls when reading/writing from/to your file 201always use non-blocking calls when reading/writing from/to your file
160handles. 202handles.
161 203
162Example:
163
164 # wait for readability of STDIN, then read a line and disable the watcher 204Example: wait for readability of STDIN, then read a line and disable the
205watcher.
206
165 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 207 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
166 chomp (my $input = <STDIN>); 208 chomp (my $input = <STDIN>);
167 warn "read: $input\n"; 209 warn "read: $input\n";
168 undef $w; 210 undef $w;
169 }); 211 });
172 214
173You can create a time watcher by calling the C<< AnyEvent->timer >> 215You can create a time watcher by calling the C<< AnyEvent->timer >>
174method with the following mandatory arguments: 216method with the following mandatory arguments:
175 217
176C<after> specifies after how many seconds (fractional values are 218C<after> specifies after how many seconds (fractional values are
177supported) should the timer activate. C<cb> the callback to invoke in that 219supported) the callback should be invoked. C<cb> is the callback to invoke
178case. 220in that case.
179 221
180The timer callback will be invoked at most once: if you want a repeating 222Although the callback might get passed parameters, their value and
181timer you have to create a new watcher (this is a limitation by both Tk 223presence is undefined and you cannot rely on them. Portable AnyEvent
182and Glib). 224callbacks cannot use arguments passed to time watcher callbacks.
183 225
184Example: 226The callback will normally be invoked once only. If you specify another
227parameter, C<interval>, as a strictly positive number (> 0), then the
228callback will be invoked regularly at that interval (in fractional
229seconds) after the first invocation. If C<interval> is specified with a
230false value, then it is treated as if it were missing.
185 231
232The callback will be rescheduled before invoking the callback, but no
233attempt is done to avoid timer drift in most backends, so the interval is
234only approximate.
235
186 # fire an event after 7.7 seconds 236Example: fire an event after 7.7 seconds.
237
187 my $w = AnyEvent->timer (after => 7.7, cb => sub { 238 my $w = AnyEvent->timer (after => 7.7, cb => sub {
188 warn "timeout\n"; 239 warn "timeout\n";
189 }); 240 });
190 241
191 # to cancel the timer: 242 # to cancel the timer:
192 undef $w; 243 undef $w;
193 244
194Example 2:
195
196 # fire an event after 0.5 seconds, then roughly every second 245Example 2: fire an event after 0.5 seconds, then roughly every second.
197 my $w;
198 246
199 my $cb = sub {
200 # cancel the old timer while creating a new one
201 $w = AnyEvent->timer (after => 1, cb => $cb); 247 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
248 warn "timeout\n";
202 }; 249 };
203
204 # start the "loop" by creating the first watcher
205 $w = AnyEvent->timer (after => 0.5, cb => $cb);
206 250
207=head3 TIMING ISSUES 251=head3 TIMING ISSUES
208 252
209There are two ways to handle timers: based on real time (relative, "fire 253There are two ways to handle timers: based on real time (relative, "fire
210in 10 seconds") and based on wallclock time (absolute, "fire at 12 254in 10 seconds") and based on wallclock time (absolute, "fire at 12
222timers. 266timers.
223 267
224AnyEvent always prefers relative timers, if available, matching the 268AnyEvent always prefers relative timers, if available, matching the
225AnyEvent API. 269AnyEvent API.
226 270
271AnyEvent has two additional methods that return the "current time":
272
273=over 4
274
275=item AnyEvent->time
276
277This returns the "current wallclock time" as a fractional number of
278seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
279return, and the result is guaranteed to be compatible with those).
280
281It progresses independently of any event loop processing, i.e. each call
282will check the system clock, which usually gets updated frequently.
283
284=item AnyEvent->now
285
286This also returns the "current wallclock time", but unlike C<time>, above,
287this value might change only once per event loop iteration, depending on
288the event loop (most return the same time as C<time>, above). This is the
289time that AnyEvent's timers get scheduled against.
290
291I<In almost all cases (in all cases if you don't care), this is the
292function to call when you want to know the current time.>
293
294This function is also often faster then C<< AnyEvent->time >>, and
295thus the preferred method if you want some timestamp (for example,
296L<AnyEvent::Handle> uses this to update it's activity timeouts).
297
298The rest of this section is only of relevance if you try to be very exact
299with your timing, you can skip it without bad conscience.
300
301For a practical example of when these times differ, consider L<Event::Lib>
302and L<EV> and the following set-up:
303
304The event loop is running and has just invoked one of your callback at
305time=500 (assume no other callbacks delay processing). In your callback,
306you wait a second by executing C<sleep 1> (blocking the process for a
307second) and then (at time=501) you create a relative timer that fires
308after three seconds.
309
310With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
311both return C<501>, because that is the current time, and the timer will
312be scheduled to fire at time=504 (C<501> + C<3>).
313
314With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
315time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
316last event processing phase started. With L<EV>, your timer gets scheduled
317to run at time=503 (C<500> + C<3>).
318
319In one sense, L<Event::Lib> is more exact, as it uses the current time
320regardless of any delays introduced by event processing. However, most
321callbacks do not expect large delays in processing, so this causes a
322higher drift (and a lot more system calls to get the current time).
323
324In another sense, L<EV> is more exact, as your timer will be scheduled at
325the same time, regardless of how long event processing actually took.
326
327In either case, if you care (and in most cases, you don't), then you
328can get whatever behaviour you want with any event loop, by taking the
329difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
330account.
331
332=item AnyEvent->now_update
333
334Some event loops (such as L<EV> or L<AnyEvent::Impl::Perl>) cache
335the current time for each loop iteration (see the discussion of L<<
336AnyEvent->now >>, above).
337
338When a callback runs for a long time (or when the process sleeps), then
339this "current" time will differ substantially from the real time, which
340might affect timers and time-outs.
341
342When this is the case, you can call this method, which will update the
343event loop's idea of "current time".
344
345Note that updating the time I<might> cause some events to be handled.
346
347=back
348
227=head2 SIGNAL WATCHERS 349=head2 SIGNAL WATCHERS
228 350
229You can watch for signals using a signal watcher, C<signal> is the signal 351You can watch for signals using a signal watcher, C<signal> is the signal
230I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 352I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
231be invoked whenever a signal occurs. 353callback to be invoked whenever a signal occurs.
232 354
355Although the callback might get passed parameters, their value and
356presence is undefined and you cannot rely on them. Portable AnyEvent
357callbacks cannot use arguments passed to signal watcher callbacks.
358
233Multiple signal occurances can be clumped together into one callback 359Multiple signal occurrences can be clumped together into one callback
234invocation, and callback invocation will be synchronous. synchronous means 360invocation, and callback invocation will be synchronous. Synchronous means
235that it might take a while until the signal gets handled by the process, 361that it might take a while until the signal gets handled by the process,
236but it is guarenteed not to interrupt any other callbacks. 362but it is guaranteed not to interrupt any other callbacks.
237 363
238The main advantage of using these watchers is that you can share a signal 364The main advantage of using these watchers is that you can share a signal
239between multiple watchers. 365between multiple watchers.
240 366
241This watcher might use C<%SIG>, so programs overwriting those signals 367This watcher might use C<%SIG>, so programs overwriting those signals
248=head2 CHILD PROCESS WATCHERS 374=head2 CHILD PROCESS WATCHERS
249 375
250You can also watch on a child process exit and catch its exit status. 376You can also watch on a child process exit and catch its exit status.
251 377
252The child process is specified by the C<pid> argument (if set to C<0>, it 378The child process is specified by the C<pid> argument (if set to C<0>, it
253watches for any child process exit). The watcher will trigger as often 379watches for any child process exit). The watcher will triggered only when
254as status change for the child are received. This works by installing a 380the child process has finished and an exit status is available, not on
255signal handler for C<SIGCHLD>. The callback will be called with the pid 381any trace events (stopped/continued).
256and exit status (as returned by waitpid).
257 382
258Example: wait for pid 1333 383The callback will be called with the pid and exit status (as returned by
384waitpid), so unlike other watcher types, you I<can> rely on child watcher
385callback arguments.
259 386
387This watcher type works by installing a signal handler for C<SIGCHLD>,
388and since it cannot be shared, nothing else should use SIGCHLD or reap
389random child processes (waiting for specific child processes, e.g. inside
390C<system>, is just fine).
391
392There is a slight catch to child watchers, however: you usually start them
393I<after> the child process was created, and this means the process could
394have exited already (and no SIGCHLD will be sent anymore).
395
396Not all event models handle this correctly (POE doesn't), but even for
397event models that I<do> handle this correctly, they usually need to be
398loaded before the process exits (i.e. before you fork in the first place).
399
400This means you cannot create a child watcher as the very first thing in an
401AnyEvent program, you I<have> to create at least one watcher before you
402C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
403
404Example: fork a process and wait for it
405
406 my $done = AnyEvent->condvar;
407
408 my $pid = fork or exit 5;
409
260 my $w = AnyEvent->child ( 410 my $w = AnyEvent->child (
261 pid => 1333, 411 pid => $pid,
262 cb => sub { 412 cb => sub {
263 my ($pid, $status) = @_; 413 my ($pid, $status) = @_;
264 warn "pid $pid exited with status $status"; 414 warn "pid $pid exited with status $status";
415 $done->send;
265 }, 416 },
266 ); 417 );
418
419 # do something else, then wait for process exit
420 $done->recv;
421
422=head2 IDLE WATCHERS
423
424Sometimes there is a need to do something, but it is not so important
425to do it instantly, but only when there is nothing better to do. This
426"nothing better to do" is usually defined to be "no other events need
427attention by the event loop".
428
429Idle watchers ideally get invoked when the event loop has nothing
430better to do, just before it would block the process to wait for new
431events. Instead of blocking, the idle watcher is invoked.
432
433Most event loops unfortunately do not really support idle watchers (only
434EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
435will simply call the callback "from time to time".
436
437Example: read lines from STDIN, but only process them when the
438program is otherwise idle:
439
440 my @lines; # read data
441 my $idle_w;
442 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
443 push @lines, scalar <STDIN>;
444
445 # start an idle watcher, if not already done
446 $idle_w ||= AnyEvent->idle (cb => sub {
447 # handle only one line, when there are lines left
448 if (my $line = shift @lines) {
449 print "handled when idle: $line";
450 } else {
451 # otherwise disable the idle watcher again
452 undef $idle_w;
453 }
454 });
455 });
267 456
268=head2 CONDITION VARIABLES 457=head2 CONDITION VARIABLES
269 458
459If you are familiar with some event loops you will know that all of them
460require you to run some blocking "loop", "run" or similar function that
461will actively watch for new events and call your callbacks.
462
463AnyEvent is different, it expects somebody else to run the event loop and
464will only block when necessary (usually when told by the user).
465
466The instrument to do that is called a "condition variable", so called
467because they represent a condition that must become true.
468
270Condition variables can be created by calling the C<< AnyEvent->condvar >> 469Condition variables can be created by calling the C<< AnyEvent->condvar
271method without any arguments. 470>> method, usually without arguments. The only argument pair allowed is
272 471
273A condition variable waits for a condition - precisely that the C<< 472C<cb>, which specifies a callback to be called when the condition variable
274->broadcast >> method has been called. 473becomes true, with the condition variable as the first argument (but not
474the results).
275 475
276They are very useful to signal that a condition has been fulfilled, for 476After creation, the condition variable is "false" until it becomes "true"
477by calling the C<send> method (or calling the condition variable as if it
478were a callback, read about the caveats in the description for the C<<
479->send >> method).
480
481Condition variables are similar to callbacks, except that you can
482optionally wait for them. They can also be called merge points - points
483in time where multiple outstanding events have been processed. And yet
484another way to call them is transactions - each condition variable can be
485used to represent a transaction, which finishes at some point and delivers
486a result.
487
488Condition variables are very useful to signal that something has finished,
277example, if you write a module that does asynchronous http requests, 489for example, if you write a module that does asynchronous http requests,
278then a condition variable would be the ideal candidate to signal the 490then a condition variable would be the ideal candidate to signal the
279availability of results. 491availability of results. The user can either act when the callback is
492called or can synchronously C<< ->recv >> for the results.
280 493
281You can also use condition variables to block your main program until 494You can also use them to simulate traditional event loops - for example,
282an event occurs - for example, you could C<< ->wait >> in your main 495you can block your main program until an event occurs - for example, you
283program until the user clicks the Quit button in your app, which would C<< 496could C<< ->recv >> in your main program until the user clicks the Quit
284->broadcast >> the "quit" event. 497button of your app, which would C<< ->send >> the "quit" event.
285 498
286Note that condition variables recurse into the event loop - if you have 499Note that condition variables recurse into the event loop - if you have
287two pirces of code that call C<< ->wait >> in a round-robbin fashion, you 500two pieces of code that call C<< ->recv >> in a round-robin fashion, you
288lose. Therefore, condition variables are good to export to your caller, but 501lose. Therefore, condition variables are good to export to your caller, but
289you should avoid making a blocking wait yourself, at least in callbacks, 502you should avoid making a blocking wait yourself, at least in callbacks,
290as this asks for trouble. 503as this asks for trouble.
291 504
292This object has two methods: 505Condition variables are represented by hash refs in perl, and the keys
506used by AnyEvent itself are all named C<_ae_XXX> to make subclassing
507easy (it is often useful to build your own transaction class on top of
508AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call
509it's C<new> method in your own C<new> method.
510
511There are two "sides" to a condition variable - the "producer side" which
512eventually calls C<< -> send >>, and the "consumer side", which waits
513for the send to occur.
514
515Example: wait for a timer.
516
517 # wait till the result is ready
518 my $result_ready = AnyEvent->condvar;
519
520 # do something such as adding a timer
521 # or socket watcher the calls $result_ready->send
522 # when the "result" is ready.
523 # in this case, we simply use a timer:
524 my $w = AnyEvent->timer (
525 after => 1,
526 cb => sub { $result_ready->send },
527 );
528
529 # this "blocks" (while handling events) till the callback
530 # calls send
531 $result_ready->recv;
532
533Example: wait for a timer, but take advantage of the fact that
534condition variables are also code references.
535
536 my $done = AnyEvent->condvar;
537 my $delay = AnyEvent->timer (after => 5, cb => $done);
538 $done->recv;
539
540Example: Imagine an API that returns a condvar and doesn't support
541callbacks. This is how you make a synchronous call, for example from
542the main program:
543
544 use AnyEvent::CouchDB;
545
546 ...
547
548 my @info = $couchdb->info->recv;
549
550And this is how you would just ste a callback to be called whenever the
551results are available:
552
553 $couchdb->info->cb (sub {
554 my @info = $_[0]->recv;
555 });
556
557=head3 METHODS FOR PRODUCERS
558
559These methods should only be used by the producing side, i.e. the
560code/module that eventually sends the signal. Note that it is also
561the producer side which creates the condvar in most cases, but it isn't
562uncommon for the consumer to create it as well.
293 563
294=over 4 564=over 4
295 565
566=item $cv->send (...)
567
568Flag the condition as ready - a running C<< ->recv >> and all further
569calls to C<recv> will (eventually) return after this method has been
570called. If nobody is waiting the send will be remembered.
571
572If a callback has been set on the condition variable, it is called
573immediately from within send.
574
575Any arguments passed to the C<send> call will be returned by all
576future C<< ->recv >> calls.
577
578Condition variables are overloaded so one can call them directly
579(as a code reference). Calling them directly is the same as calling
580C<send>. Note, however, that many C-based event loops do not handle
581overloading, so as tempting as it may be, passing a condition variable
582instead of a callback does not work. Both the pure perl and EV loops
583support overloading, however, as well as all functions that use perl to
584invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
585example).
586
587=item $cv->croak ($error)
588
589Similar to send, but causes all call's to C<< ->recv >> to invoke
590C<Carp::croak> with the given error message/object/scalar.
591
592This can be used to signal any errors to the condition variable
593user/consumer.
594
595=item $cv->begin ([group callback])
596
296=item $cv->wait 597=item $cv->end
297 598
298Wait (blocking if necessary) until the C<< ->broadcast >> method has been 599These two methods are EXPERIMENTAL and MIGHT CHANGE.
600
601These two methods can be used to combine many transactions/events into
602one. For example, a function that pings many hosts in parallel might want
603to use a condition variable for the whole process.
604
605Every call to C<< ->begin >> will increment a counter, and every call to
606C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
607>>, the (last) callback passed to C<begin> will be executed. That callback
608is I<supposed> to call C<< ->send >>, but that is not required. If no
609callback was set, C<send> will be called without any arguments.
610
611Let's clarify this with the ping example:
612
613 my $cv = AnyEvent->condvar;
614
615 my %result;
616 $cv->begin (sub { $cv->send (\%result) });
617
618 for my $host (@list_of_hosts) {
619 $cv->begin;
620 ping_host_then_call_callback $host, sub {
621 $result{$host} = ...;
622 $cv->end;
623 };
624 }
625
626 $cv->end;
627
628This code fragment supposedly pings a number of hosts and calls
629C<send> after results for all then have have been gathered - in any
630order. To achieve this, the code issues a call to C<begin> when it starts
631each ping request and calls C<end> when it has received some result for
632it. Since C<begin> and C<end> only maintain a counter, the order in which
633results arrive is not relevant.
634
635There is an additional bracketing call to C<begin> and C<end> outside the
636loop, which serves two important purposes: first, it sets the callback
637to be called once the counter reaches C<0>, and second, it ensures that
638C<send> is called even when C<no> hosts are being pinged (the loop
639doesn't execute once).
640
641This is the general pattern when you "fan out" into multiple subrequests:
642use an outer C<begin>/C<end> pair to set the callback and ensure C<end>
643is called at least once, and then, for each subrequest you start, call
644C<begin> and for each subrequest you finish, call C<end>.
645
646=back
647
648=head3 METHODS FOR CONSUMERS
649
650These methods should only be used by the consuming side, i.e. the
651code awaits the condition.
652
653=over 4
654
655=item $cv->recv
656
657Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
299called on c<$cv>, while servicing other watchers normally. 658>> methods have been called on c<$cv>, while servicing other watchers
659normally.
300 660
301You can only wait once on a condition - additional calls will return 661You can only wait once on a condition - additional calls are valid but
302immediately. 662will return immediately.
663
664If an error condition has been set by calling C<< ->croak >>, then this
665function will call C<croak>.
666
667In list context, all parameters passed to C<send> will be returned,
668in scalar context only the first one will be returned.
303 669
304Not all event models support a blocking wait - some die in that case 670Not all event models support a blocking wait - some die in that case
305(programs might want to do that to stay interactive), so I<if you are 671(programs might want to do that to stay interactive), so I<if you are
306using this from a module, never require a blocking wait>, but let the 672using this from a module, never require a blocking wait>, but let the
307caller decide whether the call will block or not (for example, by coupling 673caller decide whether the call will block or not (for example, by coupling
308condition variables with some kind of request results and supporting 674condition variables with some kind of request results and supporting
309callbacks so the caller knows that getting the result will not block, 675callbacks so the caller knows that getting the result will not block,
310while still suppporting blocking waits if the caller so desires). 676while still supporting blocking waits if the caller so desires).
311 677
312Another reason I<never> to C<< ->wait >> in a module is that you cannot 678Another reason I<never> to C<< ->recv >> in a module is that you cannot
313sensibly have two C<< ->wait >>'s in parallel, as that would require 679sensibly have two C<< ->recv >>'s in parallel, as that would require
314multiple interpreters or coroutines/threads, none of which C<AnyEvent> 680multiple interpreters or coroutines/threads, none of which C<AnyEvent>
315can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and 681can supply.
316L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s
317from different coroutines, however).
318 682
319=item $cv->broadcast 683The L<Coro> module, however, I<can> and I<does> supply coroutines and, in
684fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe
685versions and also integrates coroutines into AnyEvent, making blocking
686C<< ->recv >> calls perfectly safe as long as they are done from another
687coroutine (one that doesn't run the event loop).
320 688
321Flag the condition as ready - a running C<< ->wait >> and all further 689You can ensure that C<< -recv >> never blocks by setting a callback and
322calls to C<wait> will (eventually) return after this method has been 690only calling C<< ->recv >> from within that callback (or at a later
323called. If nobody is waiting the broadcast will be remembered.. 691time). This will work even when the event loop does not support blocking
692waits otherwise.
693
694=item $bool = $cv->ready
695
696Returns true when the condition is "true", i.e. whether C<send> or
697C<croak> have been called.
698
699=item $cb = $cv->cb ($cb->($cv))
700
701This is a mutator function that returns the callback set and optionally
702replaces it before doing so.
703
704The callback will be called when the condition becomes "true", i.e. when
705C<send> or C<croak> are called, with the only argument being the condition
706variable itself. Calling C<recv> inside the callback or at any later time
707is guaranteed not to block.
324 708
325=back 709=back
326
327Example:
328
329 # wait till the result is ready
330 my $result_ready = AnyEvent->condvar;
331
332 # do something such as adding a timer
333 # or socket watcher the calls $result_ready->broadcast
334 # when the "result" is ready.
335 # in this case, we simply use a timer:
336 my $w = AnyEvent->timer (
337 after => 1,
338 cb => sub { $result_ready->broadcast },
339 );
340
341 # this "blocks" (while handling events) till the watcher
342 # calls broadcast
343 $result_ready->wait;
344 710
345=head1 GLOBAL VARIABLES AND FUNCTIONS 711=head1 GLOBAL VARIABLES AND FUNCTIONS
346 712
347=over 4 713=over 4
348 714
354C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 720C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
355AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 721AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
356 722
357The known classes so far are: 723The known classes so far are:
358 724
359 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
360 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
361 AnyEvent::Impl::EV based on EV (an interface to libev, best choice). 725 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
362 AnyEvent::Impl::Event based on Event, second best choice. 726 AnyEvent::Impl::Event based on Event, second best choice.
727 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
363 AnyEvent::Impl::Glib based on Glib, third-best choice. 728 AnyEvent::Impl::Glib based on Glib, third-best choice.
364 AnyEvent::Impl::Tk based on Tk, very bad choice. 729 AnyEvent::Impl::Tk based on Tk, very bad choice.
365 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
366 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 730 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
367 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 731 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
368 AnyEvent::Impl::POE based on POE, not generic enough for full support. 732 AnyEvent::Impl::POE based on POE, not generic enough for full support.
369 733
370There is no support for WxWidgets, as WxWidgets has no support for 734There is no support for WxWidgets, as WxWidgets has no support for
382Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 746Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
383if necessary. You should only call this function right before you would 747if necessary. You should only call this function right before you would
384have created an AnyEvent watcher anyway, that is, as late as possible at 748have created an AnyEvent watcher anyway, that is, as late as possible at
385runtime. 749runtime.
386 750
751=item $guard = AnyEvent::post_detect { BLOCK }
752
753Arranges for the code block to be executed as soon as the event model is
754autodetected (or immediately if this has already happened).
755
756If called in scalar or list context, then it creates and returns an object
757that automatically removes the callback again when it is destroyed. See
758L<Coro::BDB> for a case where this is useful.
759
760=item @AnyEvent::post_detect
761
762If there are any code references in this array (you can C<push> to it
763before or after loading AnyEvent), then they will called directly after
764the event loop has been chosen.
765
766You should check C<$AnyEvent::MODEL> before adding to this array, though:
767if it contains a true value then the event loop has already been detected,
768and the array will be ignored.
769
770Best use C<AnyEvent::post_detect { BLOCK }> instead.
771
387=back 772=back
388 773
389=head1 WHAT TO DO IN A MODULE 774=head1 WHAT TO DO IN A MODULE
390 775
391As a module author, you should C<use AnyEvent> and call AnyEvent methods 776As a module author, you should C<use AnyEvent> and call AnyEvent methods
394Be careful when you create watchers in the module body - AnyEvent will 779Be careful when you create watchers in the module body - AnyEvent will
395decide which event module to use as soon as the first method is called, so 780decide which event module to use as soon as the first method is called, so
396by calling AnyEvent in your module body you force the user of your module 781by calling AnyEvent in your module body you force the user of your module
397to load the event module first. 782to load the event module first.
398 783
399Never call C<< ->wait >> on a condition variable unless you I<know> that 784Never call C<< ->recv >> on a condition variable unless you I<know> that
400the C<< ->broadcast >> method has been called on it already. This is 785the C<< ->send >> method has been called on it already. This is
401because it will stall the whole program, and the whole point of using 786because it will stall the whole program, and the whole point of using
402events is to stay interactive. 787events is to stay interactive.
403 788
404It is fine, however, to call C<< ->wait >> when the user of your module 789It is fine, however, to call C<< ->recv >> when the user of your module
405requests it (i.e. if you create a http request object ad have a method 790requests it (i.e. if you create a http request object ad have a method
406called C<results> that returns the results, it should call C<< ->wait >> 791called C<results> that returns the results, it should call C<< ->recv >>
407freely, as the user of your module knows what she is doing. always). 792freely, as the user of your module knows what she is doing. always).
408 793
409=head1 WHAT TO DO IN THE MAIN PROGRAM 794=head1 WHAT TO DO IN THE MAIN PROGRAM
410 795
411There will always be a single main program - the only place that should 796There will always be a single main program - the only place that should
413 798
414If it doesn't care, it can just "use AnyEvent" and use it itself, or not 799If it doesn't care, it can just "use AnyEvent" and use it itself, or not
415do anything special (it does not need to be event-based) and let AnyEvent 800do anything special (it does not need to be event-based) and let AnyEvent
416decide which implementation to chose if some module relies on it. 801decide which implementation to chose if some module relies on it.
417 802
418If the main program relies on a specific event model. For example, in 803If the main program relies on a specific event model - for example, in
419Gtk2 programs you have to rely on the Glib module. You should load the 804Gtk2 programs you have to rely on the Glib module - you should load the
420event module before loading AnyEvent or any module that uses it: generally 805event module before loading AnyEvent or any module that uses it: generally
421speaking, you should load it as early as possible. The reason is that 806speaking, you should load it as early as possible. The reason is that
422modules might create watchers when they are loaded, and AnyEvent will 807modules might create watchers when they are loaded, and AnyEvent will
423decide on the event model to use as soon as it creates watchers, and it 808decide on the event model to use as soon as it creates watchers, and it
424might chose the wrong one unless you load the correct one yourself. 809might chose the wrong one unless you load the correct one yourself.
425 810
426You can chose to use a rather inefficient pure-perl implementation by 811You can chose to use a pure-perl implementation by loading the
427loading the C<AnyEvent::Impl::Perl> module, which gives you similar 812C<AnyEvent::Impl::Perl> module, which gives you similar behaviour
428behaviour everywhere, but letting AnyEvent chose is generally better. 813everywhere, but letting AnyEvent chose the model is generally better.
814
815=head2 MAINLOOP EMULATION
816
817Sometimes (often for short test scripts, or even standalone programs who
818only want to use AnyEvent), you do not want to run a specific event loop.
819
820In that case, you can use a condition variable like this:
821
822 AnyEvent->condvar->recv;
823
824This has the effect of entering the event loop and looping forever.
825
826Note that usually your program has some exit condition, in which case
827it is better to use the "traditional" approach of storing a condition
828variable somewhere, waiting for it, and sending it when the program should
829exit cleanly.
830
831
832=head1 OTHER MODULES
833
834The following is a non-exhaustive list of additional modules that use
835AnyEvent and can therefore be mixed easily with other AnyEvent modules
836in the same program. Some of the modules come with AnyEvent, some are
837available via CPAN.
838
839=over 4
840
841=item L<AnyEvent::Util>
842
843Contains various utility functions that replace often-used but blocking
844functions such as C<inet_aton> by event-/callback-based versions.
845
846=item L<AnyEvent::Socket>
847
848Provides various utility functions for (internet protocol) sockets,
849addresses and name resolution. Also functions to create non-blocking tcp
850connections or tcp servers, with IPv6 and SRV record support and more.
851
852=item L<AnyEvent::Handle>
853
854Provide read and write buffers, manages watchers for reads and writes,
855supports raw and formatted I/O, I/O queued and fully transparent and
856non-blocking SSL/TLS.
857
858=item L<AnyEvent::DNS>
859
860Provides rich asynchronous DNS resolver capabilities.
861
862=item L<AnyEvent::HTTP>
863
864A simple-to-use HTTP library that is capable of making a lot of concurrent
865HTTP requests.
866
867=item L<AnyEvent::HTTPD>
868
869Provides a simple web application server framework.
870
871=item L<AnyEvent::FastPing>
872
873The fastest ping in the west.
874
875=item L<AnyEvent::DBI>
876
877Executes L<DBI> requests asynchronously in a proxy process.
878
879=item L<AnyEvent::AIO>
880
881Truly asynchronous I/O, should be in the toolbox of every event
882programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
883together.
884
885=item L<AnyEvent::BDB>
886
887Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
888L<BDB> and AnyEvent together.
889
890=item L<AnyEvent::GPSD>
891
892A non-blocking interface to gpsd, a daemon delivering GPS information.
893
894=item L<AnyEvent::IGS>
895
896A non-blocking interface to the Internet Go Server protocol (used by
897L<App::IGS>).
898
899=item L<AnyEvent::IRC>
900
901AnyEvent based IRC client module family (replacing the older Net::IRC3).
902
903=item L<Net::XMPP2>
904
905AnyEvent based XMPP (Jabber protocol) module family.
906
907=item L<Net::FCP>
908
909AnyEvent-based implementation of the Freenet Client Protocol, birthplace
910of AnyEvent.
911
912=item L<Event::ExecFlow>
913
914High level API for event-based execution flow control.
915
916=item L<Coro>
917
918Has special support for AnyEvent via L<Coro::AnyEvent>.
919
920=item L<IO::Lambda>
921
922The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
923
924=back
429 925
430=cut 926=cut
431 927
432package AnyEvent; 928package AnyEvent;
433 929
434no warnings; 930no warnings;
435use strict; 931use strict qw(vars subs);
436 932
437use Carp; 933use Carp;
438 934
439our $VERSION = '3.3'; 935our $VERSION = 4.352;
440our $MODEL; 936our $MODEL;
441 937
442our $AUTOLOAD; 938our $AUTOLOAD;
443our @ISA; 939our @ISA;
444 940
941our @REGISTRY;
942
943our $WIN32;
944
945BEGIN {
946 my $win32 = ! ! ($^O =~ /mswin32/i);
947 eval "sub WIN32(){ $win32 }";
948}
949
445our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 950our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
446 951
447our @REGISTRY; 952our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
953
954{
955 my $idx;
956 $PROTOCOL{$_} = ++$idx
957 for reverse split /\s*,\s*/,
958 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
959}
448 960
449my @models = ( 961my @models = (
450 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
451 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
452 [EV:: => AnyEvent::Impl::EV::], 962 [EV:: => AnyEvent::Impl::EV::],
453 [Event:: => AnyEvent::Impl::Event::], 963 [Event:: => AnyEvent::Impl::Event::],
454 [Glib:: => AnyEvent::Impl::Glib::],
455 [Tk:: => AnyEvent::Impl::Tk::],
456 [Wx:: => AnyEvent::Impl::POE::],
457 [Prima:: => AnyEvent::Impl::POE::],
458 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 964 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
459 # everything below here will not be autoprobed as the pureperl backend should work everywhere 965 # everything below here will not be autoprobed
966 # as the pureperl backend should work everywhere
967 # and is usually faster
968 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
969 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
460 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 970 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
461 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 971 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
462 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 972 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
973 [Wx:: => AnyEvent::Impl::POE::],
974 [Prima:: => AnyEvent::Impl::POE::],
463); 975);
464 976
465our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY); 977our %method = map +($_ => 1),
978 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
979
980our @post_detect;
981
982sub post_detect(&) {
983 my ($cb) = @_;
984
985 if ($MODEL) {
986 $cb->();
987
988 1
989 } else {
990 push @post_detect, $cb;
991
992 defined wantarray
993 ? bless \$cb, "AnyEvent::Util::postdetect"
994 : ()
995 }
996}
997
998sub AnyEvent::Util::postdetect::DESTROY {
999 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1000}
466 1001
467sub detect() { 1002sub detect() {
468 unless ($MODEL) { 1003 unless ($MODEL) {
469 no strict 'refs'; 1004 no strict 'refs';
1005 local $SIG{__DIE__};
470 1006
471 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1007 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
472 my $model = "AnyEvent::Impl::$1"; 1008 my $model = "AnyEvent::Impl::$1";
473 if (eval "require $model") { 1009 if (eval "require $model") {
474 $MODEL = $model; 1010 $MODEL = $model;
504 last; 1040 last;
505 } 1041 }
506 } 1042 }
507 1043
508 $MODEL 1044 $MODEL
509 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event) or Glib."; 1045 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n";
510 } 1046 }
511 } 1047 }
512 1048
1049 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1050
513 unshift @ISA, $MODEL; 1051 unshift @ISA, $MODEL;
514 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1052
1053 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
1054
1055 (shift @post_detect)->() while @post_detect;
515 } 1056 }
516 1057
517 $MODEL 1058 $MODEL
518} 1059}
519 1060
527 1068
528 my $class = shift; 1069 my $class = shift;
529 $class->$func (@_); 1070 $class->$func (@_);
530} 1071}
531 1072
1073# utility function to dup a filehandle. this is used by many backends
1074# to support binding more than one watcher per filehandle (they usually
1075# allow only one watcher per fd, so we dup it to get a different one).
1076sub _dupfh($$$$) {
1077 my ($poll, $fh, $r, $w) = @_;
1078
1079 # cygwin requires the fh mode to be matching, unix doesn't
1080 my ($rw, $mode) = $poll eq "r" ? ($r, "<")
1081 : $poll eq "w" ? ($w, ">")
1082 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1083
1084 open my $fh2, "$mode&" . fileno $fh
1085 or die "cannot dup() filehandle: $!,";
1086
1087 # we assume CLOEXEC is already set by perl in all important cases
1088
1089 ($fh2, $rw)
1090}
1091
532package AnyEvent::Base; 1092package AnyEvent::Base;
533 1093
1094# default implementations for many methods
1095
1096BEGIN {
1097 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1098 *_time = \&Time::HiRes::time;
1099 # if (eval "use POSIX (); (POSIX::times())...
1100 } else {
1101 *_time = sub { time }; # epic fail
1102 }
1103}
1104
1105sub time { _time }
1106sub now { _time }
1107sub now_update { }
1108
534# default implementation for ->condvar, ->wait, ->broadcast 1109# default implementation for ->condvar
535 1110
536sub condvar { 1111sub condvar {
537 bless \my $flag, "AnyEvent::Base::CondVar" 1112 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
538}
539
540sub AnyEvent::Base::CondVar::broadcast {
541 ${$_[0]}++;
542}
543
544sub AnyEvent::Base::CondVar::wait {
545 AnyEvent->one_event while !${$_[0]};
546} 1113}
547 1114
548# default implementation for ->signal 1115# default implementation for ->signal
549 1116
550our %SIG_CB; 1117our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1118
1119sub _signal_exec {
1120 sysread $SIGPIPE_R, my $dummy, 4;
1121
1122 while (%SIG_EV) {
1123 for (keys %SIG_EV) {
1124 delete $SIG_EV{$_};
1125 $_->() for values %{ $SIG_CB{$_} || {} };
1126 }
1127 }
1128}
551 1129
552sub signal { 1130sub signal {
553 my (undef, %arg) = @_; 1131 my (undef, %arg) = @_;
554 1132
1133 unless ($SIGPIPE_R) {
1134 require Fcntl;
1135
1136 if (AnyEvent::WIN32) {
1137 require AnyEvent::Util;
1138
1139 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1140 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R) if $SIGPIPE_R;
1141 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case
1142 } else {
1143 pipe $SIGPIPE_R, $SIGPIPE_W;
1144 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
1145 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
1146 }
1147
1148 $SIGPIPE_R
1149 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1150
1151 # not strictly required, as $^F is normally 2, but let's make sure...
1152 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1153 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1154
1155 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1156 }
1157
555 my $signal = uc $arg{signal} 1158 my $signal = uc $arg{signal}
556 or Carp::croak "required option 'signal' is missing"; 1159 or Carp::croak "required option 'signal' is missing";
557 1160
558 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1161 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
559 $SIG{$signal} ||= sub { 1162 $SIG{$signal} ||= sub {
560 $_->() for values %{ $SIG_CB{$signal} || {} }; 1163 local $!;
1164 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1165 undef $SIG_EV{$signal};
561 }; 1166 };
562 1167
563 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal" 1168 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
564} 1169}
565 1170
566sub AnyEvent::Base::Signal::DESTROY { 1171sub AnyEvent::Base::signal::DESTROY {
567 my ($signal, $cb) = @{$_[0]}; 1172 my ($signal, $cb) = @{$_[0]};
568 1173
569 delete $SIG_CB{$signal}{$cb}; 1174 delete $SIG_CB{$signal}{$cb};
570 1175
571 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} }; 1176 delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
572} 1177}
573 1178
574# default implementation for ->child 1179# default implementation for ->child
575 1180
576our %PID_CB; 1181our %PID_CB;
603 or Carp::croak "required option 'pid' is missing"; 1208 or Carp::croak "required option 'pid' is missing";
604 1209
605 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1210 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
606 1211
607 unless ($WNOHANG) { 1212 unless ($WNOHANG) {
608 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 1213 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
609 } 1214 }
610 1215
611 unless ($CHLD_W) { 1216 unless ($CHLD_W) {
612 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1217 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
613 # child could be a zombie already, so make at least one round 1218 # child could be a zombie already, so make at least one round
614 &_sigchld; 1219 &_sigchld;
615 } 1220 }
616 1221
617 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 1222 bless [$pid, $arg{cb}], "AnyEvent::Base::child"
618} 1223}
619 1224
620sub AnyEvent::Base::Child::DESTROY { 1225sub AnyEvent::Base::child::DESTROY {
621 my ($pid, $cb) = @{$_[0]}; 1226 my ($pid, $cb) = @{$_[0]};
622 1227
623 delete $PID_CB{$pid}{$cb}; 1228 delete $PID_CB{$pid}{$cb};
624 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1229 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
625 1230
626 undef $CHLD_W unless keys %PID_CB; 1231 undef $CHLD_W unless keys %PID_CB;
627} 1232}
1233
1234# idle emulation is done by simply using a timer, regardless
1235# of whether the proces sis idle or not, and not letting
1236# the callback use more than 50% of the time.
1237sub idle {
1238 my (undef, %arg) = @_;
1239
1240 my ($cb, $w, $rcb) = $arg{cb};
1241
1242 $rcb = sub {
1243 if ($cb) {
1244 $w = _time;
1245 &$cb;
1246 $w = _time - $w;
1247
1248 # never use more then 50% of the time for the idle watcher,
1249 # within some limits
1250 $w = 0.0001 if $w < 0.0001;
1251 $w = 5 if $w > 5;
1252
1253 $w = AnyEvent->timer (after => $w, cb => $rcb);
1254 } else {
1255 # clean up...
1256 undef $w;
1257 undef $rcb;
1258 }
1259 };
1260
1261 $w = AnyEvent->timer (after => 0.05, cb => $rcb);
1262
1263 bless \\$cb, "AnyEvent::Base::idle"
1264}
1265
1266sub AnyEvent::Base::idle::DESTROY {
1267 undef $${$_[0]};
1268}
1269
1270package AnyEvent::CondVar;
1271
1272our @ISA = AnyEvent::CondVar::Base::;
1273
1274package AnyEvent::CondVar::Base;
1275
1276use overload
1277 '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1278 fallback => 1;
1279
1280sub _send {
1281 # nop
1282}
1283
1284sub send {
1285 my $cv = shift;
1286 $cv->{_ae_sent} = [@_];
1287 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
1288 $cv->_send;
1289}
1290
1291sub croak {
1292 $_[0]{_ae_croak} = $_[1];
1293 $_[0]->send;
1294}
1295
1296sub ready {
1297 $_[0]{_ae_sent}
1298}
1299
1300sub _wait {
1301 AnyEvent->one_event while !$_[0]{_ae_sent};
1302}
1303
1304sub recv {
1305 $_[0]->_wait;
1306
1307 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak};
1308 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0]
1309}
1310
1311sub cb {
1312 $_[0]{_ae_cb} = $_[1] if @_ > 1;
1313 $_[0]{_ae_cb}
1314}
1315
1316sub begin {
1317 ++$_[0]{_ae_counter};
1318 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
1319}
1320
1321sub end {
1322 return if --$_[0]{_ae_counter};
1323 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
1324}
1325
1326# undocumented/compatibility with pre-3.4
1327*broadcast = \&send;
1328*wait = \&_wait;
1329
1330=head1 ERROR AND EXCEPTION HANDLING
1331
1332In general, AnyEvent does not do any error handling - it relies on the
1333caller to do that if required. The L<AnyEvent::Strict> module (see also
1334the C<PERL_ANYEVENT_STRICT> environment variable, below) provides strict
1335checking of all AnyEvent methods, however, which is highly useful during
1336development.
1337
1338As for exception handling (i.e. runtime errors and exceptions thrown while
1339executing a callback), this is not only highly event-loop specific, but
1340also not in any way wrapped by this module, as this is the job of the main
1341program.
1342
1343The pure perl event loop simply re-throws the exception (usually
1344within C<< condvar->recv >>), the L<Event> and L<EV> modules call C<<
1345$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1346so on.
1347
1348=head1 ENVIRONMENT VARIABLES
1349
1350The following environment variables are used by this module or its
1351submodules:
1352
1353=over 4
1354
1355=item C<PERL_ANYEVENT_VERBOSE>
1356
1357By default, AnyEvent will be completely silent except in fatal
1358conditions. You can set this environment variable to make AnyEvent more
1359talkative.
1360
1361When set to C<1> or higher, causes AnyEvent to warn about unexpected
1362conditions, such as not being able to load the event model specified by
1363C<PERL_ANYEVENT_MODEL>.
1364
1365When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1366model it chooses.
1367
1368=item C<PERL_ANYEVENT_STRICT>
1369
1370AnyEvent does not do much argument checking by default, as thorough
1371argument checking is very costly. Setting this variable to a true value
1372will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1373check the arguments passed to most method calls. If it finds any problems
1374it will croak.
1375
1376In other words, enables "strict" mode.
1377
1378Unlike C<use strict>, it is definitely recommended ot keep it off in
1379production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while
1380developing programs can be very useful, however.
1381
1382=item C<PERL_ANYEVENT_MODEL>
1383
1384This can be used to specify the event model to be used by AnyEvent, before
1385auto detection and -probing kicks in. It must be a string consisting
1386entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1387and the resulting module name is loaded and if the load was successful,
1388used as event model. If it fails to load AnyEvent will proceed with
1389auto detection and -probing.
1390
1391This functionality might change in future versions.
1392
1393For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1394could start your program like this:
1395
1396 PERL_ANYEVENT_MODEL=Perl perl ...
1397
1398=item C<PERL_ANYEVENT_PROTOCOLS>
1399
1400Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1401for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1402of auto probing).
1403
1404Must be set to a comma-separated list of protocols or address families,
1405current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1406used, and preference will be given to protocols mentioned earlier in the
1407list.
1408
1409This variable can effectively be used for denial-of-service attacks
1410against local programs (e.g. when setuid), although the impact is likely
1411small, as the program has to handle conenction and other failures anyways.
1412
1413Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1414but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1415- only support IPv4, never try to resolve or contact IPv6
1416addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1417IPv6, but prefer IPv6 over IPv4.
1418
1419=item C<PERL_ANYEVENT_EDNS0>
1420
1421Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1422for DNS. This extension is generally useful to reduce DNS traffic, but
1423some (broken) firewalls drop such DNS packets, which is why it is off by
1424default.
1425
1426Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1427EDNS0 in its DNS requests.
1428
1429=item C<PERL_ANYEVENT_MAX_FORKS>
1430
1431The maximum number of child processes that C<AnyEvent::Util::fork_call>
1432will create in parallel.
1433
1434=back
628 1435
629=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1436=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
630 1437
631This is an advanced topic that you do not normally need to use AnyEvent in 1438This is an advanced topic that you do not normally need to use AnyEvent in
632a module. This section is only of use to event loop authors who want to 1439a module. This section is only of use to event loop authors who want to
667I<rxvt-unicode> also cheats a bit by not providing blocking access to 1474I<rxvt-unicode> also cheats a bit by not providing blocking access to
668condition variables: code blocking while waiting for a condition will 1475condition variables: code blocking while waiting for a condition will
669C<die>. This still works with most modules/usages, and blocking calls must 1476C<die>. This still works with most modules/usages, and blocking calls must
670not be done in an interactive application, so it makes sense. 1477not be done in an interactive application, so it makes sense.
671 1478
672=head1 ENVIRONMENT VARIABLES
673
674The following environment variables are used by this module:
675
676=over 4
677
678=item C<PERL_ANYEVENT_VERBOSE>
679
680By default, AnyEvent will be completely silent except in fatal
681conditions. You can set this environment variable to make AnyEvent more
682talkative.
683
684When set to C<1> or higher, causes AnyEvent to warn about unexpected
685conditions, such as not being able to load the event model specified by
686C<PERL_ANYEVENT_MODEL>.
687
688When set to C<2> or higher, cause AnyEvent to report to STDERR which event
689model it chooses.
690
691=item C<PERL_ANYEVENT_MODEL>
692
693This can be used to specify the event model to be used by AnyEvent, before
694autodetection and -probing kicks in. It must be a string consisting
695entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
696and the resulting module name is loaded and if the load was successful,
697used as event model. If it fails to load AnyEvent will proceed with
698autodetection and -probing.
699
700This functionality might change in future versions.
701
702For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
703could start your program like this:
704
705 PERL_ANYEVENT_MODEL=Perl perl ...
706
707=back
708
709=head1 EXAMPLE PROGRAM 1479=head1 EXAMPLE PROGRAM
710 1480
711The following program uses an IO watcher to read data from STDIN, a timer 1481The following program uses an I/O watcher to read data from STDIN, a timer
712to display a message once per second, and a condition variable to quit the 1482to display a message once per second, and a condition variable to quit the
713program when the user enters quit: 1483program when the user enters quit:
714 1484
715 use AnyEvent; 1485 use AnyEvent;
716 1486
721 poll => 'r', 1491 poll => 'r',
722 cb => sub { 1492 cb => sub {
723 warn "io event <$_[0]>\n"; # will always output <r> 1493 warn "io event <$_[0]>\n"; # will always output <r>
724 chomp (my $input = <STDIN>); # read a line 1494 chomp (my $input = <STDIN>); # read a line
725 warn "read: $input\n"; # output what has been read 1495 warn "read: $input\n"; # output what has been read
726 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1496 $cv->send if $input =~ /^q/i; # quit program if /^q/i
727 }, 1497 },
728 ); 1498 );
729 1499
730 my $time_watcher; # can only be used once 1500 my $time_watcher; # can only be used once
731 1501
736 }); 1506 });
737 } 1507 }
738 1508
739 new_timer; # create first timer 1509 new_timer; # create first timer
740 1510
741 $cv->wait; # wait until user enters /^q/i 1511 $cv->recv; # wait until user enters /^q/i
742 1512
743=head1 REAL-WORLD EXAMPLE 1513=head1 REAL-WORLD EXAMPLE
744 1514
745Consider the L<Net::FCP> module. It features (among others) the following 1515Consider the L<Net::FCP> module. It features (among others) the following
746API calls, which are to freenet what HTTP GET requests are to http: 1516API calls, which are to freenet what HTTP GET requests are to http:
796 syswrite $txn->{fh}, $txn->{request} 1566 syswrite $txn->{fh}, $txn->{request}
797 or die "connection or write error"; 1567 or die "connection or write error";
798 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1568 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
799 1569
800Again, C<fh_ready_r> waits till all data has arrived, and then stores the 1570Again, C<fh_ready_r> waits till all data has arrived, and then stores the
801result and signals any possible waiters that the request ahs finished: 1571result and signals any possible waiters that the request has finished:
802 1572
803 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1573 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
804 1574
805 if (end-of-file or data complete) { 1575 if (end-of-file or data complete) {
806 $txn->{result} = $txn->{buf}; 1576 $txn->{result} = $txn->{buf};
807 $txn->{finished}->broadcast; 1577 $txn->{finished}->send;
808 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1578 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
809 } 1579 }
810 1580
811The C<result> method, finally, just waits for the finished signal (if the 1581The C<result> method, finally, just waits for the finished signal (if the
812request was already finished, it doesn't wait, of course, and returns the 1582request was already finished, it doesn't wait, of course, and returns the
813data: 1583data:
814 1584
815 $txn->{finished}->wait; 1585 $txn->{finished}->recv;
816 return $txn->{result}; 1586 return $txn->{result};
817 1587
818The actual code goes further and collects all errors (C<die>s, exceptions) 1588The actual code goes further and collects all errors (C<die>s, exceptions)
819that occured during request processing. The C<result> method detects 1589that occurred during request processing. The C<result> method detects
820whether an exception as thrown (it is stored inside the $txn object) 1590whether an exception as thrown (it is stored inside the $txn object)
821and just throws the exception, which means connection errors and other 1591and just throws the exception, which means connection errors and other
822problems get reported tot he code that tries to use the result, not in a 1592problems get reported tot he code that tries to use the result, not in a
823random callback. 1593random callback.
824 1594
855 1625
856 my $quit = AnyEvent->condvar; 1626 my $quit = AnyEvent->condvar;
857 1627
858 $fcp->txn_client_get ($url)->cb (sub { 1628 $fcp->txn_client_get ($url)->cb (sub {
859 ... 1629 ...
860 $quit->broadcast; 1630 $quit->send;
861 }); 1631 });
862 1632
863 $quit->wait; 1633 $quit->recv;
864 1634
865 1635
866=head1 BENCHMARK 1636=head1 BENCHMARKS
867 1637
868To give you an idea of the performance and overheads that AnyEvent adds 1638To give you an idea of the performance and overheads that AnyEvent adds
869over the backends directly, here is a benchmark of various supported event 1639over the event loops themselves and to give you an impression of the speed
870models natively and with anyevent. The benchmark creates a lot of timers 1640of various event loops I prepared some benchmarks.
871(with a zero timeout) and io events (watching STDOUT, a pty, to become 1641
1642=head2 BENCHMARKING ANYEVENT OVERHEAD
1643
1644Here is a benchmark of various supported event models used natively and
1645through AnyEvent. The benchmark creates a lot of timers (with a zero
1646timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
872writable), lets them fire exactly once and destroys them again. 1647which it is), lets them fire exactly once and destroys them again.
873 1648
874Explanation of the fields: 1649Source code for this benchmark is found as F<eg/bench> in the AnyEvent
1650distribution.
875 1651
1652=head3 Explanation of the columns
1653
876I<watcher> is the number of event watchers created/destroyed. Sicne 1654I<watcher> is the number of event watchers created/destroyed. Since
877different event models have vastly different performance each backend was 1655different event models feature vastly different performances, each event
878handed a number of watchers so that overall runtime is acceptable and 1656loop was given a number of watchers so that overall runtime is acceptable
879similar to all backends (and keep them from crashing). 1657and similar between tested event loop (and keep them from crashing): Glib
1658would probably take thousands of years if asked to process the same number
1659of watchers as EV in this benchmark.
880 1660
881I<bytes> is the number of bytes (as measured by resident set size) used by 1661I<bytes> is the number of bytes (as measured by the resident set size,
882each watcher. 1662RSS) consumed by each watcher. This method of measuring captures both C
1663and Perl-based overheads.
883 1664
884I<create> is the time, in microseconds, to create a single watcher. 1665I<create> is the time, in microseconds (millionths of seconds), that it
1666takes to create a single watcher. The callback is a closure shared between
1667all watchers, to avoid adding memory overhead. That means closure creation
1668and memory usage is not included in the figures.
885 1669
886I<invoke> is the time, in microseconds, used to invoke a simple callback 1670I<invoke> is the time, in microseconds, used to invoke a simple
887that simply counts down. 1671callback. The callback simply counts down a Perl variable and after it was
1672invoked "watcher" times, it would C<< ->send >> a condvar once to
1673signal the end of this phase.
888 1674
889I<destroy> is the time, in microseconds, to destroy a single watcher. 1675I<destroy> is the time, in microseconds, that it takes to destroy a single
1676watcher.
890 1677
1678=head3 Results
1679
891 name watcher bytes create invoke destroy comment 1680 name watchers bytes create invoke destroy comment
892 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1681 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
893 EV/Any 100000 610 3.52 0.91 0.75 1682 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
894 CoroEV/Any 100000 610 3.49 0.92 0.75 coroutines + Coro::Signal 1683 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
895 Perl/Any 10000 654 4.64 1.22 0.77 pure perl implementation 1684 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
896 Event/Event 10000 523 28.05 21.38 5.22 Event native interface 1685 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
897 Event/Any 10000 943 34.43 20.48 1.39 1686 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
898 Glib/Any 16000 1357 96.99 12.55 55.51 quadratic behaviour 1687 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
899 Tk/Any 2000 1855 27.01 66.61 14.03 SEGV with >> 2000 watchers 1688 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
900 POE/Select 2000 6343 94.69 807.65 562.69 POE::Loop::Select
901 POE/Event 2000 6644 108.15 768.19 14.33 POE::Loop::Event 1689 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1690 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
902 1691
903Discussion: The benchmark does I<not> bench scalability of the 1692=head3 Discussion
1693
1694The benchmark does I<not> measure scalability of the event loop very
904backend. For example a select-based backend (such as the pureperl one) can 1695well. For example, a select-based event loop (such as the pure perl one)
905never compete with a backend using epoll. In this benchmark, only a single 1696can never compete with an event loop that uses epoll when the number of
906filehandle is used. 1697file descriptors grows high. In this benchmark, all events become ready at
1698the same time, so select/poll-based implementations get an unnatural speed
1699boost.
907 1700
1701Also, note that the number of watchers usually has a nonlinear effect on
1702overall speed, that is, creating twice as many watchers doesn't take twice
1703the time - usually it takes longer. This puts event loops tested with a
1704higher number of watchers at a disadvantage.
1705
1706To put the range of results into perspective, consider that on the
1707benchmark machine, handling an event takes roughly 1600 CPU cycles with
1708EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU
1709cycles with POE.
1710
908EV is the sole leader regarding speed and memory use, which are both 1711C<EV> is the sole leader regarding speed and memory use, which are both
909maximal/minimal. Even when going through AnyEvent, there is only one event 1712maximal/minimal, respectively. Even when going through AnyEvent, it uses
910loop that uses less memory (the Event module natively), and no faster 1713far less memory than any other event loop and is still faster than Event
911event model. 1714natively.
912 1715
913The pure perl implementation is hit in a few sweet spots (both the 1716The pure perl implementation is hit in a few sweet spots (both the
914zero timeout and the use of a single fd hit optimisations in the perl 1717constant timeout and the use of a single fd hit optimisations in the perl
915interpreter and the backend itself), but it shows that it adds very little 1718interpreter and the backend itself). Nevertheless this shows that it
916overhead in itself. Like any select-based backend it's performance becomes 1719adds very little overhead in itself. Like any select-based backend its
917really bad with lots of file descriptors. 1720performance becomes really bad with lots of file descriptors (and few of
1721them active), of course, but this was not subject of this benchmark.
918 1722
919The Event module has a relatively high setup and callback invocation cost, 1723The C<Event> module has a relatively high setup and callback invocation
920but overall scores on the third place. 1724cost, but overall scores in on the third place.
921 1725
922Glib has a little higher memory cost, a bit fster callback invocation and 1726C<Glib>'s memory usage is quite a bit higher, but it features a
923has a similar speed as Event. 1727faster callback invocation and overall ends up in the same class as
1728C<Event>. However, Glib scales extremely badly, doubling the number of
1729watchers increases the processing time by more than a factor of four,
1730making it completely unusable when using larger numbers of watchers
1731(note that only a single file descriptor was used in the benchmark, so
1732inefficiencies of C<poll> do not account for this).
924 1733
925The Tk backend works relatively well, the fact that it crashes with 1734The C<Tk> adaptor works relatively well. The fact that it crashes with
926more than 2000 watchers is a big setback, however, as correctness takes 1735more than 2000 watchers is a big setback, however, as correctness takes
927precedence over speed. 1736precedence over speed. Nevertheless, its performance is surprising, as the
1737file descriptor is dup()ed for each watcher. This shows that the dup()
1738employed by some adaptors is not a big performance issue (it does incur a
1739hidden memory cost inside the kernel which is not reflected in the figures
1740above).
928 1741
929POE, regardless of backend (wether it's pure perl select backend or the 1742C<POE>, regardless of underlying event loop (whether using its pure perl
930Event backend) shows abysmal performance and memory usage: Watchers use 1743select-based backend or the Event module, the POE-EV backend couldn't
931almost 30 times as much memory as EV watchers, and 10 times as much memory 1744be tested because it wasn't working) shows abysmal performance and
932as both Event or EV via AnyEvent. 1745memory usage with AnyEvent: Watchers use almost 30 times as much memory
1746as EV watchers, and 10 times as much memory as Event (the high memory
1747requirements are caused by requiring a session for each watcher). Watcher
1748invocation speed is almost 900 times slower than with AnyEvent's pure perl
1749implementation.
933 1750
1751The design of the POE adaptor class in AnyEvent can not really account
1752for the performance issues, though, as session creation overhead is
1753small compared to execution of the state machine, which is coded pretty
1754optimally within L<AnyEvent::Impl::POE> (and while everybody agrees that
1755using multiple sessions is not a good approach, especially regarding
1756memory usage, even the author of POE could not come up with a faster
1757design).
1758
1759=head3 Summary
1760
1761=over 4
1762
934Summary: using EV through AnyEvent is faster than any other event 1763=item * Using EV through AnyEvent is faster than any other event loop
935loop. The overhead AnyEvent adds can be very small, and you should avoid 1764(even when used without AnyEvent), but most event loops have acceptable
936POE like the plague if you want performance or reasonable memory usage. 1765performance with or without AnyEvent.
1766
1767=item * The overhead AnyEvent adds is usually much smaller than the overhead of
1768the actual event loop, only with extremely fast event loops such as EV
1769adds AnyEvent significant overhead.
1770
1771=item * You should avoid POE like the plague if you want performance or
1772reasonable memory usage.
1773
1774=back
1775
1776=head2 BENCHMARKING THE LARGE SERVER CASE
1777
1778This benchmark actually benchmarks the event loop itself. It works by
1779creating a number of "servers": each server consists of a socket pair, a
1780timeout watcher that gets reset on activity (but never fires), and an I/O
1781watcher waiting for input on one side of the socket. Each time the socket
1782watcher reads a byte it will write that byte to a random other "server".
1783
1784The effect is that there will be a lot of I/O watchers, only part of which
1785are active at any one point (so there is a constant number of active
1786fds for each loop iteration, but which fds these are is random). The
1787timeout is reset each time something is read because that reflects how
1788most timeouts work (and puts extra pressure on the event loops).
1789
1790In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
1791(1%) are active. This mirrors the activity of large servers with many
1792connections, most of which are idle at any one point in time.
1793
1794Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
1795distribution.
1796
1797=head3 Explanation of the columns
1798
1799I<sockets> is the number of sockets, and twice the number of "servers" (as
1800each server has a read and write socket end).
1801
1802I<create> is the time it takes to create a socket pair (which is
1803nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1804
1805I<request>, the most important value, is the time it takes to handle a
1806single "request", that is, reading the token from the pipe and forwarding
1807it to another server. This includes deleting the old timeout and creating
1808a new one that moves the timeout into the future.
1809
1810=head3 Results
1811
1812 name sockets create request
1813 EV 20000 69.01 11.16
1814 Perl 20000 73.32 35.87
1815 Event 20000 212.62 257.32
1816 Glib 20000 651.16 1896.30
1817 POE 20000 349.67 12317.24 uses POE::Loop::Event
1818
1819=head3 Discussion
1820
1821This benchmark I<does> measure scalability and overall performance of the
1822particular event loop.
1823
1824EV is again fastest. Since it is using epoll on my system, the setup time
1825is relatively high, though.
1826
1827Perl surprisingly comes second. It is much faster than the C-based event
1828loops Event and Glib.
1829
1830Event suffers from high setup time as well (look at its code and you will
1831understand why). Callback invocation also has a high overhead compared to
1832the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event
1833uses select or poll in basically all documented configurations.
1834
1835Glib is hit hard by its quadratic behaviour w.r.t. many watchers. It
1836clearly fails to perform with many filehandles or in busy servers.
1837
1838POE is still completely out of the picture, taking over 1000 times as long
1839as EV, and over 100 times as long as the Perl implementation, even though
1840it uses a C-based event loop in this case.
1841
1842=head3 Summary
1843
1844=over 4
1845
1846=item * The pure perl implementation performs extremely well.
1847
1848=item * Avoid Glib or POE in large projects where performance matters.
1849
1850=back
1851
1852=head2 BENCHMARKING SMALL SERVERS
1853
1854While event loops should scale (and select-based ones do not...) even to
1855large servers, most programs we (or I :) actually write have only a few
1856I/O watchers.
1857
1858In this benchmark, I use the same benchmark program as in the large server
1859case, but it uses only eight "servers", of which three are active at any
1860one time. This should reflect performance for a small server relatively
1861well.
1862
1863The columns are identical to the previous table.
1864
1865=head3 Results
1866
1867 name sockets create request
1868 EV 16 20.00 6.54
1869 Perl 16 25.75 12.62
1870 Event 16 81.27 35.86
1871 Glib 16 32.63 15.48
1872 POE 16 261.87 276.28 uses POE::Loop::Event
1873
1874=head3 Discussion
1875
1876The benchmark tries to test the performance of a typical small
1877server. While knowing how various event loops perform is interesting, keep
1878in mind that their overhead in this case is usually not as important, due
1879to the small absolute number of watchers (that is, you need efficiency and
1880speed most when you have lots of watchers, not when you only have a few of
1881them).
1882
1883EV is again fastest.
1884
1885Perl again comes second. It is noticeably faster than the C-based event
1886loops Event and Glib, although the difference is too small to really
1887matter.
1888
1889POE also performs much better in this case, but is is still far behind the
1890others.
1891
1892=head3 Summary
1893
1894=over 4
1895
1896=item * C-based event loops perform very well with small number of
1897watchers, as the management overhead dominates.
1898
1899=back
1900
1901
1902=head1 SIGNALS
1903
1904AnyEvent currently installs handlers for these signals:
1905
1906=over 4
1907
1908=item SIGCHLD
1909
1910A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
1911emulation for event loops that do not support them natively. Also, some
1912event loops install a similar handler.
1913
1914=item SIGPIPE
1915
1916A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
1917when AnyEvent gets loaded.
1918
1919The rationale for this is that AnyEvent users usually do not really depend
1920on SIGPIPE delivery (which is purely an optimisation for shell use, or
1921badly-written programs), but C<SIGPIPE> can cause spurious and rare
1922program exits as a lot of people do not expect C<SIGPIPE> when writing to
1923some random socket.
1924
1925The rationale for installing a no-op handler as opposed to ignoring it is
1926that this way, the handler will be restored to defaults on exec.
1927
1928Feel free to install your own handler, or reset it to defaults.
1929
1930=back
1931
1932=cut
1933
1934$SIG{PIPE} = sub { }
1935 unless defined $SIG{PIPE};
937 1936
938 1937
939=head1 FORK 1938=head1 FORK
940 1939
941Most event libraries are not fork-safe. The ones who are usually are 1940Most event libraries are not fork-safe. The ones who are usually are
942because they are so inefficient. Only L<EV> is fully fork-aware. 1941because they rely on inefficient but fork-safe C<select> or C<poll>
1942calls. Only L<EV> is fully fork-aware.
943 1943
944If you have to fork, you must either do so I<before> creating your first 1944If you have to fork, you must either do so I<before> creating your first
945watcher OR you must not use AnyEvent at all in the child. 1945watcher OR you must not use AnyEvent at all in the child.
946 1946
947 1947
955specified in the variable. 1955specified in the variable.
956 1956
957You can make AnyEvent completely ignore this variable by deleting it 1957You can make AnyEvent completely ignore this variable by deleting it
958before the first watcher gets created, e.g. with a C<BEGIN> block: 1958before the first watcher gets created, e.g. with a C<BEGIN> block:
959 1959
960 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1960 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
961 1961
962 use AnyEvent; 1962 use AnyEvent;
1963
1964Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1965be used to probe what backend is used and gain other information (which is
1966probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and
1967$ENV{PERL_ANYEGENT_STRICT}.
1968
1969
1970=head1 BUGS
1971
1972Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
1973to work around. If you suffer from memleaks, first upgrade to Perl 5.10
1974and check wether the leaks still show up. (Perl 5.10.0 has other annoying
1975memleaks, such as leaking on C<map> and C<grep> but it is usually not as
1976pronounced).
963 1977
964 1978
965=head1 SEE ALSO 1979=head1 SEE ALSO
966 1980
967Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1981Utility functions: L<AnyEvent::Util>.
968L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>, 1982
1983Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
969L<Event::Lib>, L<Qt>, L<POE>. 1984L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
970 1985
971Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1986Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
972L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1987L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
973L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1988L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
974L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. 1989L<AnyEvent::Impl::POE>.
975 1990
1991Non-blocking file handles, sockets, TCP clients and
1992servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1993
1994Asynchronous DNS: L<AnyEvent::DNS>.
1995
1996Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1997
976Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1998Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
977 1999
978 2000
979=head1 AUTHOR 2001=head1 AUTHOR
980 2002
981 Marc Lehmann <schmorp@schmorp.de> 2003 Marc Lehmann <schmorp@schmorp.de>
982 http://home.schmorp.de/ 2004 http://home.schmorp.de/
983 2005
984=cut 2006=cut
985 2007
9861 20081
987 2009

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines