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.56 by root, Thu Apr 24 03:10:03 2008 UTC vs.
Revision 1.72 by root, Fri Apr 25 07:43:25 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - provide framework for multiple event loops
4 4
5EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt - various supported event loops 5EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 use AnyEvent; 9 use AnyEvent;
10 10
… …
80module. 80module.
81 81
82During the first call of any watcher-creation method, the module tries 82During the first call of any watcher-creation method, the module tries
83to detect the currently loaded event loop by probing whether one of the 83to detect the currently loaded event loop by probing whether one of the
84following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>, 84following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>,
85L<Event>, L<Glib>, L<Tk>. The first one found is used. If none are found, 85L<Event>, L<Glib>, L<Tk>, L<AnyEvent::Impl::Perl>, L<Event::Lib>, L<Qt>,
86the module tries to load these modules in the stated order. The first one 86L<POE>. The first one found is used. If none are found, the module tries
87to load these modules (excluding Event::Lib, Qt and POE as the pure perl
88adaptor should always succeed) in the order given. The first one that can
87that can be successfully loaded will be used. If, after this, still none 89be successfully loaded will be used. If, after this, still none could be
88could be found, AnyEvent will fall back to a pure-perl event loop, which 90found, AnyEvent will fall back to a pure-perl event loop, which is not
89is not very efficient, but should work everywhere. 91very efficient, but should work everywhere.
90 92
91Because AnyEvent first checks for modules that are already loaded, loading 93Because AnyEvent first checks for modules that are already loaded, loading
92an event model explicitly before first using AnyEvent will likely make 94an event model explicitly before first using AnyEvent will likely make
93that model the default. For example: 95that model the default. For example:
94 96
… …
206 208
207There are two ways to handle timers: based on real time (relative, "fire 209There are two ways to handle timers: based on real time (relative, "fire
208in 10 seconds") and based on wallclock time (absolute, "fire at 12 210in 10 seconds") and based on wallclock time (absolute, "fire at 12
209o'clock"). 211o'clock").
210 212
211While most event loops expect timers to specified in a relative way, they use 213While most event loops expect timers to specified in a relative way, they
212absolute time internally. This makes a difference when your clock "jumps", 214use absolute time internally. This makes a difference when your clock
213for example, when ntp decides to set your clock backwards from the wrong 2014-01-01 to 215"jumps", for example, when ntp decides to set your clock backwards from
2142008-01-01, a watcher that you created to fire "after" a second might actually take 216the wrong date of 2014-01-01 to 2008-01-01, a watcher that is supposed to
215six years to finally fire. 217fire "after" a second might actually take six years to finally fire.
216 218
217AnyEvent cannot compensate for this. The only event loop that is conscious 219AnyEvent cannot compensate for this. The only event loop that is conscious
218about these issues is L<EV>, which offers both relative (ev_timer) and 220about these issues is L<EV>, which offers both relative (ev_timer, based
219absolute (ev_periodic) timers. 221on true relative time) and absolute (ev_periodic, based on wallclock time)
222timers.
220 223
221AnyEvent always prefers relative timers, if available, matching the 224AnyEvent always prefers relative timers, if available, matching the
222AnyEvent API. 225AnyEvent API.
223 226
224=head2 SIGNAL WATCHERS 227=head2 SIGNAL WATCHERS
225 228
226You can watch for signals using a signal watcher, C<signal> is the signal 229You can watch for signals using a signal watcher, C<signal> is the signal
227I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 230I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
228be invoked whenever a signal occurs. 231be invoked whenever a signal occurs.
229 232
230Multiple signals occurances can be clumped together into one callback 233Multiple signal occurances can be clumped together into one callback
231invocation, and callback invocation will be synchronous. synchronous means 234invocation, and callback invocation will be synchronous. synchronous means
232that it might take a while until the signal gets handled by the process, 235that it might take a while until the signal gets handled by the process,
233but it is guarenteed not to interrupt any other callbacks. 236but it is guarenteed not to interrupt any other callbacks.
234 237
235The main advantage of using these watchers is that you can share a signal 238The main advantage of using these watchers is that you can share a signal
… …
360 AnyEvent::Impl::Glib based on Glib, third-best choice. 363 AnyEvent::Impl::Glib based on Glib, third-best choice.
361 AnyEvent::Impl::Tk based on Tk, very bad choice. 364 AnyEvent::Impl::Tk based on Tk, very bad choice.
362 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. 365 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
363 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 366 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
364 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 367 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
368 AnyEvent::Impl::POE based on POE, not generic enough for full support.
369
370There is no support for WxWidgets, as WxWidgets has no support for
371watching file handles. However, you can use WxWidgets through the
372POE Adaptor, as POE has a Wx backend that simply polls 20 times per
373second, which was considered to be too horrible to even consider for
374AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
375it's adaptor.
376
377AnyEvent knows about L<Prima> and L<Wx> and will try to use L<POE> when
378autodetecting them.
365 379
366=item AnyEvent::detect 380=item AnyEvent::detect
367 381
368Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 382Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
369if necessary. You should only call this function right before you would 383if necessary. You should only call this function right before you would
… …
420no warnings; 434no warnings;
421use strict; 435use strict;
422 436
423use Carp; 437use Carp;
424 438
425our $VERSION = '3.12'; 439our $VERSION = '3.3';
426our $MODEL; 440our $MODEL;
427 441
428our $AUTOLOAD; 442our $AUTOLOAD;
429our @ISA; 443our @ISA;
430 444
… …
437 [Coro::Event:: => AnyEvent::Impl::CoroEvent::], 451 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
438 [EV:: => AnyEvent::Impl::EV::], 452 [EV:: => AnyEvent::Impl::EV::],
439 [Event:: => AnyEvent::Impl::Event::], 453 [Event:: => AnyEvent::Impl::Event::],
440 [Glib:: => AnyEvent::Impl::Glib::], 454 [Glib:: => AnyEvent::Impl::Glib::],
441 [Tk:: => AnyEvent::Impl::Tk::], 455 [Tk:: => AnyEvent::Impl::Tk::],
456 [Wx:: => AnyEvent::Impl::POE::],
457 [Prima:: => AnyEvent::Impl::POE::],
442 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 458 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
443); 459 # everything below here will not be autoprobed as the pureperl backend should work everywhere
444my @models_detect = ( 460 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
445 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 461 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
446 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 462 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
447); 463);
448 464
449our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY); 465our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY);
450 466
451sub detect() { 467sub detect() {
… …
455 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 471 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
456 my $model = "AnyEvent::Impl::$1"; 472 my $model = "AnyEvent::Impl::$1";
457 if (eval "require $model") { 473 if (eval "require $model") {
458 $MODEL = $model; 474 $MODEL = $model;
459 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1; 475 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1;
476 } else {
477 warn "AnyEvent: unable to load model '$model' (from \$PERL_ANYEVENT_MODEL):\n$@" if $verbose;
460 } 478 }
461 } 479 }
462 480
463 # check for already loaded models 481 # check for already loaded models
464 unless ($MODEL) { 482 unless ($MODEL) {
465 for (@REGISTRY, @models, @models_detect) { 483 for (@REGISTRY, @models) {
466 my ($package, $model) = @$_; 484 my ($package, $model) = @$_;
467 if (${"$package\::VERSION"} > 0) { 485 if (${"$package\::VERSION"} > 0) {
468 if (eval "require $model") { 486 if (eval "require $model") {
469 $MODEL = $model; 487 $MODEL = $model;
470 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 488 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1;
… …
657 675
658=over 4 676=over 4
659 677
660=item C<PERL_ANYEVENT_VERBOSE> 678=item C<PERL_ANYEVENT_VERBOSE>
661 679
680By default, AnyEvent will be completely silent except in fatal
681conditions. You can set this environment variable to make AnyEvent more
682talkative.
683
684When set to C<1> or higher, causes AnyEvent to warn about unexpected
685conditions, such as not being able to load the event model specified by
686C<PERL_ANYEVENT_MODEL>.
687
662When set to C<2> or higher, cause AnyEvent to report to STDERR which event 688When set to C<2> or higher, cause AnyEvent to report to STDERR which event
663model it chooses. 689model it chooses.
664 690
665=item C<PERL_ANYEVENT_MODEL> 691=item C<PERL_ANYEVENT_MODEL>
666 692
… …
834 $quit->broadcast; 860 $quit->broadcast;
835 }); 861 });
836 862
837 $quit->wait; 863 $quit->wait;
838 864
865
866=head1 BENCHMARK
867
868To give you an idea of the performance and overheads that AnyEvent adds
869over the event loops themselves (and to give you an impression of the
870speed of various event loops), here is a benchmark of various supported
871event models natively and with anyevent. The benchmark creates a lot of
872timers (with a zero timeout) and io watchers (watching STDOUT, a pty, to
873become writable, which it is), lets them fire exactly once and destroys
874them again.
875
876=head2 Explanation of the columns
877
878I<watcher> is the number of event watchers created/destroyed. Since
879different event models feature vastly different performances, each event
880loop was given a number of watchers so that overall runtime is acceptable
881and similar between tested event loop (and keep them from crashing): Glib
882would probably take thousands of years if asked to process the same number
883of watchers as EV in this benchmark.
884
885I<bytes> is the number of bytes (as measured by the resident set size,
886RSS) consumed by each watcher. This method of measuring captures both C
887and Perl-based overheads.
888
889I<create> is the time, in microseconds (millionths of seconds), that it
890takes to create a single watcher. The callback is a closure shared between
891all watchers, to avoid adding memory overhead. That means closure creation
892and memory usage is not included in the figures.
893
894I<invoke> is the time, in microseconds, used to invoke a simple
895callback. The callback simply counts down a Perl variable and after it was
896invoked "watcher" times, it would C<< ->broadcast >> a condvar once to
897signal the end of this phase.
898
899I<destroy> is the time, in microseconds, that it takes to destroy a single
900watcher.
901
902=head2 Results
903
904 name watcher bytes create invoke destroy comment
905 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
906 EV/Any 100000 610 3.52 0.91 0.75 EV + AnyEvent watchers
907 CoroEV/Any 100000 610 3.49 0.92 0.75 coroutines + Coro::Signal
908 Perl/Any 16000 654 4.64 1.22 0.77 pure perl implementation
909 Event/Event 16000 523 28.05 21.38 0.86 Event native interface
910 Event/Any 16000 943 34.43 20.48 1.39 Event + AnyEvent watchers
911 Glib/Any 16000 1357 96.99 12.55 55.51 quadratic behaviour
912 Tk/Any 2000 1855 27.01 66.61 14.03 SEGV with >> 2000 watchers
913 POE/Event 2000 6644 108.15 768.19 14.33 via POE::Loop::Event
914 POE/Select 2000 6343 94.69 807.65 562.69 via POE::Loop::Select
915
916=head2 Discussion
917
918The benchmark does I<not> measure scalability of the event loop very
919well. For example, a select-based event loop (such as the pure perl one)
920can never compete with an event loop that uses epoll when the number of
921file descriptors grows high. In this benchmark, only a single filehandle
922is used (although some of the AnyEvent adaptors dup() its file descriptor
923to worka round bugs).
924
925C<EV> is the sole leader regarding speed and memory use, which are both
926maximal/minimal, respectively. Even when going through AnyEvent, there is
927only one event loop that uses less memory (the C<Event> module natively), and
928no faster event model, not event C<Event> natively.
929
930The pure perl implementation is hit in a few sweet spots (both the
931zero timeout and the use of a single fd hit optimisations in the perl
932interpreter and the backend itself). Nevertheless tis shows that it
933adds very little overhead in itself. Like any select-based backend its
934performance becomes really bad with lots of file descriptors, of course,
935but this was not subjetc of this benchmark.
936
937The C<Event> module has a relatively high setup and callback invocation cost,
938but overall scores on the third place.
939
940C<Glib>'s memory usage is quite a bit bit higher, features a faster
941callback invocation and overall lands in the same class as C<Event>.
942
943The C<Tk> adaptor works relatively well, the fact that it crashes with
944more than 2000 watchers is a big setback, however, as correctness takes
945precedence over speed. Nevertheless, its performance is surprising, as the
946file descriptor is dup()ed for each watcher. This shows that the dup()
947employed by some adaptors is not a big performance issue (it does incur a
948hidden memory cost inside the kernel, though).
949
950C<POE>, regardless of underlying event loop (wether using its pure perl
951select-based backend or the Event module) shows abysmal performance and
952memory usage: Watchers use almost 30 times as much memory as EV watchers,
953and 10 times as much memory as both Event or EV via AnyEvent. Watcher
954invocation is almost 700 times slower than with AnyEvent's pure perl
955implementation. The design of the POE adaptor class in AnyEvent can not
956really account for this, as session creation overhead is small compared
957to execution of the state machine, which is coded pretty optimally within
958L<AnyEvent::Impl::POE>. POE simply seems to be abysmally slow.
959
960=head2 Summary
961
962Using EV through AnyEvent is faster than any other event loop, but most
963event loops have acceptable performance with or without AnyEvent.
964
965The overhead AnyEvent adds is usually much smaller than the overhead of
966the actual event loop, only with extremely fast event loops such as the EV
967adds Anyevent significant overhead.
968
969And you should simply avoid POE like the plague if you want performance or
970reasonable memory usage.
971
972
839=head1 FORK 973=head1 FORK
840 974
841Most event libraries are not fork-safe. The ones who are usually are 975Most event libraries are not fork-safe. The ones who are usually are
842because they are so inefficient. Only L<EV> is fully fork-aware. 976because they are so inefficient. Only L<EV> is fully fork-aware.
843 977
844If you have to fork, you must either do so I<before> creating your first 978If you have to fork, you must either do so I<before> creating your first
845watcher OR you must not use AnyEvent at all in the child. 979watcher OR you must not use AnyEvent at all in the child.
980
846 981
847=head1 SECURITY CONSIDERATIONS 982=head1 SECURITY CONSIDERATIONS
848 983
849AnyEvent can be forced to load any event model via 984AnyEvent can be forced to load any event model via
850$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to 985$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to
… …
858 993
859 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 994 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
860 995
861 use AnyEvent; 996 use AnyEvent;
862 997
998
863=head1 SEE ALSO 999=head1 SEE ALSO
864 1000
865Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1001Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
866L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>, 1002L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
867L<Event::Lib>, L<Qt>. 1003L<Event::Lib>, L<Qt>, L<POE>.
868 1004
869Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1005Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
870L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1006L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
871L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1007L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
872L<AnyEvent::Impl::Qt>. 1008L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>.
873 1009
874Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1010Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
1011
875 1012
876=head1 AUTHOR 1013=head1 AUTHOR
877 1014
878 Marc Lehmann <schmorp@schmorp.de> 1015 Marc Lehmann <schmorp@schmorp.de>
879 http://home.schmorp.de/ 1016 http://home.schmorp.de/

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines