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.60 by root, Fri Apr 25 01:05:26 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 - 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 the 83to detect the currently loaded event loop by probing whether one of
84following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>, 84the following modules is already loaded: L<Coro::EV>, L<Coro::Event>,
85L<Event>, L<Glib>, L<Tk>. The first one found is used. If none are found, 85L<EV>, L<Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>. The first one
86the module tries to load these modules in the stated order. The first one 86found is used. If none are found, the module tries to load these modules
87(excluding Event::Lib and Qt) in the order given. The first one that can
87that can be successfully loaded will be used. If, after this, still none 88be 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 89found, AnyEvent will fall back to a pure-perl event loop, which is not
89is not very efficient, but should work everywhere. 90very efficient, but should work everywhere.
90 91
91Because AnyEvent first checks for modules that are already loaded, loading 92Because AnyEvent first checks for modules that are already loaded, loading
92an event model explicitly before first using AnyEvent will likely make 93an event model explicitly before first using AnyEvent will likely make
93that model the default. For example: 94that model the default. For example:
94 95
… …
145events. C<poll> must be a string that is either C<r> or C<w>, which 146events. 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, 147creates a watcher waiting for "r"eadable or "w"ritable events,
147respectively. C<cb> is the callback to invoke each time the file handle 148respectively. C<cb> is the callback to invoke each time the file handle
148becomes ready. 149becomes ready.
149 150
150File handles will be kept alive, so as long as the watcher exists, the 151As long as the I/O watcher exists it will keep the file descriptor or a
151file handle exists, too. 152copy of it alive/open.
152 153
153It is not allowed to close a file handle as long as any watcher is active 154It is not allowed to close a file handle as long as any watcher is active
154on the underlying file descriptor. 155on the underlying file descriptor.
155 156
156Some event loops issue spurious readyness notifications, so you should 157Some event loops issue spurious readyness notifications, so you should
… …
206 207
207There are two ways to handle timers: based on real time (relative, "fire 208There are two ways to handle timers: based on real time (relative, "fire
208in 10 seconds") and based on wallclock time (absolute, "fire at 12 209in 10 seconds") and based on wallclock time (absolute, "fire at 12
209o'clock"). 210o'clock").
210 211
211While most event loops expect timers to specified in a relative way, they use 212While most event loops expect timers to specified in a relative way, they
212absolute time internally. This makes a difference when your clock "jumps", 213use 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 214"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 215the wrong date of 2014-01-01 to 2008-01-01, a watcher that is supposed to
215six years to finally fire. 216fire "after" a second might actually take six years to finally fire.
216 217
217AnyEvent cannot compensate for this. The only event loop that is conscious 218AnyEvent cannot compensate for this. The only event loop that is conscious
218about these issues is L<EV>, which offers both relative (ev_timer) and 219about these issues is L<EV>, which offers both relative (ev_timer, based
219absolute (ev_periodic) timers. 220on true relative time) and absolute (ev_periodic, based on wallclock time)
221timers.
220 222
221AnyEvent always prefers relative timers, if available, matching the 223AnyEvent always prefers relative timers, if available, matching the
222AnyEvent API. 224AnyEvent API.
223 225
224=head2 SIGNAL WATCHERS 226=head2 SIGNAL WATCHERS
225 227
226You can watch for signals using a signal watcher, C<signal> is the signal 228You 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 229I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
228be invoked whenever a signal occurs. 230be invoked whenever a signal occurs.
229 231
230Multiple signals occurances can be clumped together into one callback 232Multiple signal occurances can be clumped together into one callback
231invocation, and callback invocation will be synchronous. synchronous means 233invocation, and callback invocation will be synchronous. synchronous means
232that it might take a while until the signal gets handled by the process, 234that it might take a while until the signal gets handled by the process,
233but it is guarenteed not to interrupt any other callbacks. 235but it is guarenteed not to interrupt any other callbacks.
234 236
235The main advantage of using these watchers is that you can share a signal 237The main advantage of using these watchers is that you can share a signal
… …
353 355
354The known classes so far are: 356The known classes so far are:
355 357
356 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 358 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
357 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. 359 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
358 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 360 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
359 AnyEvent::Impl::Event based on Event, also second best choice :) 361 AnyEvent::Impl::Event based on Event, second best choice.
360 AnyEvent::Impl::Glib based on Glib, third-best choice. 362 AnyEvent::Impl::Glib based on Glib, third-best choice.
361 AnyEvent::Impl::Tk based on Tk, very bad choice. 363 AnyEvent::Impl::Tk based on Tk, very bad choice.
362 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. 364 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
365 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
363 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 366 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
364 367
365=item AnyEvent::detect 368=item AnyEvent::detect
366 369
367Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 370Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
… …
419no warnings; 422no warnings;
420use strict; 423use strict;
421 424
422use Carp; 425use Carp;
423 426
424our $VERSION = '3.12'; 427our $VERSION = '3.2';
425our $MODEL; 428our $MODEL;
426 429
427our $AUTOLOAD; 430our $AUTOLOAD;
428our @ISA; 431our @ISA;
429 432
… …
437 [EV:: => AnyEvent::Impl::EV::], 440 [EV:: => AnyEvent::Impl::EV::],
438 [Event:: => AnyEvent::Impl::Event::], 441 [Event:: => AnyEvent::Impl::Event::],
439 [Glib:: => AnyEvent::Impl::Glib::], 442 [Glib:: => AnyEvent::Impl::Glib::],
440 [Tk:: => AnyEvent::Impl::Tk::], 443 [Tk:: => AnyEvent::Impl::Tk::],
441 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 444 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
442 [Event::Lib:: => AnyEvent::Impl::EventLib::],
443); 445);
446my @models_detect = (
447 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
448 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
449);
444 450
445our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY); 451our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY);
446 452
447sub detect() { 453sub detect() {
448 unless ($MODEL) { 454 unless ($MODEL) {
449 no strict 'refs'; 455 no strict 'refs';
450 456
451 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 457 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
452 my $model = "AnyEvent::Impl::$1"; 458 my $model = "AnyEvent::Impl::$1";
453 if (eval "require $model") { 459 if (eval "require $model") {
454 $MODEL = $model; 460 $MODEL = $model;
455 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1; 461 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1;
462 } else {
463 warn "AnyEvent: unable to load model '$model' (from \$PERL_ANYEVENT_MODEL):\n$@" if $verbose;
456 } 464 }
457 } 465 }
458 466
459 # check for already loaded models 467 # check for already loaded models
460 unless ($MODEL) { 468 unless ($MODEL) {
461 for (@REGISTRY, @models) { 469 for (@REGISTRY, @models, @models_detect) {
462 my ($package, $model) = @$_; 470 my ($package, $model) = @$_;
463 if (${"$package\::VERSION"} > 0) { 471 if (${"$package\::VERSION"} > 0) {
464 if (eval "require $model") { 472 if (eval "require $model") {
465 $MODEL = $model; 473 $MODEL = $model;
466 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 474 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1;
… …
653 661
654=over 4 662=over 4
655 663
656=item C<PERL_ANYEVENT_VERBOSE> 664=item C<PERL_ANYEVENT_VERBOSE>
657 665
666By default, AnyEvent will be completely silent except in fatal
667conditions. You can set this environment variable to make AnyEvent more
668talkative.
669
670When set to C<1> or higher, causes AnyEvent to warn about unexpected
671conditions, such as not being able to load the event model specified by
672C<PERL_ANYEVENT_MODEL>.
673
658When set to C<2> or higher, cause AnyEvent to report to STDERR which event 674When set to C<2> or higher, cause AnyEvent to report to STDERR which event
659model it chooses. 675model it chooses.
660 676
661=item C<PERL_ANYEVENT_MODEL> 677=item C<PERL_ANYEVENT_MODEL>
662 678
… …
858 874
859=head1 SEE ALSO 875=head1 SEE ALSO
860 876
861Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 877Event 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>, 878L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
863L<Event::Lib>. 879L<Event::Lib>, L<Qt>.
864 880
865Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 881Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
866L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 882L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
867L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>. 883L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
884L<AnyEvent::Impl::Qt>.
868 885
869Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 886Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
870 887
871=head1 AUTHOR 888=head1 AUTHOR
872 889

Diff Legend

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