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.1 by root, Wed Apr 27 01:26:44 2005 UTC vs.
Revision 1.132 by root, Sun May 25 01:05:27 2008 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines