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.55 by root, Wed Apr 23 11:25:42 2008 UTC vs.
Revision 1.65 by root, Fri Apr 25 06:58:12 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 - 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
… …
145events. C<poll> must be a string that is either C<r> or C<w>, which 147events. C<poll> must be a string that is either C<r> or C<w>, which
146creates a watcher waiting for "r"eadable or "w"ritable events, 148creates a watcher waiting for "r"eadable or "w"ritable events,
147respectively. C<cb> is the callback to invoke each time the file handle 149respectively. C<cb> is the callback to invoke each time the file handle
148becomes ready. 150becomes ready.
149 151
150File handles will be kept alive, so as long as the watcher exists, the 152As long as the I/O watcher exists it will keep the file descriptor or a
151file handle exists, too. 153copy of it alive/open.
152 154
153It is not allowed to close a file handle as long as any watcher is active 155It is not allowed to close a file handle as long as any watcher is active
154on the underlying file descriptor. 156on the underlying file descriptor.
155 157
156Some event loops issue spurious readyness notifications, so you should 158Some event loops issue spurious readyness notifications, so you should
… …
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
… …
353 356
354The known classes so far are: 357The known classes so far are:
355 358
356 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 359 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
357 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. 360 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
358 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 361 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
359 AnyEvent::Impl::Event based on Event, also second best choice :) 362 AnyEvent::Impl::Event based on Event, second best choice.
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.
366 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
363 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.
364 379
365=item AnyEvent::detect 380=item AnyEvent::detect
366 381
367Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 382Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
368if necessary. You should only call this function right before you would 383if necessary. You should only call this function right before you would
… …
419no warnings; 434no warnings;
420use strict; 435use strict;
421 436
422use Carp; 437use Carp;
423 438
424our $VERSION = '3.12'; 439our $VERSION = '3.3';
425our $MODEL; 440our $MODEL;
426 441
427our $AUTOLOAD; 442our $AUTOLOAD;
428our @ISA; 443our @ISA;
429 444
… …
436 [Coro::Event:: => AnyEvent::Impl::CoroEvent::], 451 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
437 [EV:: => AnyEvent::Impl::EV::], 452 [EV:: => AnyEvent::Impl::EV::],
438 [Event:: => AnyEvent::Impl::Event::], 453 [Event:: => AnyEvent::Impl::Event::],
439 [Glib:: => AnyEvent::Impl::Glib::], 454 [Glib:: => AnyEvent::Impl::Glib::],
440 [Tk:: => AnyEvent::Impl::Tk::], 455 [Tk:: => AnyEvent::Impl::Tk::],
456 [Wx:: => AnyEvent::Impl::POE::],
457 [Prima:: => AnyEvent::Impl::POE::],
441 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 458 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
459 # everything below here will not be autoprobed as the pureperl backend should work everywhere
442 [Event::Lib:: => AnyEvent::Impl::EventLib::], 460 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
461 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
462 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
443); 463);
444 464
445our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY); 465our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY);
446 466
447sub detect() { 467sub detect() {
448 unless ($MODEL) { 468 unless ($MODEL) {
449 no strict 'refs'; 469 no strict 'refs';
450 470
451 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 471 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
452 my $model = "AnyEvent::Impl::$1"; 472 my $model = "AnyEvent::Impl::$1";
453 if (eval "require $model") { 473 if (eval "require $model") {
454 $MODEL = $model; 474 $MODEL = $model;
455 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;
456 } 478 }
457 } 479 }
458 480
459 # check for already loaded models 481 # check for already loaded models
460 unless ($MODEL) { 482 unless ($MODEL) {
… …
653 675
654=over 4 676=over 4
655 677
656=item C<PERL_ANYEVENT_VERBOSE> 678=item C<PERL_ANYEVENT_VERBOSE>
657 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
658When 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
659model it chooses. 689model it chooses.
660 690
661=item C<PERL_ANYEVENT_MODEL> 691=item C<PERL_ANYEVENT_MODEL>
662 692
… …
830 $quit->broadcast; 860 $quit->broadcast;
831 }); 861 });
832 862
833 $quit->wait; 863 $quit->wait;
834 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 events (watching STDOUT, a pty, to become
872writable), lets them fire exactly once and destroys them again.
873
874Explanation of the fields:
875
876I<watcher> is the number of event watchers created/destroyed. Sicne
877different event models have vastly different performance each backend was
878handed a number of watchers so that overall runtime is acceptable and
879similar to all backends (and keep them from crashing).
880
881I<bytes> is the number of bytes (as measured by resident set size) used by
882each watcher.
883
884I<create> is the time, in microseconds, to create a single watcher.
885
886I<invoke> is the time, in microseconds, used to invoke a simple callback
887that simply counts down.
888
889I<destroy> is the time, in microseconds, to destroy a single watcher.
890
891 name watcher bytes create invoke destroy comment
892 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
893 EV/Any 100000 610 3.52 0.91 0.75
894 CoroEV/Any 100000 610 3.49 0.92 0.75 coroutines + Coro::Signal
895 Perl/Any 10000 654 4.64 1.22 0.77 pure perl implementation
896 Event/Event 10000 523 28.05 21.38 5.22 Event native interface
897 Event/Any 10000 943 34.43 20.48 1.39
898 Glib/Any 16000 1357 96.99 12.55 55.51 quadratic behaviour
899 Tk/Any 2000 1855 27.01 66.61 14.03 SEGV with >> 2000 watchers
900 POE/Select 2000 6343 94.69 807.65 562.69 POE::Loop::Select
901 POE/Event 2000 6644 108.15 768.19 14.33 POE::Loop::Event
902
903Discussion: The benchmark does I<not> bench scalability of the
904backend. For example a select-based backend (such as the pureperl one) can
905never compete with a backend using epoll. In this benchmark, only a single
906filehandle is used.
907
908EV is the sole leader regarding speed and memory use, which are both
909maximal/minimal. Even when going through AnyEvent, there is only one event
910loop that uses less memory (the Event module natively), and no faster
911event model.
912
913The pure perl implementation is hit in a few sweet spots (both the
914zero timeout and the use of a single fd hit optimisations in the perl
915interpreter and the backend itself), but it shows that it adds very little
916overhead in itself. Like any select-based backend it's performance becomes
917really bad with lots of file descriptors.
918
919The Event module has a relatively high setup and callback invocation cost,
920but overall scores on the third place.
921
922Glib has a little higher memory cost, a bit fster callback invocation and
923has a similar speed as Event.
924
925The Tk backend works relatively well, the fact that it crashes with
926more than 2000 watchers is a big setback, however, as correctness takes
927precedence over speed.
928
929POE, regardless of backend (wether it's pure perl select backend or the
930Event backend) shows abysmal performance and memory usage: Watchers use
931almost 30 times as much memory as EV watchers, and 10 times as much memory
932as both Event or EV via AnyEvent.
933
934Summary: using EV through AnyEvent is faster than any other event
935loop. The overhead AnyEvent adds can be very small, and you should avoid
936POE like the plague if you want performance or reasonable memory usage.
937
938
835=head1 FORK 939=head1 FORK
836 940
837Most event libraries are not fork-safe. The ones who are usually are 941Most event libraries are not fork-safe. The ones who are usually are
838because they are so inefficient. Only L<EV> is fully fork-aware. 942because they are so inefficient. Only L<EV> is fully fork-aware.
839 943
840If you have to fork, you must either do so I<before> creating your first 944If you have to fork, you must either do so I<before> creating your first
841watcher OR you must not use AnyEvent at all in the child. 945watcher OR you must not use AnyEvent at all in the child.
946
842 947
843=head1 SECURITY CONSIDERATIONS 948=head1 SECURITY CONSIDERATIONS
844 949
845AnyEvent can be forced to load any event model via 950AnyEvent can be forced to load any event model via
846$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to 951$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to
… …
854 959
855 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 960 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
856 961
857 use AnyEvent; 962 use AnyEvent;
858 963
964
859=head1 SEE ALSO 965=head1 SEE ALSO
860 966
861Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 967Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
862L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>, 968L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
863L<Event::Lib>. 969L<Event::Lib>, L<Qt>, L<POE>.
864 970
865Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 971Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
866L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 972L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
867L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>. 973L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
974L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>.
868 975
869Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 976Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
977
870 978
871=head1 AUTHOR 979=head1 AUTHOR
872 980
873 Marc Lehmann <schmorp@schmorp.de> 981 Marc Lehmann <schmorp@schmorp.de>
874 http://home.schmorp.de/ 982 http://home.schmorp.de/

Diff Legend

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