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.61 by root, Fri Apr 25 01:55: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.
365 376
366=item AnyEvent::detect 377=item AnyEvent::detect
367 378
368Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 379Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
369if necessary. You should only call this function right before you would 380if necessary. You should only call this function right before you would
… …
420no warnings; 431no warnings;
421use strict; 432use strict;
422 433
423use Carp; 434use Carp;
424 435
425our $VERSION = '3.12'; 436our $VERSION = '3.2';
426our $MODEL; 437our $MODEL;
427 438
428our $AUTOLOAD; 439our $AUTOLOAD;
429our @ISA; 440our @ISA;
430 441
… …
438 [EV:: => AnyEvent::Impl::EV::], 449 [EV:: => AnyEvent::Impl::EV::],
439 [Event:: => AnyEvent::Impl::Event::], 450 [Event:: => AnyEvent::Impl::Event::],
440 [Glib:: => AnyEvent::Impl::Glib::], 451 [Glib:: => AnyEvent::Impl::Glib::],
441 [Tk:: => AnyEvent::Impl::Tk::], 452 [Tk:: => AnyEvent::Impl::Tk::],
442 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 453 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
443); 454 # everything below here will not be autoprobed as the pureperl backend should work everywhere
444my @models_detect = ( 455 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
445 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 456 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
446 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 457 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
447); 458);
448 459
449our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY); 460our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY);
450 461
451sub detect() { 462sub detect() {
… …
455 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 466 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
456 my $model = "AnyEvent::Impl::$1"; 467 my $model = "AnyEvent::Impl::$1";
457 if (eval "require $model") { 468 if (eval "require $model") {
458 $MODEL = $model; 469 $MODEL = $model;
459 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1; 470 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1;
471 } else {
472 warn "AnyEvent: unable to load model '$model' (from \$PERL_ANYEVENT_MODEL):\n$@" if $verbose;
460 } 473 }
461 } 474 }
462 475
463 # check for already loaded models 476 # check for already loaded models
464 unless ($MODEL) { 477 unless ($MODEL) {
465 for (@REGISTRY, @models, @models_detect) { 478 for (@REGISTRY, @models) {
466 my ($package, $model) = @$_; 479 my ($package, $model) = @$_;
467 if (${"$package\::VERSION"} > 0) { 480 if (${"$package\::VERSION"} > 0) {
468 if (eval "require $model") { 481 if (eval "require $model") {
469 $MODEL = $model; 482 $MODEL = $model;
470 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 483 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1;
… …
657 670
658=over 4 671=over 4
659 672
660=item C<PERL_ANYEVENT_VERBOSE> 673=item C<PERL_ANYEVENT_VERBOSE>
661 674
675By default, AnyEvent will be completely silent except in fatal
676conditions. You can set this environment variable to make AnyEvent more
677talkative.
678
679When set to C<1> or higher, causes AnyEvent to warn about unexpected
680conditions, such as not being able to load the event model specified by
681C<PERL_ANYEVENT_MODEL>.
682
662When set to C<2> or higher, cause AnyEvent to report to STDERR which event 683When set to C<2> or higher, cause AnyEvent to report to STDERR which event
663model it chooses. 684model it chooses.
664 685
665=item C<PERL_ANYEVENT_MODEL> 686=item C<PERL_ANYEVENT_MODEL>
666 687
… …
862 883
863=head1 SEE ALSO 884=head1 SEE ALSO
864 885
865Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 886Event 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>, 887L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
867L<Event::Lib>, L<Qt>. 888L<Event::Lib>, L<Qt>, L<POE>.
868 889
869Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 890Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
870L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 891L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
871L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 892L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
872L<AnyEvent::Impl::Qt>. 893L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>.
873 894
874Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 895Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
875 896
876=head1 AUTHOR 897=head1 AUTHOR
877 898

Diff Legend

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