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.143 by root, Wed May 28 23:57:38 2008 UTC vs.
Revision 1.266 by root, Thu Jul 30 03:41:56 2009 UTC

1=head1 => NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - the DBI of event loop programming
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops 5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt
6and POE are various supported event loops/environments.
6 7
7=head1 SYNOPSIS 8=head1 SYNOPSIS
8 9
9 use AnyEvent; 10 use AnyEvent;
10 11
12 # file descriptor readable
11 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 13 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
14
15 # one-shot or repeating timers
16 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
17 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
18
19 print AnyEvent->now; # prints current event loop time
20 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
21
22 # POSIX signal
23 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
24
25 # child process exit
26 my $w = AnyEvent->child (pid => $pid, cb => sub {
27 my ($pid, $status) = @_;
12 ... 28 ...
13 }); 29 });
14 30
15 my $w = AnyEvent->timer (after => $seconds, cb => sub { 31 # called when event loop idle (if applicable)
16 ... 32 my $w = AnyEvent->idle (cb => sub { ... });
17 });
18 33
19 my $w = AnyEvent->condvar; # stores whether a condition was flagged 34 my $w = AnyEvent->condvar; # stores whether a condition was flagged
20 $w->send; # wake up current and all future recv's 35 $w->send; # wake up current and all future recv's
21 $w->recv; # enters "main loop" till $condvar gets ->send 36 $w->recv; # enters "main loop" till $condvar gets ->send
37 # use a condvar in callback mode:
38 $w->cb (sub { $_[0]->recv });
39
40=head1 INTRODUCTION/TUTORIAL
41
42This manpage is mainly a reference manual. If you are interested
43in a tutorial or some gentle introduction, have a look at the
44L<AnyEvent::Intro> manpage.
45
46=head1 SUPPORT
47
48There is a mailinglist for discussing all things AnyEvent, and an IRC
49channel, too.
50
51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
52Repository>, at L<http://anyevent.schmorp.de>, for more info.
22 53
23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24 55
25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26nowadays. So what is different about AnyEvent? 57nowadays. So what is different about AnyEvent?
27 58
28Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of 59Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
29policy> and AnyEvent is I<small and efficient>. 60policy> and AnyEvent is I<small and efficient>.
30 61
31First and foremost, I<AnyEvent is not an event model> itself, it only 62First 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 63interfaces to whatever event model the main program happens to use, in a
33pragmatic way. For event models and certain classes of immortals alike, 64pragmatic way. For event models and certain classes of immortals alike,
34the statement "there can only be one" is a bitter reality: In general, 65the 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 66only one event loop can be active at the same time in a process. AnyEvent
36helps hiding the differences between those event loops. 67cannot change this, but it can hide the differences between those event
68loops.
37 69
38The goal of AnyEvent is to offer module authors the ability to do event 70The 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 71programming (waiting for I/O or timer events) without subscribing to a
40religion, a way of living, and most importantly: without forcing your 72religion, a way of living, and most importantly: without forcing your
41module users into the same thing by forcing them to use the same event 73module users into the same thing by forcing them to use the same event
42model you use. 74model you use.
43 75
44For modules like POE or IO::Async (which is a total misnomer as it is 76For 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 77actually 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 78like 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 79cannot use anything else, as they are simply incompatible to everything
48isn't itself. What's worse, all the potential users of your module are 80that isn't them. What's worse, all the potential users of your
49I<also> forced to use the same event loop you use. 81module are I<also> forced to use the same event loop you use.
50 82
51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 83AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
52fine. AnyEvent + Tk works fine etc. etc. but none of these work together 84fine. 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 85with 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, 86your 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 87too. But if your module uses AnyEvent, it works transparently with all
56event models it supports (including stuff like POE and IO::Async, as long 88event 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 89use one of the supported event loops. It is trivial to add new event loops
58event loops to AnyEvent, too, so it is future-proof). 90to AnyEvent, too, so it is future-proof).
59 91
60In addition to being free of having to use I<the one and only true event 92In 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 93model>, AnyEvent also is free of bloat and policy: with POE or similar
62modules, you get an enormous amount of code and strict rules you have to 94modules, 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 95follow. AnyEvent, on the other hand, is lean and up to the point, by only
121These watchers are normal Perl objects with normal Perl lifetime. After 153These watchers are normal Perl objects with normal Perl lifetime. After
122creating a watcher it will immediately "watch" for events and invoke the 154creating a watcher it will immediately "watch" for events and invoke the
123callback when the event occurs (of course, only when the event model 155callback when the event occurs (of course, only when the event model
124is in control). 156is in control).
125 157
158Note that B<callbacks must not permanently change global variables>
159potentially in use by the event loop (such as C<$_> or C<$[>) and that B<<
160callbacks must not C<die> >>. The former is good programming practise in
161Perl and the latter stems from the fact that exception handling differs
162widely between event loops.
163
126To disable the watcher you have to destroy it (e.g. by setting the 164To disable the watcher you have to destroy it (e.g. by setting the
127variable you store it in to C<undef> or otherwise deleting all references 165variable you store it in to C<undef> or otherwise deleting all references
128to it). 166to it).
129 167
130All watchers are created by calling a method on the C<AnyEvent> class. 168All watchers are created by calling a method on the C<AnyEvent> class.
132Many watchers either are used with "recursion" (repeating timers for 170Many watchers either are used with "recursion" (repeating timers for
133example), or need to refer to their watcher object in other ways. 171example), or need to refer to their watcher object in other ways.
134 172
135An any way to achieve that is this pattern: 173An any way to achieve that is this pattern:
136 174
137 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 175 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
138 # you can use $w here, for example to undef it 176 # you can use $w here, for example to undef it
139 undef $w; 177 undef $w;
140 }); 178 });
141 179
142Note that C<my $w; $w => combination. This is necessary because in Perl, 180Note that C<my $w; $w => combination. This is necessary because in Perl,
143my variables are only visible after the statement in which they are 181my variables are only visible after the statement in which they are
144declared. 182declared.
145 183
146=head2 I/O WATCHERS 184=head2 I/O WATCHERS
147 185
186 $w = AnyEvent->io (
187 fh => <filehandle_or_fileno>,
188 poll => <"r" or "w">,
189 cb => <callback>,
190 );
191
148You can create an I/O watcher by calling the C<< AnyEvent->io >> method 192You can create an I/O watcher by calling the C<< AnyEvent->io >> method
149with the following mandatory key-value pairs as arguments: 193with the following mandatory key-value pairs as arguments:
150 194
151C<fh> the Perl I<file handle> (I<not> file descriptor) to watch 195C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
196for events (AnyEvent might or might not keep a reference to this file
197handle). Note that only file handles pointing to things for which
198non-blocking operation makes sense are allowed. This includes sockets,
199most character devices, pipes, fifos and so on, but not for example files
200or block devices.
201
152for events. C<poll> must be a string that is either C<r> or C<w>, 202C<poll> must be a string that is either C<r> or C<w>, which creates a
153which creates a watcher waiting for "r"eadable or "w"ritable events, 203watcher waiting for "r"eadable or "w"ritable events, respectively.
204
154respectively. C<cb> is the callback to invoke each time the file handle 205C<cb> is the callback to invoke each time the file handle becomes ready.
155becomes ready.
156 206
157Although the callback might get passed parameters, their value and 207Although the callback might get passed parameters, their value and
158presence is undefined and you cannot rely on them. Portable AnyEvent 208presence is undefined and you cannot rely on them. Portable AnyEvent
159callbacks cannot use arguments passed to I/O watcher callbacks. 209callbacks cannot use arguments passed to I/O watcher callbacks.
160 210
164 214
165Some event loops issue spurious readyness notifications, so you should 215Some event loops issue spurious readyness notifications, so you should
166always use non-blocking calls when reading/writing from/to your file 216always use non-blocking calls when reading/writing from/to your file
167handles. 217handles.
168 218
169Example:
170
171 # wait for readability of STDIN, then read a line and disable the watcher 219Example: wait for readability of STDIN, then read a line and disable the
220watcher.
221
172 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 222 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
173 chomp (my $input = <STDIN>); 223 chomp (my $input = <STDIN>);
174 warn "read: $input\n"; 224 warn "read: $input\n";
175 undef $w; 225 undef $w;
176 }); 226 });
177 227
178=head2 TIME WATCHERS 228=head2 TIME WATCHERS
179 229
230 $w = AnyEvent->timer (after => <seconds>, cb => <callback>);
231
232 $w = AnyEvent->timer (
233 after => <fractional_seconds>,
234 interval => <fractional_seconds>,
235 cb => <callback>,
236 );
237
180You can create a time watcher by calling the C<< AnyEvent->timer >> 238You can create a time watcher by calling the C<< AnyEvent->timer >>
181method with the following mandatory arguments: 239method with the following mandatory arguments:
182 240
183C<after> specifies after how many seconds (fractional values are 241C<after> specifies after how many seconds (fractional values are
184supported) the callback should be invoked. C<cb> is the callback to invoke 242supported) the callback should be invoked. C<cb> is the callback to invoke
186 244
187Although the callback might get passed parameters, their value and 245Although the callback might get passed parameters, their value and
188presence is undefined and you cannot rely on them. Portable AnyEvent 246presence is undefined and you cannot rely on them. Portable AnyEvent
189callbacks cannot use arguments passed to time watcher callbacks. 247callbacks cannot use arguments passed to time watcher callbacks.
190 248
191The timer callback will be invoked at most once: if you want a repeating 249The callback will normally be invoked once only. If you specify another
192timer you have to create a new watcher (this is a limitation by both Tk 250parameter, C<interval>, as a strictly positive number (> 0), then the
193and Glib). 251callback will be invoked regularly at that interval (in fractional
252seconds) after the first invocation. If C<interval> is specified with a
253false value, then it is treated as if it were missing.
194 254
195Example: 255The callback will be rescheduled before invoking the callback, but no
256attempt is done to avoid timer drift in most backends, so the interval is
257only approximate.
196 258
197 # fire an event after 7.7 seconds 259Example: fire an event after 7.7 seconds.
260
198 my $w = AnyEvent->timer (after => 7.7, cb => sub { 261 my $w = AnyEvent->timer (after => 7.7, cb => sub {
199 warn "timeout\n"; 262 warn "timeout\n";
200 }); 263 });
201 264
202 # to cancel the timer: 265 # to cancel the timer:
203 undef $w; 266 undef $w;
204 267
205Example 2:
206
207 # fire an event after 0.5 seconds, then roughly every second 268Example 2: fire an event after 0.5 seconds, then roughly every second.
208 my $w;
209 269
210 my $cb = sub {
211 # cancel the old timer while creating a new one
212 $w = AnyEvent->timer (after => 1, cb => $cb); 270 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
271 warn "timeout\n";
213 }; 272 };
214
215 # start the "loop" by creating the first watcher
216 $w = AnyEvent->timer (after => 0.5, cb => $cb);
217 273
218=head3 TIMING ISSUES 274=head3 TIMING ISSUES
219 275
220There are two ways to handle timers: based on real time (relative, "fire 276There are two ways to handle timers: based on real time (relative, "fire
221in 10 seconds") and based on wallclock time (absolute, "fire at 12 277in 10 seconds") and based on wallclock time (absolute, "fire at 12
243 299
244This returns the "current wallclock time" as a fractional number of 300This returns the "current wallclock time" as a fractional number of
245seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time> 301seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
246return, and the result is guaranteed to be compatible with those). 302return, and the result is guaranteed to be compatible with those).
247 303
248It progresses independently of any event loop processing. 304It progresses independently of any event loop processing, i.e. each call
249 305will check the system clock, which usually gets updated frequently.
250In almost all cases (in all cases if you don't care), this is the function
251to call when you want to know the current time.
252 306
253=item AnyEvent->now 307=item AnyEvent->now
254 308
255This also returns the "current wallclock time", but unlike C<time>, above, 309This also returns the "current wallclock time", but unlike C<time>, above,
256this value might change only once per event loop iteration, depending on 310this value might change only once per event loop iteration, depending on
257the event loop (most return the same time as C<time>, above). This is the 311the event loop (most return the same time as C<time>, above). This is the
258time that AnyEvent timers get scheduled against. 312time that AnyEvent's timers get scheduled against.
313
314I<In almost all cases (in all cases if you don't care), this is the
315function to call when you want to know the current time.>
316
317This function is also often faster then C<< AnyEvent->time >>, and
318thus the preferred method if you want some timestamp (for example,
319L<AnyEvent::Handle> uses this to update it's activity timeouts).
320
321The rest of this section is only of relevance if you try to be very exact
322with your timing, you can skip it without bad conscience.
259 323
260For a practical example of when these times differ, consider L<Event::Lib> 324For a practical example of when these times differ, consider L<Event::Lib>
261and L<EV> and the following set-up: 325and L<EV> and the following set-up:
262 326
263The event loop is running and has just invoked one of your callback at 327The event loop is running and has just invoked one of your callback at
268 332
269With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will 333With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
270both return C<501>, because that is the current time, and the timer will 334both return C<501>, because that is the current time, and the timer will
271be scheduled to fire at time=504 (C<501> + C<3>). 335be scheduled to fire at time=504 (C<501> + C<3>).
272 336
273With L<EV>m C<< AnyEvent->time >> returns C<501> (as that is the current 337With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
274time), but C<< AnyEvent->now >> returns C<500>, as that is the time the 338time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
275last event processing phase started. With L<EV>, your timer gets scheduled 339last event processing phase started. With L<EV>, your timer gets scheduled
276to run at time=503 (C<500> + C<3>). 340to run at time=503 (C<500> + C<3>).
277 341
278In one sense, L<Event::Lib> is more exact, as it uses the current time 342In one sense, L<Event::Lib> is more exact, as it uses the current time
279regardless of any delays introduced by event processing. However, most 343regardless of any delays introduced by event processing. However, most
280callbacks do not expect large delays in processing, so this causes a 344callbacks do not expect large delays in processing, so this causes a
281higher drift (and a lot more syscalls to get the current time). 345higher drift (and a lot more system calls to get the current time).
282 346
283In another sense, L<EV> is more exact, as your timer will be scheduled at 347In another sense, L<EV> is more exact, as your timer will be scheduled at
284the same time, regardless of how long event processing actually took. 348the same time, regardless of how long event processing actually took.
285 349
286In either case, if you care (and in most cases, you don't), then you 350In either case, if you care (and in most cases, you don't), then you
287can get whatever behaviour you want with any event loop, by taking the 351can get whatever behaviour you want with any event loop, by taking the
288difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into 352difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
289account. 353account.
290 354
355=item AnyEvent->now_update
356
357Some event loops (such as L<EV> or L<AnyEvent::Impl::Perl>) cache
358the current time for each loop iteration (see the discussion of L<<
359AnyEvent->now >>, above).
360
361When a callback runs for a long time (or when the process sleeps), then
362this "current" time will differ substantially from the real time, which
363might affect timers and time-outs.
364
365When this is the case, you can call this method, which will update the
366event loop's idea of "current time".
367
368Note that updating the time I<might> cause some events to be handled.
369
291=back 370=back
292 371
293=head2 SIGNAL WATCHERS 372=head2 SIGNAL WATCHERS
294 373
374 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
375
295You can watch for signals using a signal watcher, C<signal> is the signal 376You can watch for signals using a signal watcher, C<signal> is the signal
296I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 377I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
297be invoked whenever a signal occurs. 378callback to be invoked whenever a signal occurs.
298 379
299Although the callback might get passed parameters, their value and 380Although the callback might get passed parameters, their value and
300presence is undefined and you cannot rely on them. Portable AnyEvent 381presence is undefined and you cannot rely on them. Portable AnyEvent
301callbacks cannot use arguments passed to signal watcher callbacks. 382callbacks cannot use arguments passed to signal watcher callbacks.
302 383
304invocation, and callback invocation will be synchronous. Synchronous means 385invocation, and callback invocation will be synchronous. Synchronous means
305that it might take a while until the signal gets handled by the process, 386that it might take a while until the signal gets handled by the process,
306but it is guaranteed not to interrupt any other callbacks. 387but it is guaranteed not to interrupt any other callbacks.
307 388
308The main advantage of using these watchers is that you can share a signal 389The main advantage of using these watchers is that you can share a signal
309between multiple watchers. 390between multiple watchers, and AnyEvent will ensure that signals will not
391interrupt your program at bad times.
310 392
311This watcher might use C<%SIG>, so programs overwriting those signals 393This watcher might use C<%SIG> (depending on the event loop used),
312directly will likely not work correctly. 394so programs overwriting those signals directly will likely not work
395correctly.
313 396
314Example: exit on SIGINT 397Example: exit on SIGINT
315 398
316 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 399 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
317 400
401=head3 Signal Races, Delays and Workarounds
402
403Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
404callbacks to signals in a generic way, which is a pity, as you cannot do
405race-free signal handling in perl. AnyEvent will try to do it's best, but
406in some cases, signals will be delayed. The maximum time a signal might
407be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
408seconds). This variable can be changed only before the first signal
409watcher is created, and should be left alone otherwise. Higher values
410will cause fewer spurious wake-ups, which is better for power and CPU
411saving. All these problems can be avoided by installing the optional
412L<Async::Interrupt> module. This will not work with inherently broken
413event loops such as L<Event> or L<Event::Lib> (and not with L<POE>
414currently, as POE does it's own workaround with one-second latency). With
415those, you just have to suffer the delays.
416
318=head2 CHILD PROCESS WATCHERS 417=head2 CHILD PROCESS WATCHERS
319 418
419 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
420
320You can also watch on a child process exit and catch its exit status. 421You can also watch on a child process exit and catch its exit status.
321 422
322The child process is specified by the C<pid> argument (if set to C<0>, it 423The child process is specified by the C<pid> argument (one some backends,
323watches for any child process exit). The watcher will trigger as often 424using C<0> watches for any child process exit, on others this will
324as status change for the child are received. This works by installing a 425croak). The watcher will be triggered only when the child process has
325signal handler for C<SIGCHLD>. The callback will be called with the pid 426finished and an exit status is available, not on any trace events
326and exit status (as returned by waitpid), so unlike other watcher types, 427(stopped/continued).
327you I<can> rely on child watcher callback arguments. 428
429The callback will be called with the pid and exit status (as returned by
430waitpid), so unlike other watcher types, you I<can> rely on child watcher
431callback arguments.
432
433This watcher type works by installing a signal handler for C<SIGCHLD>,
434and since it cannot be shared, nothing else should use SIGCHLD or reap
435random child processes (waiting for specific child processes, e.g. inside
436C<system>, is just fine).
328 437
329There is a slight catch to child watchers, however: you usually start them 438There is a slight catch to child watchers, however: you usually start them
330I<after> the child process was created, and this means the process could 439I<after> the child process was created, and this means the process could
331have exited already (and no SIGCHLD will be sent anymore). 440have exited already (and no SIGCHLD will be sent anymore).
332 441
333Not all event models handle this correctly (POE doesn't), but even for 442Not all event models handle this correctly (neither POE nor IO::Async do,
443see their AnyEvent::Impl manpages for details), but even for event models
334event models that I<do> handle this correctly, they usually need to be 444that I<do> handle this correctly, they usually need to be loaded before
335loaded before the process exits (i.e. before you fork in the first place). 445the process exits (i.e. before you fork in the first place). AnyEvent's
446pure perl event loop handles all cases correctly regardless of when you
447start the watcher.
336 448
337This means you cannot create a child watcher as the very first thing in an 449This means you cannot create a child watcher as the very first
338AnyEvent program, you I<have> to create at least one watcher before you 450thing in an AnyEvent program, you I<have> to create at least one
339C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 451watcher before you C<fork> the child (alternatively, you can call
452C<AnyEvent::detect>).
453
454As most event loops do not support waiting for child events, they will be
455emulated by AnyEvent in most cases, in which the latency and race problems
456mentioned in the description of signal watchers apply.
340 457
341Example: fork a process and wait for it 458Example: fork a process and wait for it
342 459
343 my $done = AnyEvent->condvar; 460 my $done = AnyEvent->condvar;
344 461
345 my $pid = fork or exit 5; 462 my $pid = fork or exit 5;
346 463
347 my $w = AnyEvent->child ( 464 my $w = AnyEvent->child (
348 pid => $pid, 465 pid => $pid,
349 cb => sub { 466 cb => sub {
350 my ($pid, $status) = @_; 467 my ($pid, $status) = @_;
351 warn "pid $pid exited with status $status"; 468 warn "pid $pid exited with status $status";
352 $done->send; 469 $done->send;
353 }, 470 },
354 ); 471 );
355 472
356 # do something else, then wait for process exit 473 # do something else, then wait for process exit
357 $done->recv; 474 $done->recv;
475
476=head2 IDLE WATCHERS
477
478 $w = AnyEvent->idle (cb => <callback>);
479
480Sometimes there is a need to do something, but it is not so important
481to do it instantly, but only when there is nothing better to do. This
482"nothing better to do" is usually defined to be "no other events need
483attention by the event loop".
484
485Idle watchers ideally get invoked when the event loop has nothing
486better to do, just before it would block the process to wait for new
487events. Instead of blocking, the idle watcher is invoked.
488
489Most event loops unfortunately do not really support idle watchers (only
490EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
491will simply call the callback "from time to time".
492
493Example: read lines from STDIN, but only process them when the
494program is otherwise idle:
495
496 my @lines; # read data
497 my $idle_w;
498 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
499 push @lines, scalar <STDIN>;
500
501 # start an idle watcher, if not already done
502 $idle_w ||= AnyEvent->idle (cb => sub {
503 # handle only one line, when there are lines left
504 if (my $line = shift @lines) {
505 print "handled when idle: $line";
506 } else {
507 # otherwise disable the idle watcher again
508 undef $idle_w;
509 }
510 });
511 });
358 512
359=head2 CONDITION VARIABLES 513=head2 CONDITION VARIABLES
514
515 $cv = AnyEvent->condvar;
516
517 $cv->send (<list>);
518 my @res = $cv->recv;
360 519
361If you are familiar with some event loops you will know that all of them 520If you are familiar with some event loops you will know that all of them
362require you to run some blocking "loop", "run" or similar function that 521require you to run some blocking "loop", "run" or similar function that
363will actively watch for new events and call your callbacks. 522will actively watch for new events and call your callbacks.
364 523
365AnyEvent is different, it expects somebody else to run the event loop and 524AnyEvent is slightly different: it expects somebody else to run the event
366will only block when necessary (usually when told by the user). 525loop and will only block when necessary (usually when told by the user).
367 526
368The instrument to do that is called a "condition variable", so called 527The instrument to do that is called a "condition variable", so called
369because they represent a condition that must become true. 528because they represent a condition that must become true.
529
530Now is probably a good time to look at the examples further below.
370 531
371Condition variables can be created by calling the C<< AnyEvent->condvar 532Condition variables can be created by calling the C<< AnyEvent->condvar
372>> method, usually without arguments. The only argument pair allowed is 533>> method, usually without arguments. The only argument pair allowed is
373C<cb>, which specifies a callback to be called when the condition variable 534C<cb>, which specifies a callback to be called when the condition variable
374becomes true. 535becomes true, with the condition variable as the first argument (but not
536the results).
375 537
376After creation, the condition variable is "false" until it becomes "true" 538After creation, the condition variable is "false" until it becomes "true"
377by calling the C<send> method (or calling the condition variable as if it 539by calling the C<send> method (or calling the condition variable as if it
378were a callback, read about the caveats in the description for the C<< 540were a callback, read about the caveats in the description for the C<<
379->send >> method). 541->send >> method).
381Condition variables are similar to callbacks, except that you can 543Condition variables are similar to callbacks, except that you can
382optionally wait for them. They can also be called merge points - points 544optionally wait for them. They can also be called merge points - points
383in time where multiple outstanding events have been processed. And yet 545in time where multiple outstanding events have been processed. And yet
384another way to call them is transactions - each condition variable can be 546another way to call them is transactions - each condition variable can be
385used to represent a transaction, which finishes at some point and delivers 547used to represent a transaction, which finishes at some point and delivers
386a result. 548a result. And yet some people know them as "futures" - a promise to
549compute/deliver something that you can wait for.
387 550
388Condition variables are very useful to signal that something has finished, 551Condition variables are very useful to signal that something has finished,
389for example, if you write a module that does asynchronous http requests, 552for example, if you write a module that does asynchronous http requests,
390then a condition variable would be the ideal candidate to signal the 553then a condition variable would be the ideal candidate to signal the
391availability of results. The user can either act when the callback is 554availability of results. The user can either act when the callback is
425 after => 1, 588 after => 1,
426 cb => sub { $result_ready->send }, 589 cb => sub { $result_ready->send },
427 ); 590 );
428 591
429 # this "blocks" (while handling events) till the callback 592 # this "blocks" (while handling events) till the callback
430 # calls send 593 # calls -<send
431 $result_ready->recv; 594 $result_ready->recv;
432 595
433Example: wait for a timer, but take advantage of the fact that 596Example: wait for a timer, but take advantage of the fact that condition
434condition variables are also code references. 597variables are also callable directly.
435 598
436 my $done = AnyEvent->condvar; 599 my $done = AnyEvent->condvar;
437 my $delay = AnyEvent->timer (after => 5, cb => $done); 600 my $delay = AnyEvent->timer (after => 5, cb => $done);
438 $done->recv; 601 $done->recv;
602
603Example: Imagine an API that returns a condvar and doesn't support
604callbacks. This is how you make a synchronous call, for example from
605the main program:
606
607 use AnyEvent::CouchDB;
608
609 ...
610
611 my @info = $couchdb->info->recv;
612
613And this is how you would just set a callback to be called whenever the
614results are available:
615
616 $couchdb->info->cb (sub {
617 my @info = $_[0]->recv;
618 });
439 619
440=head3 METHODS FOR PRODUCERS 620=head3 METHODS FOR PRODUCERS
441 621
442These methods should only be used by the producing side, i.e. the 622These methods should only be used by the producing side, i.e. the
443code/module that eventually sends the signal. Note that it is also 623code/module that eventually sends the signal. Note that it is also
456immediately from within send. 636immediately from within send.
457 637
458Any arguments passed to the C<send> call will be returned by all 638Any arguments passed to the C<send> call will be returned by all
459future C<< ->recv >> calls. 639future C<< ->recv >> calls.
460 640
461Condition variables are overloaded so one can call them directly 641Condition variables are overloaded so one can call them directly (as if
462(as a code reference). Calling them directly is the same as calling 642they were a code reference). Calling them directly is the same as calling
463C<send>. Note, however, that many C-based event loops do not handle 643C<send>.
464overloading, so as tempting as it may be, passing a condition variable
465instead of a callback does not work. Both the pure perl and EV loops
466support overloading, however, as well as all functions that use perl to
467invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
468example).
469 644
470=item $cv->croak ($error) 645=item $cv->croak ($error)
471 646
472Similar to send, but causes all call's to C<< ->recv >> to invoke 647Similar to send, but causes all call's to C<< ->recv >> to invoke
473C<Carp::croak> with the given error message/object/scalar. 648C<Carp::croak> with the given error message/object/scalar.
474 649
475This can be used to signal any errors to the condition variable 650This can be used to signal any errors to the condition variable
476user/consumer. 651user/consumer. Doing it this way instead of calling C<croak> directly
652delays the error detetcion, but has the overwhelmign advantage that it
653diagnoses the error at the place where the result is expected, and not
654deep in some event clalback without connection to the actual code causing
655the problem.
477 656
478=item $cv->begin ([group callback]) 657=item $cv->begin ([group callback])
479 658
480=item $cv->end 659=item $cv->end
481
482These two methods are EXPERIMENTAL and MIGHT CHANGE.
483 660
484These two methods can be used to combine many transactions/events into 661These two methods can be used to combine many transactions/events into
485one. For example, a function that pings many hosts in parallel might want 662one. For example, a function that pings many hosts in parallel might want
486to use a condition variable for the whole process. 663to use a condition variable for the whole process.
487 664
489C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end 666C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
490>>, the (last) callback passed to C<begin> will be executed. That callback 667>>, the (last) callback passed to C<begin> will be executed. That callback
491is I<supposed> to call C<< ->send >>, but that is not required. If no 668is I<supposed> to call C<< ->send >>, but that is not required. If no
492callback was set, C<send> will be called without any arguments. 669callback was set, C<send> will be called without any arguments.
493 670
494Let's clarify this with the ping example: 671You can think of C<< $cv->send >> giving you an OR condition (one call
672sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND
673condition (all C<begin> calls must be C<end>'ed before the condvar sends).
674
675Let's start with a simple example: you have two I/O watchers (for example,
676STDOUT and STDERR for a program), and you want to wait for both streams to
677close before activating a condvar:
678
679 my $cv = AnyEvent->condvar;
680
681 $cv->begin; # first watcher
682 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
683 defined sysread $fh1, my $buf, 4096
684 or $cv->end;
685 });
686
687 $cv->begin; # second watcher
688 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
689 defined sysread $fh2, my $buf, 4096
690 or $cv->end;
691 });
692
693 $cv->recv;
694
695This works because for every event source (EOF on file handle), there is
696one call to C<begin>, so the condvar waits for all calls to C<end> before
697sending.
698
699The ping example mentioned above is slightly more complicated, as the
700there are results to be passwd back, and the number of tasks that are
701begung can potentially be zero:
495 702
496 my $cv = AnyEvent->condvar; 703 my $cv = AnyEvent->condvar;
497 704
498 my %result; 705 my %result;
499 $cv->begin (sub { $cv->send (\%result) }); 706 $cv->begin (sub { $cv->send (\%result) });
519loop, which serves two important purposes: first, it sets the callback 726loop, which serves two important purposes: first, it sets the callback
520to be called once the counter reaches C<0>, and second, it ensures that 727to be called once the counter reaches C<0>, and second, it ensures that
521C<send> is called even when C<no> hosts are being pinged (the loop 728C<send> is called even when C<no> hosts are being pinged (the loop
522doesn't execute once). 729doesn't execute once).
523 730
524This is the general pattern when you "fan out" into multiple subrequests: 731This is the general pattern when you "fan out" into multiple (but
525use an outer C<begin>/C<end> pair to set the callback and ensure C<end> 732potentially none) subrequests: use an outer C<begin>/C<end> pair to set
526is called at least once, and then, for each subrequest you start, call 733the callback and ensure C<end> is called at least once, and then, for each
527C<begin> and for each subrequest you finish, call C<end>. 734subrequest you start, call C<begin> and for each subrequest you finish,
735call C<end>.
528 736
529=back 737=back
530 738
531=head3 METHODS FOR CONSUMERS 739=head3 METHODS FOR CONSUMERS
532 740
548function will call C<croak>. 756function will call C<croak>.
549 757
550In list context, all parameters passed to C<send> will be returned, 758In list context, all parameters passed to C<send> will be returned,
551in scalar context only the first one will be returned. 759in scalar context only the first one will be returned.
552 760
761Note that doing a blocking wait in a callback is not supported by any
762event loop, that is, recursive invocation of a blocking C<< ->recv
763>> is not allowed, and the C<recv> call will C<croak> if such a
764condition is detected. This condition can be slightly loosened by using
765L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from
766any thread that doesn't run the event loop itself.
767
553Not all event models support a blocking wait - some die in that case 768Not all event models support a blocking wait - some die in that case
554(programs might want to do that to stay interactive), so I<if you are 769(programs might want to do that to stay interactive), so I<if you are
555using this from a module, never require a blocking wait>, but let the 770using this from a module, never require a blocking wait>. Instead, let the
556caller decide whether the call will block or not (for example, by coupling 771caller decide whether the call will block or not (for example, by coupling
557condition variables with some kind of request results and supporting 772condition variables with some kind of request results and supporting
558callbacks so the caller knows that getting the result will not block, 773callbacks so the caller knows that getting the result will not block,
559while still supporting blocking waits if the caller so desires). 774while still supporting blocking waits if the caller so desires).
560 775
561Another reason I<never> to C<< ->recv >> in a module is that you cannot
562sensibly have two C<< ->recv >>'s in parallel, as that would require
563multiple interpreters or coroutines/threads, none of which C<AnyEvent>
564can supply.
565
566The L<Coro> module, however, I<can> and I<does> supply coroutines and, in
567fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe
568versions and also integrates coroutines into AnyEvent, making blocking
569C<< ->recv >> calls perfectly safe as long as they are done from another
570coroutine (one that doesn't run the event loop).
571
572You can ensure that C<< -recv >> never blocks by setting a callback and 776You can ensure that C<< -recv >> never blocks by setting a callback and
573only calling C<< ->recv >> from within that callback (or at a later 777only calling C<< ->recv >> from within that callback (or at a later
574time). This will work even when the event loop does not support blocking 778time). This will work even when the event loop does not support blocking
575waits otherwise. 779waits otherwise.
576 780
577=item $bool = $cv->ready 781=item $bool = $cv->ready
578 782
579Returns true when the condition is "true", i.e. whether C<send> or 783Returns true when the condition is "true", i.e. whether C<send> or
580C<croak> have been called. 784C<croak> have been called.
581 785
582=item $cb = $cv->cb ([new callback]) 786=item $cb = $cv->cb ($cb->($cv))
583 787
584This is a mutator function that returns the callback set and optionally 788This is a mutator function that returns the callback set and optionally
585replaces it before doing so. 789replaces it before doing so.
586 790
587The callback will be called when the condition becomes "true", i.e. when 791The callback will be called when the condition becomes "true", i.e. when
588C<send> or C<croak> are called. Calling C<recv> inside the callback 792C<send> or C<croak> are called, with the only argument being the condition
589or at any later time is guaranteed not to block. 793variable itself. Calling C<recv> inside the callback or at any later time
794is guaranteed not to block.
590 795
591=back 796=back
592 797
798=head1 SUPPORTED EVENT LOOPS/BACKENDS
799
800The available backend classes are (every class has its own manpage):
801
802=over 4
803
804=item Backends that are autoprobed when no other event loop can be found.
805
806EV is the preferred backend when no other event loop seems to be in
807use. If EV is not installed, then AnyEvent will try Event, and, failing
808that, will fall back to its own pure-perl implementation, which is
809available everywhere as it comes with AnyEvent itself.
810
811 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
812 AnyEvent::Impl::Event based on Event, very stable, few glitches.
813 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
814
815=item Backends that are transparently being picked up when they are used.
816
817These will be used when they are currently loaded when the first watcher
818is created, in which case it is assumed that the application is using
819them. This means that AnyEvent will automatically pick the right backend
820when the main program loads an event module before anything starts to
821create watchers. Nothing special needs to be done by the main program.
822
823 AnyEvent::Impl::Glib based on Glib, slow but very stable.
824 AnyEvent::Impl::Tk based on Tk, very broken.
825 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
826 AnyEvent::Impl::POE based on POE, very slow, some limitations.
827 AnyEvent::Impl::Irssi used when running within irssi.
828
829=item Backends with special needs.
830
831Qt requires the Qt::Application to be instantiated first, but will
832otherwise be picked up automatically. As long as the main program
833instantiates the application before any AnyEvent watchers are created,
834everything should just work.
835
836 AnyEvent::Impl::Qt based on Qt.
837
838Support for IO::Async can only be partial, as it is too broken and
839architecturally limited to even support the AnyEvent API. It also
840is the only event loop that needs the loop to be set explicitly, so
841it can only be used by a main program knowing about AnyEvent. See
842L<AnyEvent::Impl::Async> for the gory details.
843
844 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
845
846=item Event loops that are indirectly supported via other backends.
847
848Some event loops can be supported via other modules:
849
850There is no direct support for WxWidgets (L<Wx>) or L<Prima>.
851
852B<WxWidgets> has no support for watching file handles. However, you can
853use WxWidgets through the POE adaptor, as POE has a Wx backend that simply
854polls 20 times per second, which was considered to be too horrible to even
855consider for AnyEvent.
856
857B<Prima> is not supported as nobody seems to be using it, but it has a POE
858backend, so it can be supported through POE.
859
860AnyEvent knows about both L<Prima> and L<Wx>, however, and will try to
861load L<POE> when detecting them, in the hope that POE will pick them up,
862in which case everything will be automatic.
863
864=back
865
593=head1 GLOBAL VARIABLES AND FUNCTIONS 866=head1 GLOBAL VARIABLES AND FUNCTIONS
594 867
868These are not normally required to use AnyEvent, but can be useful to
869write AnyEvent extension modules.
870
595=over 4 871=over 4
596 872
597=item $AnyEvent::MODEL 873=item $AnyEvent::MODEL
598 874
599Contains C<undef> until the first watcher is being created. Then it 875Contains C<undef> until the first watcher is being created, before the
876backend has been autodetected.
877
600contains the event model that is being used, which is the name of the 878Afterwards it contains the event model that is being used, which is the
601Perl class implementing the model. This class is usually one of the 879name of the Perl class implementing the model. This class is usually one
602C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 880of the C<AnyEvent::Impl:xxx> modules, but can be any other class in the
603AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 881case AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode> it
604 882will be C<urxvt::anyevent>).
605The known classes so far are:
606
607 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
608 AnyEvent::Impl::Event based on Event, second best choice.
609 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
610 AnyEvent::Impl::Glib based on Glib, third-best choice.
611 AnyEvent::Impl::Tk based on Tk, very bad choice.
612 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
613 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
614 AnyEvent::Impl::POE based on POE, not generic enough for full support.
615
616There is no support for WxWidgets, as WxWidgets has no support for
617watching file handles. However, you can use WxWidgets through the
618POE Adaptor, as POE has a Wx backend that simply polls 20 times per
619second, which was considered to be too horrible to even consider for
620AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
621it's adaptor.
622
623AnyEvent knows about L<Prima> and L<Wx> and will try to use L<POE> when
624autodetecting them.
625 883
626=item AnyEvent::detect 884=item AnyEvent::detect
627 885
628Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 886Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
629if necessary. You should only call this function right before you would 887if necessary. You should only call this function right before you would
630have created an AnyEvent watcher anyway, that is, as late as possible at 888have created an AnyEvent watcher anyway, that is, as late as possible at
631runtime. 889runtime, and not e.g. while initialising of your module.
890
891If you need to do some initialisation before AnyEvent watchers are
892created, use C<post_detect>.
632 893
633=item $guard = AnyEvent::post_detect { BLOCK } 894=item $guard = AnyEvent::post_detect { BLOCK }
634 895
635Arranges for the code block to be executed as soon as the event model is 896Arranges for the code block to be executed as soon as the event model is
636autodetected (or immediately if this has already happened). 897autodetected (or immediately if this has already happened).
637 898
899The block will be executed I<after> the actual backend has been detected
900(C<$AnyEvent::MODEL> is set), but I<before> any watchers have been
901created, so it is possible to e.g. patch C<@AnyEvent::ISA> or do
902other initialisations - see the sources of L<AnyEvent::Strict> or
903L<AnyEvent::AIO> to see how this is used.
904
905The most common usage is to create some global watchers, without forcing
906event module detection too early, for example, L<AnyEvent::AIO> creates
907and installs the global L<IO::AIO> watcher in a C<post_detect> block to
908avoid autodetecting the event module at load time.
909
638If called in scalar or list context, then it creates and returns an object 910If called in scalar or list context, then it creates and returns an object
639that automatically removes the callback again when it is destroyed. See 911that automatically removes the callback again when it is destroyed (or
912C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
640L<Coro::BDB> for a case where this is useful. 913a case where this is useful.
914
915Example: Create a watcher for the IO::AIO module and store it in
916C<$WATCHER>. Only do so after the event loop is initialised, though.
917
918 our WATCHER;
919
920 my $guard = AnyEvent::post_detect {
921 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
922 };
923
924 # the ||= is important in case post_detect immediately runs the block,
925 # as to not clobber the newly-created watcher. assigning both watcher and
926 # post_detect guard to the same variable has the advantage of users being
927 # able to just C<undef $WATCHER> if the watcher causes them grief.
928
929 $WATCHER ||= $guard;
641 930
642=item @AnyEvent::post_detect 931=item @AnyEvent::post_detect
643 932
644If there are any code references in this array (you can C<push> to it 933If there are any code references in this array (you can C<push> to it
645before or after loading AnyEvent), then they will called directly after 934before or after loading AnyEvent), then they will called directly after
646the event loop has been chosen. 935the event loop has been chosen.
647 936
648You should check C<$AnyEvent::MODEL> before adding to this array, though: 937You should check C<$AnyEvent::MODEL> before adding to this array, though:
649if it contains a true value then the event loop has already been detected, 938if it is defined then the event loop has already been detected, and the
650and the array will be ignored. 939array will be ignored.
651 940
652Best use C<AnyEvent::post_detect { BLOCK }> instead. 941Best use C<AnyEvent::post_detect { BLOCK }> when your application allows
942it,as it takes care of these details.
943
944This variable is mainly useful for modules that can do something useful
945when AnyEvent is used and thus want to know when it is initialised, but do
946not need to even load it by default. This array provides the means to hook
947into AnyEvent passively, without loading it.
653 948
654=back 949=back
655 950
656=head1 WHAT TO DO IN A MODULE 951=head1 WHAT TO DO IN A MODULE
657 952
712 1007
713 1008
714=head1 OTHER MODULES 1009=head1 OTHER MODULES
715 1010
716The following is a non-exhaustive list of additional modules that use 1011The following is a non-exhaustive list of additional modules that use
717AnyEvent and can therefore be mixed easily with other AnyEvent modules 1012AnyEvent as a client and can therefore be mixed easily with other AnyEvent
718in the same program. Some of the modules come with AnyEvent, some are 1013modules and other event loops in the same program. Some of the modules
719available via CPAN. 1014come with AnyEvent, most are available via CPAN.
720 1015
721=over 4 1016=over 4
722 1017
723=item L<AnyEvent::Util> 1018=item L<AnyEvent::Util>
724 1019
725Contains various utility functions that replace often-used but blocking 1020Contains various utility functions that replace often-used but blocking
726functions such as C<inet_aton> by event-/callback-based versions. 1021functions such as C<inet_aton> by event-/callback-based versions.
727
728=item L<AnyEvent::Handle>
729
730Provide read and write buffers and manages watchers for reads and writes.
731 1022
732=item L<AnyEvent::Socket> 1023=item L<AnyEvent::Socket>
733 1024
734Provides various utility functions for (internet protocol) sockets, 1025Provides various utility functions for (internet protocol) sockets,
735addresses and name resolution. Also functions to create non-blocking tcp 1026addresses and name resolution. Also functions to create non-blocking tcp
736connections or tcp servers, with IPv6 and SRV record support and more. 1027connections or tcp servers, with IPv6 and SRV record support and more.
737 1028
1029=item L<AnyEvent::Handle>
1030
1031Provide read and write buffers, manages watchers for reads and writes,
1032supports raw and formatted I/O, I/O queued and fully transparent and
1033non-blocking SSL/TLS (via L<AnyEvent::TLS>.
1034
738=item L<AnyEvent::DNS> 1035=item L<AnyEvent::DNS>
739 1036
740Provides rich asynchronous DNS resolver capabilities. 1037Provides rich asynchronous DNS resolver capabilities.
741 1038
1039=item L<AnyEvent::HTTP>
1040
1041A simple-to-use HTTP library that is capable of making a lot of concurrent
1042HTTP requests.
1043
742=item L<AnyEvent::HTTPD> 1044=item L<AnyEvent::HTTPD>
743 1045
744Provides a simple web application server framework. 1046Provides a simple web application server framework.
745 1047
746=item L<AnyEvent::FastPing> 1048=item L<AnyEvent::FastPing>
747 1049
748The fastest ping in the west. 1050The fastest ping in the west.
749 1051
1052=item L<AnyEvent::DBI>
1053
1054Executes L<DBI> requests asynchronously in a proxy process.
1055
1056=item L<AnyEvent::AIO>
1057
1058Truly asynchronous I/O, should be in the toolbox of every event
1059programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
1060together.
1061
1062=item L<AnyEvent::BDB>
1063
1064Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
1065L<BDB> and AnyEvent together.
1066
1067=item L<AnyEvent::GPSD>
1068
1069A non-blocking interface to gpsd, a daemon delivering GPS information.
1070
750=item L<Net::IRC3> 1071=item L<AnyEvent::IRC>
751 1072
752AnyEvent based IRC client module family. 1073AnyEvent based IRC client module family (replacing the older Net::IRC3).
753 1074
754=item L<Net::XMPP2> 1075=item L<AnyEvent::XMPP>
755 1076
756AnyEvent based XMPP (Jabber protocol) module family. 1077AnyEvent based XMPP (Jabber protocol) module family (replacing the older
1078Net::XMPP2>.
1079
1080=item L<AnyEvent::IGS>
1081
1082A non-blocking interface to the Internet Go Server protocol (used by
1083L<App::IGS>).
757 1084
758=item L<Net::FCP> 1085=item L<Net::FCP>
759 1086
760AnyEvent-based implementation of the Freenet Client Protocol, birthplace 1087AnyEvent-based implementation of the Freenet Client Protocol, birthplace
761of AnyEvent. 1088of AnyEvent.
766 1093
767=item L<Coro> 1094=item L<Coro>
768 1095
769Has special support for AnyEvent via L<Coro::AnyEvent>. 1096Has special support for AnyEvent via L<Coro::AnyEvent>.
770 1097
771=item L<AnyEvent::AIO>, L<IO::AIO>
772
773Truly asynchronous I/O, should be in the toolbox of every event
774programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
775together.
776
777=item L<AnyEvent::BDB>, L<BDB>
778
779Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
780IO::AIO and AnyEvent together.
781
782=item L<IO::Lambda>
783
784The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
785
786=back 1098=back
787 1099
788=cut 1100=cut
789 1101
790package AnyEvent; 1102package AnyEvent;
791 1103
1104# basically a tuned-down version of common::sense
1105sub common_sense {
792no warnings; 1106 # no warnings
793use strict; 1107 ${^WARNING_BITS} ^= ${^WARNING_BITS};
1108 # use strict vars subs
1109 $^H |= 0x00000600;
1110}
794 1111
1112BEGIN { AnyEvent::common_sense }
1113
795use Carp; 1114use Carp ();
796 1115
797our $VERSION = '4.05'; 1116our $VERSION = 4.881;
798our $MODEL; 1117our $MODEL;
799 1118
800our $AUTOLOAD; 1119our $AUTOLOAD;
801our @ISA; 1120our @ISA;
802 1121
803our @REGISTRY; 1122our @REGISTRY;
804 1123
805our $WIN32; 1124our $WIN32;
806 1125
1126our $VERBOSE;
1127
807BEGIN { 1128BEGIN {
808 my $win32 = ! ! ($^O =~ /mswin32/i); 1129 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
809 eval "sub WIN32(){ $win32 }"; 1130 eval "sub TAINT(){ " . (${^TAINT}*1) . " }";
810}
811 1131
1132 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1133 if ${^TAINT};
1134
812our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1135 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1136
1137}
1138
1139our $MAX_SIGNAL_LATENCY = 10;
813 1140
814our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1141our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
815 1142
816{ 1143{
817 my $idx; 1144 my $idx;
819 for reverse split /\s*,\s*/, 1146 for reverse split /\s*,\s*/,
820 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1147 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
821} 1148}
822 1149
823my @models = ( 1150my @models = (
824 [EV:: => AnyEvent::Impl::EV::], 1151 [EV:: => AnyEvent::Impl::EV:: , 1],
825 [Event:: => AnyEvent::Impl::Event::], 1152 [Event:: => AnyEvent::Impl::Event::, 1],
826 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1153 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
827 # everything below here will not be autoprobed 1154 # everything below here will not (normally) be autoprobed
828 # as the pureperl backend should work everywhere 1155 # as the pureperl backend should work everywhere
829 # and is usually faster 1156 # and is usually faster
1157 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1158 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1159 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
830 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1160 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
831 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
832 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
833 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1161 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
834 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1162 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
835 [Wx:: => AnyEvent::Impl::POE::], 1163 [Wx:: => AnyEvent::Impl::POE::],
836 [Prima:: => AnyEvent::Impl::POE::], 1164 [Prima:: => AnyEvent::Impl::POE::],
1165 # IO::Async is just too broken - we would need workarounds for its
1166 # byzantine signal and broken child handling, among others.
1167 # IO::Async is rather hard to detect, as it doesn't have any
1168 # obvious default class.
1169# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1170# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1171# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
837); 1172);
838 1173
839our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY); 1174our %method = map +($_ => 1),
1175 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
840 1176
841our @post_detect; 1177our @post_detect;
842 1178
843sub post_detect(&) { 1179sub post_detect(&) {
844 my ($cb) = @_; 1180 my ($cb) = @_;
845 1181
846 if ($MODEL) { 1182 if ($MODEL) {
847 $cb->(); 1183 $cb->();
848 1184
849 1 1185 undef
850 } else { 1186 } else {
851 push @post_detect, $cb; 1187 push @post_detect, $cb;
852 1188
853 defined wantarray 1189 defined wantarray
854 ? bless \$cb, "AnyEvent::Util::PostDetect" 1190 ? bless \$cb, "AnyEvent::Util::postdetect"
855 : () 1191 : ()
856 } 1192 }
857} 1193}
858 1194
859sub AnyEvent::Util::PostDetect::DESTROY { 1195sub AnyEvent::Util::postdetect::DESTROY {
860 @post_detect = grep $_ != ${$_[0]}, @post_detect; 1196 @post_detect = grep $_ != ${$_[0]}, @post_detect;
861} 1197}
862 1198
863sub detect() { 1199sub detect() {
864 unless ($MODEL) { 1200 unless ($MODEL) {
865 no strict 'refs';
866 local $SIG{__DIE__}; 1201 local $SIG{__DIE__};
867 1202
868 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1203 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
869 my $model = "AnyEvent::Impl::$1"; 1204 my $model = "AnyEvent::Impl::$1";
870 if (eval "require $model") { 1205 if (eval "require $model") {
871 $MODEL = $model; 1206 $MODEL = $model;
872 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1; 1207 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
873 } else { 1208 } else {
874 warn "AnyEvent: unable to load model '$model' (from \$PERL_ANYEVENT_MODEL):\n$@" if $verbose; 1209 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
875 } 1210 }
876 } 1211 }
877 1212
878 # check for already loaded models 1213 # check for already loaded models
879 unless ($MODEL) { 1214 unless ($MODEL) {
880 for (@REGISTRY, @models) { 1215 for (@REGISTRY, @models) {
881 my ($package, $model) = @$_; 1216 my ($package, $model) = @$_;
882 if (${"$package\::VERSION"} > 0) { 1217 if (${"$package\::VERSION"} > 0) {
883 if (eval "require $model") { 1218 if (eval "require $model") {
884 $MODEL = $model; 1219 $MODEL = $model;
885 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 1220 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
886 last; 1221 last;
887 } 1222 }
888 } 1223 }
889 } 1224 }
890 1225
891 unless ($MODEL) { 1226 unless ($MODEL) {
892 # try to load a model 1227 # try to autoload a model
893
894 for (@REGISTRY, @models) { 1228 for (@REGISTRY, @models) {
895 my ($package, $model) = @$_; 1229 my ($package, $model, $autoload) = @$_;
1230 if (
1231 $autoload
896 if (eval "require $package" 1232 and eval "require $package"
897 and ${"$package\::VERSION"} > 0 1233 and ${"$package\::VERSION"} > 0
898 and eval "require $model") { 1234 and eval "require $model"
1235 ) {
899 $MODEL = $model; 1236 $MODEL = $model;
900 warn "AnyEvent: autoprobed model '$model', using it.\n" if $verbose > 1; 1237 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
901 last; 1238 last;
902 } 1239 }
903 } 1240 }
904 1241
905 $MODEL 1242 $MODEL
906 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib."; 1243 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n";
907 } 1244 }
908 } 1245 }
909 1246
1247 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1248
910 unshift @ISA, $MODEL; 1249 unshift @ISA, $MODEL;
911 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1250
1251 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
912 1252
913 (shift @post_detect)->() while @post_detect; 1253 (shift @post_detect)->() while @post_detect;
914 } 1254 }
915 1255
916 $MODEL 1256 $MODEL
918 1258
919sub AUTOLOAD { 1259sub AUTOLOAD {
920 (my $func = $AUTOLOAD) =~ s/.*://; 1260 (my $func = $AUTOLOAD) =~ s/.*://;
921 1261
922 $method{$func} 1262 $method{$func}
923 or croak "$func: not a valid method for AnyEvent objects"; 1263 or Carp::croak "$func: not a valid method for AnyEvent objects";
924 1264
925 detect unless $MODEL; 1265 detect unless $MODEL;
926 1266
927 my $class = shift; 1267 my $class = shift;
928 $class->$func (@_); 1268 $class->$func (@_);
929} 1269}
930 1270
1271# utility function to dup a filehandle. this is used by many backends
1272# to support binding more than one watcher per filehandle (they usually
1273# allow only one watcher per fd, so we dup it to get a different one).
1274sub _dupfh($$;$$) {
1275 my ($poll, $fh, $r, $w) = @_;
1276
1277 # cygwin requires the fh mode to be matching, unix doesn't
1278 my ($rw, $mode) = $poll eq "r" ? ($r, "<&") : ($w, ">&");
1279
1280 open my $fh2, $mode, $fh
1281 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1282
1283 # we assume CLOEXEC is already set by perl in all important cases
1284
1285 ($fh2, $rw)
1286}
1287
931package AnyEvent::Base; 1288package AnyEvent::Base;
932 1289
933# default implementation for now and time 1290# default implementations for many methods
934 1291
935use Time::HiRes (); 1292sub _time {
1293 # probe for availability of Time::HiRes
1294 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1295 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1296 *_time = \&Time::HiRes::time;
1297 # if (eval "use POSIX (); (POSIX::times())...
1298 } else {
1299 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1300 *_time = sub { time }; # epic fail
1301 }
936 1302
937sub time { Time::HiRes::time } 1303 &_time
938sub now { Time::HiRes::time } 1304}
1305
1306sub time { _time }
1307sub now { _time }
1308sub now_update { }
939 1309
940# default implementation for ->condvar 1310# default implementation for ->condvar
941 1311
942sub condvar { 1312sub condvar {
943 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 1313 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
944} 1314}
945 1315
946# default implementation for ->signal 1316# default implementation for ->signal
947 1317
948our %SIG_CB; 1318our $HAVE_ASYNC_INTERRUPT;
1319
1320sub _have_async_interrupt() {
1321 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT}
1322 && eval "use Async::Interrupt 1.0 (); 1")
1323 unless defined $HAVE_ASYNC_INTERRUPT;
1324
1325 $HAVE_ASYNC_INTERRUPT
1326}
1327
1328our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1329our (%SIG_ASY, %SIG_ASY_W);
1330our ($SIG_COUNT, $SIG_TW);
1331
1332sub _signal_exec {
1333 $HAVE_ASYNC_INTERRUPT
1334 ? $SIGPIPE_R->drain
1335 : sysread $SIGPIPE_R, my $dummy, 9;
1336
1337 while (%SIG_EV) {
1338 for (keys %SIG_EV) {
1339 delete $SIG_EV{$_};
1340 $_->() for values %{ $SIG_CB{$_} || {} };
1341 }
1342 }
1343}
1344
1345# install a dummy wakeup watcher to reduce signal catching latency
1346sub _sig_add() {
1347 unless ($SIG_COUNT++) {
1348 # try to align timer on a full-second boundary, if possible
1349 my $NOW = AnyEvent->now;
1350
1351 $SIG_TW = AnyEvent->timer (
1352 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1353 interval => $MAX_SIGNAL_LATENCY,
1354 cb => sub { }, # just for the PERL_ASYNC_CHECK
1355 );
1356 }
1357}
1358
1359sub _sig_del {
1360 undef $SIG_TW
1361 unless --$SIG_COUNT;
1362}
1363
1364our $_sig_name_init; $_sig_name_init = sub {
1365 eval q{ # poor man's autoloading
1366 undef $_sig_name_init;
1367
1368 if (_have_async_interrupt) {
1369 *sig2num = \&Async::Interrupt::sig2num;
1370 *sig2name = \&Async::Interrupt::sig2name;
1371 } else {
1372 require Config;
1373
1374 my %signame2num;
1375 @signame2num{ split ' ', $Config::Config{sig_name} }
1376 = split ' ', $Config::Config{sig_num};
1377
1378 my @signum2name;
1379 @signum2name[values %signame2num] = keys %signame2num;
1380
1381 *sig2num = sub($) {
1382 $_[0] > 0 ? shift : $signame2num{+shift}
1383 };
1384 *sig2name = sub ($) {
1385 $_[0] > 0 ? $signum2name[+shift] : shift
1386 };
1387 }
1388 };
1389 die if $@;
1390};
1391
1392sub sig2num ($) { &$_sig_name_init; &sig2num }
1393sub sig2name($) { &$_sig_name_init; &sig2name }
949 1394
950sub signal { 1395sub signal {
1396 eval q{ # poor man's autoloading {}
1397 # probe for availability of Async::Interrupt
1398 if (_have_async_interrupt) {
1399 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1400
1401 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1402 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1403
1404 } else {
1405 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1406
1407 require Fcntl;
1408
1409 if (AnyEvent::WIN32) {
1410 require AnyEvent::Util;
1411
1412 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1413 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
1414 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case
1415 } else {
1416 pipe $SIGPIPE_R, $SIGPIPE_W;
1417 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
1418 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
1419
1420 # not strictly required, as $^F is normally 2, but let's make sure...
1421 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1422 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1423 }
1424
1425 $SIGPIPE_R
1426 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1427
1428 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1429 }
1430
1431 *signal = sub {
951 my (undef, %arg) = @_; 1432 my (undef, %arg) = @_;
952 1433
953 my $signal = uc $arg{signal} 1434 my $signal = uc $arg{signal}
954 or Carp::croak "required option 'signal' is missing"; 1435 or Carp::croak "required option 'signal' is missing";
955 1436
1437 if ($HAVE_ASYNC_INTERRUPT) {
1438 # async::interrupt
1439
1440 $signal = sig2num $signal;
956 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1441 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1442
1443 $SIG_ASY{$signal} ||= new Async::Interrupt
1444 cb => sub { undef $SIG_EV{$signal} },
1445 signal => $signal,
1446 pipe => [$SIGPIPE_R->filenos],
1447 pipe_autodrain => 0,
1448 ;
1449
1450 } else {
1451 # pure perl
1452
1453 # AE::Util has been loaded in signal
1454 $signal = sig2name $signal;
1455 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1456
957 $SIG{$signal} ||= sub { 1457 $SIG{$signal} ||= sub {
958 $_->() for values %{ $SIG_CB{$signal} || {} }; 1458 local $!;
1459 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1460 undef $SIG_EV{$signal};
1461 };
1462
1463 # can't do signal processing without introducing races in pure perl,
1464 # so limit the signal latency.
1465 _sig_add;
1466 }
1467
1468 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1469 };
1470
1471 *AnyEvent::Base::signal::DESTROY = sub {
1472 my ($signal, $cb) = @{$_[0]};
1473
1474 _sig_del;
1475
1476 delete $SIG_CB{$signal}{$cb};
1477
1478 $HAVE_ASYNC_INTERRUPT
1479 ? delete $SIG_ASY{$signal}
1480 : # delete doesn't work with older perls - they then
1481 # print weird messages, or just unconditionally exit
1482 # instead of getting the default action.
1483 undef $SIG{$signal}
1484 unless keys %{ $SIG_CB{$signal} };
1485 };
959 }; 1486 };
960 1487 die if $@;
961 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal" 1488 &signal
962}
963
964sub AnyEvent::Base::Signal::DESTROY {
965 my ($signal, $cb) = @{$_[0]};
966
967 delete $SIG_CB{$signal}{$cb};
968
969 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
970} 1489}
971 1490
972# default implementation for ->child 1491# default implementation for ->child
973 1492
974our %PID_CB; 1493our %PID_CB;
975our $CHLD_W; 1494our $CHLD_W;
976our $CHLD_DELAY_W; 1495our $CHLD_DELAY_W;
977our $PID_IDLE;
978our $WNOHANG; 1496our $WNOHANG;
979 1497
980sub _child_wait { 1498sub _emit_childstatus($$) {
981 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1499 my (undef, $rpid, $rstatus) = @_;
1500
1501 $_->($rpid, $rstatus)
982 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 1502 for values %{ $PID_CB{$rpid} || {} },
983 (values %{ $PID_CB{0} || {} }); 1503 values %{ $PID_CB{0} || {} };
984 }
985
986 undef $PID_IDLE;
987} 1504}
988 1505
989sub _sigchld { 1506sub _sigchld {
990 # make sure we deliver these changes "synchronous" with the event loop. 1507 my $pid;
991 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub { 1508
992 undef $CHLD_DELAY_W; 1509 AnyEvent->_emit_childstatus ($pid, $?)
993 &_child_wait; 1510 while ($pid = waitpid -1, $WNOHANG) > 0;
994 });
995} 1511}
996 1512
997sub child { 1513sub child {
998 my (undef, %arg) = @_; 1514 my (undef, %arg) = @_;
999 1515
1000 defined (my $pid = $arg{pid} + 0) 1516 defined (my $pid = $arg{pid} + 0)
1001 or Carp::croak "required option 'pid' is missing"; 1517 or Carp::croak "required option 'pid' is missing";
1002 1518
1003 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1519 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
1004 1520
1005 unless ($WNOHANG) { 1521 # WNOHANG is almost cetrainly 1 everywhere
1522 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1523 ? 1
1006 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1524 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1007 }
1008 1525
1009 unless ($CHLD_W) { 1526 unless ($CHLD_W) {
1010 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1527 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
1011 # child could be a zombie already, so make at least one round 1528 # child could be a zombie already, so make at least one round
1012 &_sigchld; 1529 &_sigchld;
1013 } 1530 }
1014 1531
1015 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 1532 bless [$pid, $arg{cb}], "AnyEvent::Base::child"
1016} 1533}
1017 1534
1018sub AnyEvent::Base::Child::DESTROY { 1535sub AnyEvent::Base::child::DESTROY {
1019 my ($pid, $cb) = @{$_[0]}; 1536 my ($pid, $cb) = @{$_[0]};
1020 1537
1021 delete $PID_CB{$pid}{$cb}; 1538 delete $PID_CB{$pid}{$cb};
1022 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1539 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1023 1540
1024 undef $CHLD_W unless keys %PID_CB; 1541 undef $CHLD_W unless keys %PID_CB;
1025} 1542}
1026 1543
1544# idle emulation is done by simply using a timer, regardless
1545# of whether the process is idle or not, and not letting
1546# the callback use more than 50% of the time.
1547sub idle {
1548 my (undef, %arg) = @_;
1549
1550 my ($cb, $w, $rcb) = $arg{cb};
1551
1552 $rcb = sub {
1553 if ($cb) {
1554 $w = _time;
1555 &$cb;
1556 $w = _time - $w;
1557
1558 # never use more then 50% of the time for the idle watcher,
1559 # within some limits
1560 $w = 0.0001 if $w < 0.0001;
1561 $w = 5 if $w > 5;
1562
1563 $w = AnyEvent->timer (after => $w, cb => $rcb);
1564 } else {
1565 # clean up...
1566 undef $w;
1567 undef $rcb;
1568 }
1569 };
1570
1571 $w = AnyEvent->timer (after => 0.05, cb => $rcb);
1572
1573 bless \\$cb, "AnyEvent::Base::idle"
1574}
1575
1576sub AnyEvent::Base::idle::DESTROY {
1577 undef $${$_[0]};
1578}
1579
1027package AnyEvent::CondVar; 1580package AnyEvent::CondVar;
1028 1581
1029our @ISA = AnyEvent::CondVar::Base::; 1582our @ISA = AnyEvent::CondVar::Base::;
1030 1583
1031package AnyEvent::CondVar::Base; 1584package AnyEvent::CondVar::Base;
1032 1585
1033use overload 1586#use overload
1034 '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1587# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1035 fallback => 1; 1588# fallback => 1;
1589
1590# save 300+ kilobytes by dirtily hardcoding overloading
1591${"AnyEvent::CondVar::Base::OVERLOAD"}{dummy}++; # Register with magic by touching.
1592*{'AnyEvent::CondVar::Base::()'} = sub { }; # "Make it findable via fetchmethod."
1593*{'AnyEvent::CondVar::Base::(&{}'} = sub { my $self = shift; sub { $self->send (@_) } }; # &{}
1594${'AnyEvent::CondVar::Base::()'} = 1; # fallback
1595
1596our $WAITING;
1036 1597
1037sub _send { 1598sub _send {
1038 # nop 1599 # nop
1039} 1600}
1040 1601
1053sub ready { 1614sub ready {
1054 $_[0]{_ae_sent} 1615 $_[0]{_ae_sent}
1055} 1616}
1056 1617
1057sub _wait { 1618sub _wait {
1619 $WAITING
1620 and !$_[0]{_ae_sent}
1621 and Carp::croak "AnyEvent::CondVar: recursive blocking wait detected";
1622
1623 local $WAITING = 1;
1058 AnyEvent->one_event while !$_[0]{_ae_sent}; 1624 AnyEvent->one_event while !$_[0]{_ae_sent};
1059} 1625}
1060 1626
1061sub recv { 1627sub recv {
1062 $_[0]->_wait; 1628 $_[0]->_wait;
1081} 1647}
1082 1648
1083# undocumented/compatibility with pre-3.4 1649# undocumented/compatibility with pre-3.4
1084*broadcast = \&send; 1650*broadcast = \&send;
1085*wait = \&_wait; 1651*wait = \&_wait;
1652
1653#############################################################################
1654# "new" API, currently only emulation of it
1655#############################################################################
1656
1657package AE;
1658
1659sub io($$$) {
1660 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1661}
1662
1663sub timer($$$) {
1664 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]);
1665}
1666
1667sub signal($$) {
1668 AnyEvent->signal (signal => $_[0], cb => $_[1]);
1669}
1670
1671sub child($$) {
1672 AnyEvent->child (pid => $_[0], cb => $_[1]);
1673}
1674
1675sub idle($) {
1676 AnyEvent->idle (cb => $_[0]);
1677}
1678
1679sub cv() {
1680 AnyEvent->condvar
1681}
1682
1683sub now() {
1684 AnyEvent->now
1685}
1686
1687sub now_update() {
1688 AnyEvent->now_update
1689}
1690
1691sub time() {
1692 AnyEvent->time
1693}
1694
1695=head1 ERROR AND EXCEPTION HANDLING
1696
1697In general, AnyEvent does not do any error handling - it relies on the
1698caller to do that if required. The L<AnyEvent::Strict> module (see also
1699the C<PERL_ANYEVENT_STRICT> environment variable, below) provides strict
1700checking of all AnyEvent methods, however, which is highly useful during
1701development.
1702
1703As for exception handling (i.e. runtime errors and exceptions thrown while
1704executing a callback), this is not only highly event-loop specific, but
1705also not in any way wrapped by this module, as this is the job of the main
1706program.
1707
1708The pure perl event loop simply re-throws the exception (usually
1709within C<< condvar->recv >>), the L<Event> and L<EV> modules call C<<
1710$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1711so on.
1712
1713=head1 ENVIRONMENT VARIABLES
1714
1715The following environment variables are used by this module or its
1716submodules.
1717
1718Note that AnyEvent will remove I<all> environment variables starting with
1719C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
1720enabled.
1721
1722=over 4
1723
1724=item C<PERL_ANYEVENT_VERBOSE>
1725
1726By default, AnyEvent will be completely silent except in fatal
1727conditions. You can set this environment variable to make AnyEvent more
1728talkative.
1729
1730When set to C<1> or higher, causes AnyEvent to warn about unexpected
1731conditions, such as not being able to load the event model specified by
1732C<PERL_ANYEVENT_MODEL>.
1733
1734When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1735model it chooses.
1736
1737When set to C<8> or higher, then AnyEvent will report extra information on
1738which optional modules it loads and how it implements certain features.
1739
1740=item C<PERL_ANYEVENT_STRICT>
1741
1742AnyEvent does not do much argument checking by default, as thorough
1743argument checking is very costly. Setting this variable to a true value
1744will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1745check the arguments passed to most method calls. If it finds any problems,
1746it will croak.
1747
1748In other words, enables "strict" mode.
1749
1750Unlike C<use strict> (or it's modern cousin, C<< use L<common::sense>
1751>>, it is definitely recommended to keep it off in production. Keeping
1752C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1753can be very useful, however.
1754
1755=item C<PERL_ANYEVENT_MODEL>
1756
1757This can be used to specify the event model to be used by AnyEvent, before
1758auto detection and -probing kicks in. It must be a string consisting
1759entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1760and the resulting module name is loaded and if the load was successful,
1761used as event model. If it fails to load AnyEvent will proceed with
1762auto detection and -probing.
1763
1764This functionality might change in future versions.
1765
1766For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1767could start your program like this:
1768
1769 PERL_ANYEVENT_MODEL=Perl perl ...
1770
1771=item C<PERL_ANYEVENT_PROTOCOLS>
1772
1773Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1774for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1775of auto probing).
1776
1777Must be set to a comma-separated list of protocols or address families,
1778current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1779used, and preference will be given to protocols mentioned earlier in the
1780list.
1781
1782This variable can effectively be used for denial-of-service attacks
1783against local programs (e.g. when setuid), although the impact is likely
1784small, as the program has to handle conenction and other failures anyways.
1785
1786Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1787but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1788- only support IPv4, never try to resolve or contact IPv6
1789addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1790IPv6, but prefer IPv6 over IPv4.
1791
1792=item C<PERL_ANYEVENT_EDNS0>
1793
1794Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1795for DNS. This extension is generally useful to reduce DNS traffic, but
1796some (broken) firewalls drop such DNS packets, which is why it is off by
1797default.
1798
1799Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1800EDNS0 in its DNS requests.
1801
1802=item C<PERL_ANYEVENT_MAX_FORKS>
1803
1804The maximum number of child processes that C<AnyEvent::Util::fork_call>
1805will create in parallel.
1806
1807=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
1808
1809The default value for the C<max_outstanding> parameter for the default DNS
1810resolver - this is the maximum number of parallel DNS requests that are
1811sent to the DNS server.
1812
1813=item C<PERL_ANYEVENT_RESOLV_CONF>
1814
1815The file to use instead of F</etc/resolv.conf> (or OS-specific
1816configuration) in the default resolver. When set to the empty string, no
1817default config will be used.
1818
1819=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1820
1821When neither C<ca_file> nor C<ca_path> was specified during
1822L<AnyEvent::TLS> context creation, and either of these environment
1823variables exist, they will be used to specify CA certificate locations
1824instead of a system-dependent default.
1825
1826=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1827
1828When these are set to C<1>, then the respective modules are not
1829loaded. Mostly good for testing AnyEvent itself.
1830
1831=back
1086 1832
1087=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1833=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1088 1834
1089This is an advanced topic that you do not normally need to use AnyEvent in 1835This is an advanced topic that you do not normally need to use AnyEvent in
1090a module. This section is only of use to event loop authors who want to 1836a module. This section is only of use to event loop authors who want to
1124 1870
1125I<rxvt-unicode> also cheats a bit by not providing blocking access to 1871I<rxvt-unicode> also cheats a bit by not providing blocking access to
1126condition variables: code blocking while waiting for a condition will 1872condition variables: code blocking while waiting for a condition will
1127C<die>. This still works with most modules/usages, and blocking calls must 1873C<die>. This still works with most modules/usages, and blocking calls must
1128not be done in an interactive application, so it makes sense. 1874not be done in an interactive application, so it makes sense.
1129
1130=head1 ENVIRONMENT VARIABLES
1131
1132The following environment variables are used by this module:
1133
1134=over 4
1135
1136=item C<PERL_ANYEVENT_VERBOSE>
1137
1138By default, AnyEvent will be completely silent except in fatal
1139conditions. You can set this environment variable to make AnyEvent more
1140talkative.
1141
1142When set to C<1> or higher, causes AnyEvent to warn about unexpected
1143conditions, such as not being able to load the event model specified by
1144C<PERL_ANYEVENT_MODEL>.
1145
1146When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1147model it chooses.
1148
1149=item C<PERL_ANYEVENT_MODEL>
1150
1151This can be used to specify the event model to be used by AnyEvent, before
1152auto detection and -probing kicks in. It must be a string consisting
1153entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1154and the resulting module name is loaded and if the load was successful,
1155used as event model. If it fails to load AnyEvent will proceed with
1156auto detection and -probing.
1157
1158This functionality might change in future versions.
1159
1160For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1161could start your program like this:
1162
1163 PERL_ANYEVENT_MODEL=Perl perl ...
1164
1165=item C<PERL_ANYEVENT_PROTOCOLS>
1166
1167Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1168for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1169of auto probing).
1170
1171Must be set to a comma-separated list of protocols or address families,
1172current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1173used, and preference will be given to protocols mentioned earlier in the
1174list.
1175
1176This variable can effectively be used for denial-of-service attacks
1177against local programs (e.g. when setuid), although the impact is likely
1178small, as the program has to handle connection errors already-
1179
1180Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1181but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1182- only support IPv4, never try to resolve or contact IPv6
1183addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1184IPv6, but prefer IPv6 over IPv4.
1185
1186=item C<PERL_ANYEVENT_EDNS0>
1187
1188Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1189for DNS. This extension is generally useful to reduce DNS traffic, but
1190some (broken) firewalls drop such DNS packets, which is why it is off by
1191default.
1192
1193Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1194EDNS0 in its DNS requests.
1195
1196=item C<PERL_ANYEVENT_MAX_FORKS>
1197
1198The maximum number of child processes that C<AnyEvent::Util::fork_call>
1199will create in parallel.
1200
1201=back
1202 1875
1203=head1 EXAMPLE PROGRAM 1876=head1 EXAMPLE PROGRAM
1204 1877
1205The following program uses an I/O watcher to read data from STDIN, a timer 1878The following program uses an I/O watcher to read data from STDIN, a timer
1206to display a message once per second, and a condition variable to quit the 1879to display a message once per second, and a condition variable to quit the
1400watcher. 2073watcher.
1401 2074
1402=head3 Results 2075=head3 Results
1403 2076
1404 name watchers bytes create invoke destroy comment 2077 name watchers bytes create invoke destroy comment
1405 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 2078 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1406 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 2079 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1407 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 2080 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1408 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 2081 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1409 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 2082 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1410 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 2083 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
2084 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
2085 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1411 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 2086 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1412 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 2087 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1413 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 2088 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1414 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 2089 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1415 2090
1416=head3 Discussion 2091=head3 Discussion
1417 2092
1418The benchmark does I<not> measure scalability of the event loop very 2093The benchmark does I<not> measure scalability of the event loop very
1419well. For example, a select-based event loop (such as the pure perl one) 2094well. For example, a select-based event loop (such as the pure perl one)
1444performance becomes really bad with lots of file descriptors (and few of 2119performance becomes really bad with lots of file descriptors (and few of
1445them active), of course, but this was not subject of this benchmark. 2120them active), of course, but this was not subject of this benchmark.
1446 2121
1447The C<Event> module has a relatively high setup and callback invocation 2122The C<Event> module has a relatively high setup and callback invocation
1448cost, but overall scores in on the third place. 2123cost, but overall scores in on the third place.
2124
2125C<IO::Async> performs admirably well, about on par with C<Event>, even
2126when using its pure perl backend.
1449 2127
1450C<Glib>'s memory usage is quite a bit higher, but it features a 2128C<Glib>'s memory usage is quite a bit higher, but it features a
1451faster callback invocation and overall ends up in the same class as 2129faster callback invocation and overall ends up in the same class as
1452C<Event>. However, Glib scales extremely badly, doubling the number of 2130C<Event>. However, Glib scales extremely badly, doubling the number of
1453watchers increases the processing time by more than a factor of four, 2131watchers increases the processing time by more than a factor of four,
1531it to another server. This includes deleting the old timeout and creating 2209it to another server. This includes deleting the old timeout and creating
1532a new one that moves the timeout into the future. 2210a new one that moves the timeout into the future.
1533 2211
1534=head3 Results 2212=head3 Results
1535 2213
1536 name sockets create request 2214 name sockets create request
1537 EV 20000 69.01 11.16 2215 EV 20000 69.01 11.16
1538 Perl 20000 73.32 35.87 2216 Perl 20000 73.32 35.87
2217 IOAsync 20000 157.00 98.14 epoll
2218 IOAsync 20000 159.31 616.06 poll
1539 Event 20000 212.62 257.32 2219 Event 20000 212.62 257.32
1540 Glib 20000 651.16 1896.30 2220 Glib 20000 651.16 1896.30
1541 POE 20000 349.67 12317.24 uses POE::Loop::Event 2221 POE 20000 349.67 12317.24 uses POE::Loop::Event
1542 2222
1543=head3 Discussion 2223=head3 Discussion
1544 2224
1545This benchmark I<does> measure scalability and overall performance of the 2225This benchmark I<does> measure scalability and overall performance of the
1546particular event loop. 2226particular event loop.
1548EV is again fastest. Since it is using epoll on my system, the setup time 2228EV is again fastest. Since it is using epoll on my system, the setup time
1549is relatively high, though. 2229is relatively high, though.
1550 2230
1551Perl surprisingly comes second. It is much faster than the C-based event 2231Perl surprisingly comes second. It is much faster than the C-based event
1552loops Event and Glib. 2232loops Event and Glib.
2233
2234IO::Async performs very well when using its epoll backend, and still quite
2235good compared to Glib when using its pure perl backend.
1553 2236
1554Event suffers from high setup time as well (look at its code and you will 2237Event suffers from high setup time as well (look at its code and you will
1555understand why). Callback invocation also has a high overhead compared to 2238understand why). Callback invocation also has a high overhead compared to
1556the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event 2239the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event
1557uses select or poll in basically all documented configurations. 2240uses select or poll in basically all documented configurations.
1620=item * C-based event loops perform very well with small number of 2303=item * C-based event loops perform very well with small number of
1621watchers, as the management overhead dominates. 2304watchers, as the management overhead dominates.
1622 2305
1623=back 2306=back
1624 2307
2308=head2 THE IO::Lambda BENCHMARK
2309
2310Recently I was told about the benchmark in the IO::Lambda manpage, which
2311could be misinterpreted to make AnyEvent look bad. In fact, the benchmark
2312simply compares IO::Lambda with POE, and IO::Lambda looks better (which
2313shouldn't come as a surprise to anybody). As such, the benchmark is
2314fine, and mostly shows that the AnyEvent backend from IO::Lambda isn't
2315very optimal. But how would AnyEvent compare when used without the extra
2316baggage? To explore this, I wrote the equivalent benchmark for AnyEvent.
2317
2318The benchmark itself creates an echo-server, and then, for 500 times,
2319connects to the echo server, sends a line, waits for the reply, and then
2320creates the next connection. This is a rather bad benchmark, as it doesn't
2321test the efficiency of the framework or much non-blocking I/O, but it is a
2322benchmark nevertheless.
2323
2324 name runtime
2325 Lambda/select 0.330 sec
2326 + optimized 0.122 sec
2327 Lambda/AnyEvent 0.327 sec
2328 + optimized 0.138 sec
2329 Raw sockets/select 0.077 sec
2330 POE/select, components 0.662 sec
2331 POE/select, raw sockets 0.226 sec
2332 POE/select, optimized 0.404 sec
2333
2334 AnyEvent/select/nb 0.085 sec
2335 AnyEvent/EV/nb 0.068 sec
2336 +state machine 0.134 sec
2337
2338The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
2339benchmarks actually make blocking connects and use 100% blocking I/O,
2340defeating the purpose of an event-based solution. All of the newly
2341written AnyEvent benchmarks use 100% non-blocking connects (using
2342AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
2343resolver), so AnyEvent is at a disadvantage here, as non-blocking connects
2344generally require a lot more bookkeeping and event handling than blocking
2345connects (which involve a single syscall only).
2346
2347The last AnyEvent benchmark additionally uses L<AnyEvent::Handle>, which
2348offers similar expressive power as POE and IO::Lambda, using conventional
2349Perl syntax. This means that both the echo server and the client are 100%
2350non-blocking, further placing it at a disadvantage.
2351
2352As you can see, the AnyEvent + EV combination even beats the
2353hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
2354backend easily beats IO::Lambda and POE.
2355
2356And even the 100% non-blocking version written using the high-level (and
2357slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a
2358large margin, even though it does all of DNS, tcp-connect and socket I/O
2359in a non-blocking way.
2360
2361The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
2362F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2363part of the IO::lambda distribution and were used without any changes.
2364
2365
2366=head1 SIGNALS
2367
2368AnyEvent currently installs handlers for these signals:
2369
2370=over 4
2371
2372=item SIGCHLD
2373
2374A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
2375emulation for event loops that do not support them natively. Also, some
2376event loops install a similar handler.
2377
2378Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE, then
2379AnyEvent will reset it to default, to avoid losing child exit statuses.
2380
2381=item SIGPIPE
2382
2383A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
2384when AnyEvent gets loaded.
2385
2386The rationale for this is that AnyEvent users usually do not really depend
2387on SIGPIPE delivery (which is purely an optimisation for shell use, or
2388badly-written programs), but C<SIGPIPE> can cause spurious and rare
2389program exits as a lot of people do not expect C<SIGPIPE> when writing to
2390some random socket.
2391
2392The rationale for installing a no-op handler as opposed to ignoring it is
2393that this way, the handler will be restored to defaults on exec.
2394
2395Feel free to install your own handler, or reset it to defaults.
2396
2397=back
2398
2399=cut
2400
2401undef $SIG{CHLD}
2402 if $SIG{CHLD} eq 'IGNORE';
2403
2404$SIG{PIPE} = sub { }
2405 unless defined $SIG{PIPE};
2406
2407=head1 RECOMMENDED/OPTIONAL MODULES
2408
2409One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2410it's built-in modules) are required to use it.
2411
2412That does not mean that AnyEvent won't take advantage of some additional
2413modules if they are installed.
2414
2415This section epxlains which additional modules will be used, and how they
2416affect AnyEvent's operetion.
2417
2418=over 4
2419
2420=item L<Async::Interrupt>
2421
2422This slightly arcane module is used to implement fast signal handling: To
2423my knowledge, there is no way to do completely race-free and quick
2424signal handling in pure perl. To ensure that signals still get
2425delivered, AnyEvent will start an interval timer to wake up perl (and
2426catch the signals) with some delay (default is 10 seconds, look for
2427C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2428
2429If this module is available, then it will be used to implement signal
2430catching, which means that signals will not be delayed, and the event loop
2431will not be interrupted regularly, which is more efficient (And good for
2432battery life on laptops).
2433
2434This affects not just the pure-perl event loop, but also other event loops
2435that have no signal handling on their own (e.g. Glib, Tk, Qt).
2436
2437Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2438and either employ their own workarounds (POE) or use AnyEvent's workaround
2439(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2440does nothing for those backends.
2441
2442=item L<EV>
2443
2444This module isn't really "optional", as it is simply one of the backend
2445event loops that AnyEvent can use. However, it is simply the best event
2446loop available in terms of features, speed and stability: It supports
2447the AnyEvent API optimally, implements all the watcher types in XS, does
2448automatic timer adjustments even when no monotonic clock is available,
2449can take avdantage of advanced kernel interfaces such as C<epoll> and
2450C<kqueue>, and is the fastest backend I<by far>. You can even embed
2451L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2452
2453=item L<Guard>
2454
2455The guard module, when used, will be used to implement
2456C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2457lot less memory), but otherwise doesn't affect guard operation much. It is
2458purely used for performance.
2459
2460=item L<JSON> and L<JSON::XS>
2461
2462This module is required when you want to read or write JSON data via
2463L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2464advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2465
2466In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2467installed.
2468
2469=item L<Net::SSLeay>
2470
2471Implementing TLS/SSL in Perl is certainly interesting, but not very
2472worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2473the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2474
2475=item L<Time::HiRes>
2476
2477This module is part of perl since release 5.008. It will be used when the
2478chosen event library does not come with a timing source on it's own. The
2479pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to
2480try to use a monotonic clock for timing stability.
2481
2482=back
2483
1625 2484
1626=head1 FORK 2485=head1 FORK
1627 2486
1628Most event libraries are not fork-safe. The ones who are usually are 2487Most event libraries are not fork-safe. The ones who are usually are
1629because they rely on inefficient but fork-safe C<select> or C<poll> 2488because they rely on inefficient but fork-safe C<select> or C<poll>
1630calls. Only L<EV> is fully fork-aware. 2489calls. Only L<EV> is fully fork-aware.
1631 2490
1632If you have to fork, you must either do so I<before> creating your first 2491If you have to fork, you must either do so I<before> creating your first
1633watcher OR you must not use AnyEvent at all in the child. 2492watcher OR you must not use AnyEvent at all in the child OR you must do
2493something completely out of the scope of AnyEvent.
1634 2494
1635 2495
1636=head1 SECURITY CONSIDERATIONS 2496=head1 SECURITY CONSIDERATIONS
1637 2497
1638AnyEvent can be forced to load any event model via 2498AnyEvent can be forced to load any event model via
1643specified in the variable. 2503specified in the variable.
1644 2504
1645You can make AnyEvent completely ignore this variable by deleting it 2505You can make AnyEvent completely ignore this variable by deleting it
1646before the first watcher gets created, e.g. with a C<BEGIN> block: 2506before the first watcher gets created, e.g. with a C<BEGIN> block:
1647 2507
1648 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 2508 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1649 2509
1650 use AnyEvent; 2510 use AnyEvent;
1651 2511
1652Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 2512Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1653be used to probe what backend is used and gain other information (which is 2513be used to probe what backend is used and gain other information (which is
1654probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 2514probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and
2515$ENV{PERL_ANYEVENT_STRICT}.
2516
2517Note that AnyEvent will remove I<all> environment variables starting with
2518C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
2519enabled.
2520
2521
2522=head1 BUGS
2523
2524Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
2525to work around. If you suffer from memleaks, first upgrade to Perl 5.10
2526and check wether the leaks still show up. (Perl 5.10.0 has other annoying
2527memleaks, such as leaking on C<map> and C<grep> but it is usually not as
2528pronounced).
1655 2529
1656 2530
1657=head1 SEE ALSO 2531=head1 SEE ALSO
1658 2532
1659Utility functions: L<AnyEvent::Util>. 2533Utility functions: L<AnyEvent::Util>.
1662L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2536L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1663 2537
1664Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2538Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1665L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2539L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1666L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2540L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1667L<AnyEvent::Impl::POE>. 2541L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>.
1668 2542
1669Non-blocking file handles, sockets, TCP clients and 2543Non-blocking file handles, sockets, TCP clients and
1670servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>. 2544servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
1671 2545
1672Asynchronous DNS: L<AnyEvent::DNS>. 2546Asynchronous DNS: L<AnyEvent::DNS>.
1673 2547
1674Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 2548Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>,
2549L<Coro::Event>,
1675 2550
1676Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 2551Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
2552L<AnyEvent::HTTP>.
1677 2553
1678 2554
1679=head1 AUTHOR 2555=head1 AUTHOR
1680 2556
1681 Marc Lehmann <schmorp@schmorp.de> 2557 Marc Lehmann <schmorp@schmorp.de>
1682 http://home.schmorp.de/ 2558 http://home.schmorp.de/
1683 2559
1684=cut 2560=cut
1685 2561
16861 25621
1687 2563

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines