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.2 by root, Thu Dec 1 18:56:18 2005 UTC vs.
Revision 1.201 by root, Wed Apr 1 14:08:27 2009 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines