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.64 by root, Fri Apr 25 06:54:08 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<Tk>, L<AnyEvent::Impl::Perl>, 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 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
… …
362 AnyEvent::Impl::Glib based on Glib, third-best choice. 363 AnyEvent::Impl::Glib based on Glib, third-best choice.
363 AnyEvent::Impl::Tk based on Tk, very bad choice. 364 AnyEvent::Impl::Tk based on Tk, very bad choice.
364 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. 365 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
… …
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 an doverheads that AnyEvent adds
869over the backends, here is a benchmark of various supported backends. The
870benchmark creates a lot of timers (with zero timeout) and io events
871(watching STDOUT, a pty, to become writable).
872
873Explanation of the fields:
874
875I<watcher> is the number of event watchers created/destroyed. Sicne
876different event models have vastly different performance each backend was
877handed a number of watchers so that overall runtime is acceptable and
878similar to all backends (and keep them from crashing).
879
880I<bytes> is the number of bytes (as measured by resident set size) used by
881each watcher.
882
883I<create> is the time, in microseconds, to create a single watcher.
884
885I<invoke> is the time, in microseconds, used to invoke a simple callback
886that simply counts down.
887
888I<destroy> is the time, in microseconds, to destroy a single watcher.
889
890 name watcher bytes create invoke destroy comment
891 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
892 EV/Any 100000 610 3.52 0.91 0.75
893 CoroEV/Any 100000 610 3.49 0.92 0.75 coroutines + Coro::Signal
894 Perl/Any 10000 654 4.64 1.22 0.77 pure perl implementation
895 Event/Event 10000 523 28.05 21.38 5.22 Event native interface
896 Event/Any 10000 943 34.43 20.48 1.39
897 Glib/Any 16000 1357 96.99 12.55 55.51 quadratic behaviour
898 Tk/Any 2000 1855 27.01 66.61 14.03 SEGV with >> 2000 watchers
899 POE/Select 2000 6343 94.69 807.65 562.69 POE::Loop::Select
900 POE/Event 2000 6644 108.15 768.19 14.33 POE::Loop::Event
901
902Discussion: The benchmark does I<not> bench scalability of the
903backend. For example a select-based backend (such as the pureperl one) can
904never compete with a backend using epoll. In this benchmark, only a single
905filehandle is used.
906
907EV is the sole leader regarding speed and memory use, which are both
908maximal/minimal. Even when going through AnyEvent, there is only one event
909loop that uses less memory (the Event module natively), and no faster
910event model.
911
912The pure perl implementation is hit in a few sweet spots (both the
913zero timeout and the use of a single fd hit optimisations in the perl
914interpreter and the backend itself), but it shows that it adds very little
915overhead in itself. Like any select-based backend it's performance becomes
916really bad with lots of file descriptors.
917
918The Event module has a relatively high setup and callback invocation cost,
919but overall scores on the third place.
920
921Glib has a little higher memory cost, a bit fster callback invocation and
922has a similar speed as Event.
923
924The Tk backend works relatively well, the fact that it crashes with
925more than 2000 watchers is a big setback, however, as correctness takes
926precedence over speed.
927
928POE, regardless of backend (wether it's pure perl select backend or the
929Event backend) shows abysmal performance and memory usage: Watchers use
930almost 30 times as much memory as EV watchers, and 10 times as much memory
931as both Event or EV via AnyEvent.
932
933Summary: using EV through AnyEvent is faster than any other event
934loop. The overhead AnyEvent adds can be very small, and you should avoid
935POE like the plague if you want performance or reasonable memory usage.
936
937
841=head1 FORK 938=head1 FORK
842 939
843Most event libraries are not fork-safe. The ones who are usually are 940Most event libraries are not fork-safe. The ones who are usually are
844because they are so inefficient. Only L<EV> is fully fork-aware. 941because they are so inefficient. Only L<EV> is fully fork-aware.
845 942
846If you have to fork, you must either do so I<before> creating your first 943If 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. 944watcher OR you must not use AnyEvent at all in the child.
945
848 946
849=head1 SECURITY CONSIDERATIONS 947=head1 SECURITY CONSIDERATIONS
850 948
851AnyEvent can be forced to load any event model via 949AnyEvent can be forced to load any event model via
852$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to 950$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to
… …
860 958
861 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 959 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
862 960
863 use AnyEvent; 961 use AnyEvent;
864 962
963
865=head1 SEE ALSO 964=head1 SEE ALSO
866 965
867Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 966Event 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>, 967L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
869L<Event::Lib>, L<Qt>. 968L<Event::Lib>, L<Qt>, L<POE>.
870 969
871Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 970Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
872L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 971L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
873L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 972L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
874L<AnyEvent::Impl::Qt>. 973L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>.
875 974
876Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 975Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
976
877 977
878=head1 AUTHOR 978=head1 AUTHOR
879 979
880 Marc Lehmann <schmorp@schmorp.de> 980 Marc Lehmann <schmorp@schmorp.de>
881 http://home.schmorp.de/ 981 http://home.schmorp.de/

Diff Legend

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