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.142 by root, Tue May 27 02:34:30 2008 UTC vs.
Revision 1.252 by root, Tue Jul 21 03:30:02 2009 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines