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.57 by root, Thu Apr 24 03:19:28 2008 UTC vs.
Revision 1.67 by root, Fri Apr 25 06:58:38 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
… …
207 208
208There 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
209in 10 seconds") and based on wallclock time (absolute, "fire at 12 210in 10 seconds") and based on wallclock time (absolute, "fire at 12
210o'clock"). 211o'clock").
211 212
212While 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
213absolute time internally. This makes a difference when your clock "jumps", 214use absolute time internally. This makes a difference when your clock
214for 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
2152008-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
216six years to finally fire. 217fire "after" a second might actually take six years to finally fire.
217 218
218AnyEvent cannot compensate for this. The only event loop that is conscious 219AnyEvent cannot compensate for this. The only event loop that is conscious
219about 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
220absolute (ev_periodic) timers. 221on true relative time) and absolute (ev_periodic, based on wallclock time)
222timers.
221 223
222AnyEvent always prefers relative timers, if available, matching the 224AnyEvent always prefers relative timers, if available, matching the
223AnyEvent API. 225AnyEvent API.
224 226
225=head2 SIGNAL WATCHERS 227=head2 SIGNAL WATCHERS
226 228
227You 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
228I<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
229be invoked whenever a signal occurs. 231be invoked whenever a signal occurs.
230 232
231Multiple signals occurances can be clumped together into one callback 233Multiple signal occurances can be clumped together into one callback
232invocation, and callback invocation will be synchronous. synchronous means 234invocation, and callback invocation will be synchronous. synchronous means
233that 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,
234but it is guarenteed not to interrupt any other callbacks. 236but it is guarenteed not to interrupt any other callbacks.
235 237
236The 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
… …
361 AnyEvent::Impl::Glib based on Glib, third-best choice. 363 AnyEvent::Impl::Glib based on Glib, third-best choice.
362 AnyEvent::Impl::Tk based on Tk, very bad choice. 364 AnyEvent::Impl::Tk based on Tk, very bad choice.
363 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. 365 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
364 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).
365 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.
366 379
367=item AnyEvent::detect 380=item AnyEvent::detect
368 381
369Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 382Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
370if necessary. You should only call this function right before you would 383if necessary. You should only call this function right before you would
… …
421no warnings; 434no warnings;
422use strict; 435use strict;
423 436
424use Carp; 437use Carp;
425 438
426our $VERSION = '3.12'; 439our $VERSION = '3.3';
427our $MODEL; 440our $MODEL;
428 441
429our $AUTOLOAD; 442our $AUTOLOAD;
430our @ISA; 443our @ISA;
431 444
… …
438 [Coro::Event:: => AnyEvent::Impl::CoroEvent::], 451 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
439 [EV:: => AnyEvent::Impl::EV::], 452 [EV:: => AnyEvent::Impl::EV::],
440 [Event:: => AnyEvent::Impl::Event::], 453 [Event:: => AnyEvent::Impl::Event::],
441 [Glib:: => AnyEvent::Impl::Glib::], 454 [Glib:: => AnyEvent::Impl::Glib::],
442 [Tk:: => AnyEvent::Impl::Tk::], 455 [Tk:: => AnyEvent::Impl::Tk::],
456 [Wx:: => AnyEvent::Impl::POE::],
457 [Prima:: => AnyEvent::Impl::POE::],
443 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 458 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
444); 459 # everything below here will not be autoprobed as the pureperl backend should work everywhere
445my @models_detect = ( 460 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
446 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 461 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
447 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 462 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
448); 463);
449 464
450our %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);
451 466
452sub detect() { 467sub detect() {
… …
456 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 471 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
457 my $model = "AnyEvent::Impl::$1"; 472 my $model = "AnyEvent::Impl::$1";
458 if (eval "require $model") { 473 if (eval "require $model") {
459 $MODEL = $model; 474 $MODEL = $model;
460 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;
461 } 478 }
462 } 479 }
463 480
464 # check for already loaded models 481 # check for already loaded models
465 unless ($MODEL) { 482 unless ($MODEL) {
466 for (@REGISTRY, @models, @models_detect) { 483 for (@REGISTRY, @models) {
467 my ($package, $model) = @$_; 484 my ($package, $model) = @$_;
468 if (${"$package\::VERSION"} > 0) { 485 if (${"$package\::VERSION"} > 0) {
469 if (eval "require $model") { 486 if (eval "require $model") {
470 $MODEL = $model; 487 $MODEL = $model;
471 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 488 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1;
… …
658 675
659=over 4 676=over 4
660 677
661=item C<PERL_ANYEVENT_VERBOSE> 678=item C<PERL_ANYEVENT_VERBOSE>
662 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
663When 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
664model it chooses. 689model it chooses.
665 690
666=item C<PERL_ANYEVENT_MODEL> 691=item C<PERL_ANYEVENT_MODEL>
667 692
… …
835 $quit->broadcast; 860 $quit->broadcast;
836 }); 861 });
837 862
838 $quit->wait; 863 $quit->wait;
839 864
865
866=head1 BENCHMARK
867
868To give you an idea of the performance and overheads that AnyEvent adds
869over the backends directly, here is a benchmark of various supported event
870models natively and with anyevent. The benchmark creates a lot of timers
871(with a zero timeout) and io watchers (watching STDOUT, a pty, to become
872writable, which it is), lets them fire exactly once and destroys them
873again.
874
875Explanation of the fields:
876
877I<watcher> is the number of event watchers created/destroyed. Sicne
878different event models have vastly different performance each backend was
879handed a number of watchers so that overall runtime is acceptable and
880similar to all backends (and keep them from crashing).
881
882I<bytes> is the number of bytes (as measured by resident set size) used by
883each watcher.
884
885I<create> is the time, in microseconds, to create a single watcher.
886
887I<invoke> is the time, in microseconds, used to invoke a simple callback
888that simply counts down.
889
890I<destroy> is the time, in microseconds, to destroy a single watcher.
891
892 name watcher bytes create invoke destroy comment
893 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
894 EV/Any 100000 610 3.52 0.91 0.75
895 CoroEV/Any 100000 610 3.49 0.92 0.75 coroutines + Coro::Signal
896 Perl/Any 10000 654 4.64 1.22 0.77 pure perl implementation
897 Event/Event 10000 523 28.05 21.38 5.22 Event native interface
898 Event/Any 10000 943 34.43 20.48 1.39
899 Glib/Any 16000 1357 96.99 12.55 55.51 quadratic behaviour
900 Tk/Any 2000 1855 27.01 66.61 14.03 SEGV with >> 2000 watchers
901 POE/Select 2000 6343 94.69 807.65 562.69 POE::Loop::Select
902 POE/Event 2000 6644 108.15 768.19 14.33 POE::Loop::Event
903
904Discussion: The benchmark does I<not> bench scalability of the
905backend. For example a select-based backend (such as the pureperl one) can
906never compete with a backend using epoll. In this benchmark, only a single
907filehandle is used.
908
909EV is the sole leader regarding speed and memory use, which are both
910maximal/minimal. Even when going through AnyEvent, there is only one event
911loop that uses less memory (the Event module natively), and no faster
912event model.
913
914The pure perl implementation is hit in a few sweet spots (both the
915zero timeout and the use of a single fd hit optimisations in the perl
916interpreter and the backend itself), but it shows that it adds very little
917overhead in itself. Like any select-based backend it's performance becomes
918really bad with lots of file descriptors.
919
920The Event module has a relatively high setup and callback invocation cost,
921but overall scores on the third place.
922
923Glib has a little higher memory cost, a bit fster callback invocation and
924has a similar speed as Event.
925
926The Tk backend works relatively well, the fact that it crashes with
927more than 2000 watchers is a big setback, however, as correctness takes
928precedence over speed.
929
930POE, regardless of backend (wether it's pure perl select backend or the
931Event backend) shows abysmal performance and memory usage: Watchers use
932almost 30 times as much memory as EV watchers, and 10 times as much memory
933as both Event or EV via AnyEvent.
934
935Summary: using EV through AnyEvent is faster than any other event
936loop. The overhead AnyEvent adds can be very small, and you should avoid
937POE like the plague if you want performance or reasonable memory usage.
938
939
840=head1 FORK 940=head1 FORK
841 941
842Most event libraries are not fork-safe. The ones who are usually are 942Most event libraries are not fork-safe. The ones who are usually are
843because they are so inefficient. Only L<EV> is fully fork-aware. 943because they are so inefficient. Only L<EV> is fully fork-aware.
844 944
845If you have to fork, you must either do so I<before> creating your first 945If you have to fork, you must either do so I<before> creating your first
846watcher OR you must not use AnyEvent at all in the child. 946watcher OR you must not use AnyEvent at all in the child.
947
847 948
848=head1 SECURITY CONSIDERATIONS 949=head1 SECURITY CONSIDERATIONS
849 950
850AnyEvent can be forced to load any event model via 951AnyEvent can be forced to load any event model via
851$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to 952$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to
… …
859 960
860 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 961 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
861 962
862 use AnyEvent; 963 use AnyEvent;
863 964
965
864=head1 SEE ALSO 966=head1 SEE ALSO
865 967
866Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 968Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
867L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>, 969L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
868L<Event::Lib>, L<Qt>. 970L<Event::Lib>, L<Qt>, L<POE>.
869 971
870Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 972Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
871L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 973L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
872L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 974L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
873L<AnyEvent::Impl::Qt>. 975L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>.
874 976
875Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 977Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
978
876 979
877=head1 AUTHOR 980=head1 AUTHOR
878 981
879 Marc Lehmann <schmorp@schmorp.de> 982 Marc Lehmann <schmorp@schmorp.de>
880 http://home.schmorp.de/ 983 http://home.schmorp.de/

Diff Legend

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