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.53 by root, Sat Apr 19 04:58:14 2008 UTC vs.
Revision 1.57 by root, Thu Apr 24 03:19:28 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 - 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
… …
353 354
354The known classes so far are: 355The known classes so far are:
355 356
356 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 357 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
357 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. 358 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
358 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 359 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
359 AnyEvent::Impl::Event based on Event, also second best choice :) 360 AnyEvent::Impl::Event based on Event, second best choice.
360 AnyEvent::Impl::Glib based on Glib, third-best choice. 361 AnyEvent::Impl::Glib based on Glib, third-best choice.
361 AnyEvent::Impl::Tk based on Tk, very bad choice. 362 AnyEvent::Impl::Tk based on Tk, very bad choice.
362 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. 363 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
364 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
365 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
363 366
364=item AnyEvent::detect 367=item AnyEvent::detect
365 368
366Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 369Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
367if necessary. You should only call this function right before you would 370if necessary. You should only call this function right before you would
… …
418no warnings; 421no warnings;
419use strict; 422use strict;
420 423
421use Carp; 424use Carp;
422 425
423our $VERSION = '3.11'; 426our $VERSION = '3.12';
424our $MODEL; 427our $MODEL;
425 428
426our $AUTOLOAD; 429our $AUTOLOAD;
427our @ISA; 430our @ISA;
428 431
… …
437 [Event:: => AnyEvent::Impl::Event::], 440 [Event:: => AnyEvent::Impl::Event::],
438 [Glib:: => AnyEvent::Impl::Glib::], 441 [Glib:: => AnyEvent::Impl::Glib::],
439 [Tk:: => AnyEvent::Impl::Tk::], 442 [Tk:: => AnyEvent::Impl::Tk::],
440 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 443 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
441); 444);
445my @models_detect = (
446 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
447 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
448);
442 449
443our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY); 450our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY);
444 451
445sub detect() { 452sub detect() {
446 unless ($MODEL) { 453 unless ($MODEL) {
447 no strict 'refs'; 454 no strict 'refs';
448 455
456 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
457 my $model = "AnyEvent::Impl::$1";
458 if (eval "require $model") {
459 $MODEL = $model;
460 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1;
461 }
462 }
463
449 # check for already loaded models 464 # check for already loaded models
465 unless ($MODEL) {
450 for (@REGISTRY, @models) { 466 for (@REGISTRY, @models, @models_detect) {
451 my ($package, $model) = @$_; 467 my ($package, $model) = @$_;
452 if (${"$package\::VERSION"} > 0) { 468 if (${"$package\::VERSION"} > 0) {
453 if (eval "require $model") { 469 if (eval "require $model") {
454 $MODEL = $model; 470 $MODEL = $model;
455 warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1; 471 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1;
456 last; 472 last;
473 }
457 } 474 }
458 } 475 }
459 }
460 476
461 unless ($MODEL) { 477 unless ($MODEL) {
462 # try to load a model 478 # try to load a model
463 479
464 for (@REGISTRY, @models) { 480 for (@REGISTRY, @models) {
465 my ($package, $model) = @$_; 481 my ($package, $model) = @$_;
466 if (eval "require $package" 482 if (eval "require $package"
467 and ${"$package\::VERSION"} > 0 483 and ${"$package\::VERSION"} > 0
468 and eval "require $model") { 484 and eval "require $model") {
469 $MODEL = $model; 485 $MODEL = $model;
470 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1; 486 warn "AnyEvent: autoprobed model '$model', using it.\n" if $verbose > 1;
471 last; 487 last;
488 }
472 } 489 }
490
491 $MODEL
492 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event) or Glib.";
473 } 493 }
474
475 $MODEL
476 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event), Glib or Tk.";
477 } 494 }
478 495
479 unshift @ISA, $MODEL; 496 unshift @ISA, $MODEL;
480 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 497 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
481 } 498 }
… …
637 654
638=head1 ENVIRONMENT VARIABLES 655=head1 ENVIRONMENT VARIABLES
639 656
640The following environment variables are used by this module: 657The following environment variables are used by this module:
641 658
642C<PERL_ANYEVENT_VERBOSE> when set to C<2> or higher, cause AnyEvent to 659=over 4
643report to STDERR which event model it chooses. 660
661=item C<PERL_ANYEVENT_VERBOSE>
662
663When set to C<2> or higher, cause AnyEvent to report to STDERR which event
664model it chooses.
665
666=item C<PERL_ANYEVENT_MODEL>
667
668This can be used to specify the event model to be used by AnyEvent, before
669autodetection and -probing kicks in. It must be a string consisting
670entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
671and the resulting module name is loaded and if the load was successful,
672used as event model. If it fails to load AnyEvent will proceed with
673autodetection and -probing.
674
675This functionality might change in future versions.
676
677For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
678could start your program like this:
679
680 PERL_ANYEVENT_MODEL=Perl perl ...
681
682=back
644 683
645=head1 EXAMPLE PROGRAM 684=head1 EXAMPLE PROGRAM
646 685
647The following program uses an IO watcher to read data from STDIN, a timer 686The following program uses an IO watcher to read data from STDIN, a timer
648to display a message once per second, and a condition variable to quit the 687to display a message once per second, and a condition variable to quit the
… …
796 $quit->broadcast; 835 $quit->broadcast;
797 }); 836 });
798 837
799 $quit->wait; 838 $quit->wait;
800 839
840=head1 FORK
841
842Most event libraries are not fork-safe. The ones who are usually are
843because they are so inefficient. Only L<EV> is fully fork-aware.
844
845If 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.
847
848=head1 SECURITY CONSIDERATIONS
849
850AnyEvent can be forced to load any event model via
851$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to
852execute arbitrary code or directly gain access, it can easily be used to
853make the program hang or malfunction in subtle ways, as AnyEvent watchers
854will not be active when the program uses a different event model than
855specified in the variable.
856
857You can make AnyEvent completely ignore this variable by deleting it
858before the first watcher gets created, e.g. with a C<BEGIN> block:
859
860 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
861
862 use AnyEvent;
863
801=head1 SEE ALSO 864=head1 SEE ALSO
802 865
803Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 866Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
804L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>. 867L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
868L<Event::Lib>, L<Qt>.
805 869
806Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 870Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
807L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, 871L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
808L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>. 872L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
873L<AnyEvent::Impl::Qt>.
809 874
810Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 875Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
811 876
812=head1 877=head1 AUTHOR
878
879 Marc Lehmann <schmorp@schmorp.de>
880 http://home.schmorp.de/
813 881
814=cut 882=cut
815 883
8161 8841
817 885

Diff Legend

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