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.59 by root, Thu Apr 24 08:38:13 2008 UTC vs.
Revision 1.81 by root, Fri Apr 25 13:05:17 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
… …
78 78
79The interface itself is vaguely similar, but not identical to the L<Event> 79The interface itself is vaguely similar, but not identical to the L<Event>
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 83to detect the currently loaded event loop by probing whether one of the
84the following modules is already loaded: L<Coro::EV>, L<Coro::Event>, 84following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>,
85L<EV>, L<Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>. The first one 85L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>,
86found is used. If none are found, the module tries to load these modules 86L<POE>. The first one found is used. If none are found, the module tries
87(excluding Event::Lib and Qt) in the order given. The first one that can 87to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl
88adaptor 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 89be 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 90found, AnyEvent will fall back to a pure-perl event loop, which is not
90very efficient, but should work everywhere. 91very efficient, but should work everywhere.
91 92
92Because AnyEvent first checks for modules that are already loaded, loading 93Because AnyEvent first checks for modules that are already loaded, loading
… …
135 136
136Note that C<my $w; $w => combination. This is necessary because in Perl, 137Note that C<my $w; $w => combination. This is necessary because in Perl,
137my variables are only visible after the statement in which they are 138my variables are only visible after the statement in which they are
138declared. 139declared.
139 140
140=head2 IO WATCHERS 141=head2 I/O WATCHERS
141 142
142You can create an I/O watcher by calling the C<< AnyEvent->io >> method 143You can create an I/O watcher by calling the C<< AnyEvent->io >> method
143with the following mandatory key-value pairs as arguments: 144with the following mandatory key-value pairs as arguments:
144 145
145C<fh> the Perl I<file handle> (I<not> file descriptor) to watch for 146C<fh> the Perl I<file handle> (I<not> file descriptor) to watch for
… …
358 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 359 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
359 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. 360 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
360 AnyEvent::Impl::EV based on EV (an interface to libev, best choice). 361 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
361 AnyEvent::Impl::Event based on Event, second best choice. 362 AnyEvent::Impl::Event based on Event, second best choice.
362 AnyEvent::Impl::Glib based on Glib, third-best choice. 363 AnyEvent::Impl::Glib based on Glib, third-best choice.
364 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
363 AnyEvent::Impl::Tk based on Tk, very bad choice. 365 AnyEvent::Impl::Tk based on Tk, very bad choice.
364 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
365 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).
366 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.
367 379
368=item AnyEvent::detect 380=item AnyEvent::detect
369 381
370Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 382Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
371if necessary. You should only call this function right before you would 383if necessary. You should only call this function right before you would
… …
422no warnings; 434no warnings;
423use strict; 435use strict;
424 436
425use Carp; 437use Carp;
426 438
427our $VERSION = '3.2'; 439our $VERSION = '3.3';
428our $MODEL; 440our $MODEL;
429 441
430our $AUTOLOAD; 442our $AUTOLOAD;
431our @ISA; 443our @ISA;
432 444
… …
439 [Coro::Event:: => AnyEvent::Impl::CoroEvent::], 451 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
440 [EV:: => AnyEvent::Impl::EV::], 452 [EV:: => AnyEvent::Impl::EV::],
441 [Event:: => AnyEvent::Impl::Event::], 453 [Event:: => AnyEvent::Impl::Event::],
442 [Glib:: => AnyEvent::Impl::Glib::], 454 [Glib:: => AnyEvent::Impl::Glib::],
443 [Tk:: => AnyEvent::Impl::Tk::], 455 [Tk:: => AnyEvent::Impl::Tk::],
456 [Wx:: => AnyEvent::Impl::POE::],
457 [Prima:: => AnyEvent::Impl::POE::],
444 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 458 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
445); 459 # everything below here will not be autoprobed as the pureperl backend should work everywhere
446my @models_detect = ( 460 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
447 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 461 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
448 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 462 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
449); 463);
450 464
451our %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);
452 466
453sub detect() { 467sub detect() {
… …
457 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 471 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
458 my $model = "AnyEvent::Impl::$1"; 472 my $model = "AnyEvent::Impl::$1";
459 if (eval "require $model") { 473 if (eval "require $model") {
460 $MODEL = $model; 474 $MODEL = $model;
461 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;
462 } 478 }
463 } 479 }
464 480
465 # check for already loaded models 481 # check for already loaded models
466 unless ($MODEL) { 482 unless ($MODEL) {
467 for (@REGISTRY, @models, @models_detect) { 483 for (@REGISTRY, @models) {
468 my ($package, $model) = @$_; 484 my ($package, $model) = @$_;
469 if (${"$package\::VERSION"} > 0) { 485 if (${"$package\::VERSION"} > 0) {
470 if (eval "require $model") { 486 if (eval "require $model") {
471 $MODEL = $model; 487 $MODEL = $model;
472 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 488 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1;
… …
659 675
660=over 4 676=over 4
661 677
662=item C<PERL_ANYEVENT_VERBOSE> 678=item C<PERL_ANYEVENT_VERBOSE>
663 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
664When 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
665model it chooses. 689model it chooses.
666 690
667=item C<PERL_ANYEVENT_MODEL> 691=item C<PERL_ANYEVENT_MODEL>
668 692
… …
682 706
683=back 707=back
684 708
685=head1 EXAMPLE PROGRAM 709=head1 EXAMPLE PROGRAM
686 710
687The following program uses an IO watcher to read data from STDIN, a timer 711The following program uses an I/O watcher to read data from STDIN, a timer
688to display a message once per second, and a condition variable to quit the 712to display a message once per second, and a condition variable to quit the
689program when the user enters quit: 713program when the user enters quit:
690 714
691 use AnyEvent; 715 use AnyEvent;
692 716
… …
836 $quit->broadcast; 860 $quit->broadcast;
837 }); 861 });
838 862
839 $quit->wait; 863 $quit->wait;
840 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 I/O watchers (watching STDOUT, a pty, to
873become writable, which it is), lets them fire exactly once and destroys
874them again.
875
876Rewriting the benchmark to use many different sockets instead of using
877the same filehandle for all I/O watchers results in a much longer runtime
878(socket creation is expensive), but qualitatively the same figures, so it
879was not used.
880
881=head2 Explanation of the columns
882
883I<watcher> is the number of event watchers created/destroyed. Since
884different event models feature vastly different performances, each event
885loop was given a number of watchers so that overall runtime is acceptable
886and similar between tested event loop (and keep them from crashing): Glib
887would probably take thousands of years if asked to process the same number
888of watchers as EV in this benchmark.
889
890I<bytes> is the number of bytes (as measured by the resident set size,
891RSS) consumed by each watcher. This method of measuring captures both C
892and Perl-based overheads.
893
894I<create> is the time, in microseconds (millionths of seconds), that it
895takes to create a single watcher. The callback is a closure shared between
896all watchers, to avoid adding memory overhead. That means closure creation
897and memory usage is not included in the figures.
898
899I<invoke> is the time, in microseconds, used to invoke a simple
900callback. The callback simply counts down a Perl variable and after it was
901invoked "watcher" times, it would C<< ->broadcast >> a condvar once to
902signal the end of this phase.
903
904I<destroy> is the time, in microseconds, that it takes to destroy a single
905watcher.
906
907=head2 Results
908
909 name watchers bytes create invoke destroy comment
910 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
911 EV/Any 100000 610 3.52 0.91 0.75 EV + AnyEvent watchers
912 CoroEV/Any 100000 610 3.49 0.92 0.75 coroutines + Coro::Signal
913 Perl/Any 100000 513 4.91 0.92 1.15 pure perl implementation
914 Event/Event 16000 523 28.05 21.38 0.86 Event native interface
915 Event/Any 16000 943 34.43 20.48 1.39 Event + AnyEvent watchers
916 Glib/Any 16000 1357 96.99 12.55 55.51 quadratic behaviour
917 Tk/Any 2000 1855 27.01 66.61 14.03 SEGV with >> 2000 watchers
918 POE/Event 2000 6644 108.15 768.19 14.33 via POE::Loop::Event
919 POE/Select 2000 6343 94.69 807.65 562.69 via POE::Loop::Select
920
921=head2 Discussion
922
923The benchmark does I<not> measure scalability of the event loop very
924well. For example, a select-based event loop (such as the pure perl one)
925can never compete with an event loop that uses epoll when the number of
926file descriptors grows high. In this benchmark, all events become ready at
927the same time, so select/poll-based implementations get an unnatural speed
928boost.
929
930C<EV> is the sole leader regarding speed and memory use, which are both
931maximal/minimal, respectively. Even when going through AnyEvent, there are
932only two event loops that use slightly less memory (the C<Event> module
933natively and the pure perl backend), and no faster event models, not even
934C<Event> natively.
935
936The pure perl implementation is hit in a few sweet spots (both the
937zero timeout and the use of a single fd hit optimisations in the perl
938interpreter and the backend itself, and all watchers become ready at the
939same time). Nevertheless this shows that it adds very little overhead in
940itself. Like any select-based backend its performance becomes really bad
941with lots of file descriptors (and few of them active), of course, but
942this was not subject of this benchmark.
943
944The C<Event> module has a relatively high setup and callback invocation cost,
945but overall scores on the third place.
946
947C<Glib>'s memory usage is quite a bit bit higher, but it features a
948faster callback invocation and overall ends up in the same class as
949C<Event>. However, Glib scales extremely badly, doubling the number of
950watchers increases the processing time by more than a factor of four,
951making it completely unusable when using larger numbers of watchers
952(note that only a single file descriptor was used in the benchmark, so
953inefficiencies of C<poll> do not account for this).
954
955The C<Tk> adaptor works relatively well. The fact that it crashes with
956more than 2000 watchers is a big setback, however, as correctness takes
957precedence over speed. Nevertheless, its performance is surprising, as the
958file descriptor is dup()ed for each watcher. This shows that the dup()
959employed by some adaptors is not a big performance issue (it does incur a
960hidden memory cost inside the kernel, though, that is not reflected in the
961figures above).
962
963C<POE>, regardless of underlying event loop (wether using its pure perl
964select-based backend or the Event module) shows abysmal performance and
965memory usage: Watchers use almost 30 times as much memory as EV watchers,
966and 10 times as much memory as both Event or EV via AnyEvent. Watcher
967invocation is almost 900 times slower than with AnyEvent's pure perl
968implementation. The design of the POE adaptor class in AnyEvent can not
969really account for this, as session creation overhead is small compared
970to execution of the state machine, which is coded pretty optimally within
971L<AnyEvent::Impl::POE>. POE simply seems to be abysmally slow.
972
973=head2 Summary
974
975Using EV through AnyEvent is faster than any other event loop, but most
976event loops have acceptable performance with or without AnyEvent.
977
978The overhead AnyEvent adds is usually much smaller than the overhead of
979the actual event loop, only with extremely fast event loops such as the EV
980adds AnyEvent significant overhead.
981
982And you should simply avoid POE like the plague if you want performance or
983reasonable memory usage.
984
985
841=head1 FORK 986=head1 FORK
842 987
843Most event libraries are not fork-safe. The ones who are usually are 988Most event libraries are not fork-safe. The ones who are usually are
844because they are so inefficient. Only L<EV> is fully fork-aware. 989because they are so inefficient. Only L<EV> is fully fork-aware.
845 990
846If you have to fork, you must either do so I<before> creating your first 991If you have to fork, you must either do so I<before> creating your first
847watcher OR you must not use AnyEvent at all in the child. 992watcher OR you must not use AnyEvent at all in the child.
993
848 994
849=head1 SECURITY CONSIDERATIONS 995=head1 SECURITY CONSIDERATIONS
850 996
851AnyEvent can be forced to load any event model via 997AnyEvent can be forced to load any event model via
852$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to 998$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to
… …
860 1006
861 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1007 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
862 1008
863 use AnyEvent; 1009 use AnyEvent;
864 1010
1011
865=head1 SEE ALSO 1012=head1 SEE ALSO
866 1013
867Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1014Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
868L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>, 1015L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
869L<Event::Lib>, L<Qt>. 1016L<Event::Lib>, L<Qt>, L<POE>.
870 1017
871Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1018Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
872L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1019L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
873L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1020L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
874L<AnyEvent::Impl::Qt>. 1021L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>.
875 1022
876Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1023Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
1024
877 1025
878=head1 AUTHOR 1026=head1 AUTHOR
879 1027
880 Marc Lehmann <schmorp@schmorp.de> 1028 Marc Lehmann <schmorp@schmorp.de>
881 http://home.schmorp.de/ 1029 http://home.schmorp.de/

Diff Legend

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