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.54 by root, Tue Apr 22 05:12:19 2008 UTC vs.
Revision 1.56 by root, Thu Apr 24 03:10:03 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
… …
145events. C<poll> must be a string that is either C<r> or C<w>, which 145events. 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, 146creates a watcher waiting for "r"eadable or "w"ritable events,
147respectively. C<cb> is the callback to invoke each time the file handle 147respectively. C<cb> is the callback to invoke each time the file handle
148becomes ready. 148becomes ready.
149 149
150File handles will be kept alive, so as long as the watcher exists, the 150As long as the I/O watcher exists it will keep the file descriptor or a
151file handle exists, too. 151copy of it alive/open.
152 152
153It is not allowed to close a file handle as long as any watcher is active 153It is not allowed to close a file handle as long as any watcher is active
154on the underlying file descriptor. 154on the underlying file descriptor.
155 155
156Some event loops issue spurious readyness notifications, so you should 156Some event loops issue spurious readyness notifications, so you should
… …
353 353
354The known classes so far are: 354The known classes so far are:
355 355
356 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 356 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
357 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. 357 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
358 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 358 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
359 AnyEvent::Impl::Event based on Event, also second best choice :) 359 AnyEvent::Impl::Event based on Event, second best choice.
360 AnyEvent::Impl::Glib based on Glib, third-best choice. 360 AnyEvent::Impl::Glib based on Glib, third-best choice.
361 AnyEvent::Impl::Tk based on Tk, very bad choice. 361 AnyEvent::Impl::Tk based on Tk, very bad choice.
362 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. 362 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
363 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
364 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
363 365
364=item AnyEvent::detect 366=item AnyEvent::detect
365 367
366Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 368Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
367if necessary. You should only call this function right before you would 369if necessary. You should only call this function right before you would
… …
437 [Event:: => AnyEvent::Impl::Event::], 439 [Event:: => AnyEvent::Impl::Event::],
438 [Glib:: => AnyEvent::Impl::Glib::], 440 [Glib:: => AnyEvent::Impl::Glib::],
439 [Tk:: => AnyEvent::Impl::Tk::], 441 [Tk:: => AnyEvent::Impl::Tk::],
440 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 442 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
441); 443);
444my @models_detect = (
445 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
446 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
447);
442 448
443our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY); 449our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY);
444 450
445sub detect() { 451sub detect() {
446 unless ($MODEL) { 452 unless ($MODEL) {
447 no strict 'refs'; 453 no strict 'refs';
448 454
455 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
456 my $model = "AnyEvent::Impl::$1";
457 if (eval "require $model") {
458 $MODEL = $model;
459 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1;
460 }
461 }
462
449 # check for already loaded models 463 # check for already loaded models
464 unless ($MODEL) {
450 for (@REGISTRY, @models) { 465 for (@REGISTRY, @models, @models_detect) {
451 my ($package, $model) = @$_; 466 my ($package, $model) = @$_;
452 if (${"$package\::VERSION"} > 0) { 467 if (${"$package\::VERSION"} > 0) {
453 if (eval "require $model") { 468 if (eval "require $model") {
454 $MODEL = $model; 469 $MODEL = $model;
455 warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1; 470 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1;
456 last; 471 last;
472 }
457 } 473 }
458 } 474 }
459 }
460 475
461 unless ($MODEL) { 476 unless ($MODEL) {
462 # try to load a model 477 # try to load a model
463 478
464 for (@REGISTRY, @models) { 479 for (@REGISTRY, @models) {
465 my ($package, $model) = @$_; 480 my ($package, $model) = @$_;
466 if (eval "require $package" 481 if (eval "require $package"
467 and ${"$package\::VERSION"} > 0 482 and ${"$package\::VERSION"} > 0
468 and eval "require $model") { 483 and eval "require $model") {
469 $MODEL = $model; 484 $MODEL = $model;
470 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1; 485 warn "AnyEvent: autoprobed model '$model', using it.\n" if $verbose > 1;
471 last; 486 last;
487 }
472 } 488 }
489
490 $MODEL
491 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 } 492 }
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 } 493 }
478 494
479 unshift @ISA, $MODEL; 495 unshift @ISA, $MODEL;
480 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 496 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
481 } 497 }
… …
637 653
638=head1 ENVIRONMENT VARIABLES 654=head1 ENVIRONMENT VARIABLES
639 655
640The following environment variables are used by this module: 656The following environment variables are used by this module:
641 657
642C<PERL_ANYEVENT_VERBOSE> when set to C<2> or higher, cause AnyEvent to 658=over 4
643report to STDERR which event model it chooses. 659
660=item C<PERL_ANYEVENT_VERBOSE>
661
662When set to C<2> or higher, cause AnyEvent to report to STDERR which event
663model it chooses.
664
665=item C<PERL_ANYEVENT_MODEL>
666
667This can be used to specify the event model to be used by AnyEvent, before
668autodetection and -probing kicks in. It must be a string consisting
669entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
670and the resulting module name is loaded and if the load was successful,
671used as event model. If it fails to load AnyEvent will proceed with
672autodetection and -probing.
673
674This functionality might change in future versions.
675
676For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
677could start your program like this:
678
679 PERL_ANYEVENT_MODEL=Perl perl ...
680
681=back
644 682
645=head1 EXAMPLE PROGRAM 683=head1 EXAMPLE PROGRAM
646 684
647The following program uses an IO watcher to read data from STDIN, a timer 685The 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 686to display a message once per second, and a condition variable to quit the
… …
796 $quit->broadcast; 834 $quit->broadcast;
797 }); 835 });
798 836
799 $quit->wait; 837 $quit->wait;
800 838
839=head1 FORK
840
841Most event libraries are not fork-safe. The ones who are usually are
842because they are so inefficient. Only L<EV> is fully fork-aware.
843
844If you have to fork, you must either do so I<before> creating your first
845watcher OR you must not use AnyEvent at all in the child.
846
847=head1 SECURITY CONSIDERATIONS
848
849AnyEvent can be forced to load any event model via
850$ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used to
851execute arbitrary code or directly gain access, it can easily be used to
852make the program hang or malfunction in subtle ways, as AnyEvent watchers
853will not be active when the program uses a different event model than
854specified in the variable.
855
856You can make AnyEvent completely ignore this variable by deleting it
857before the first watcher gets created, e.g. with a C<BEGIN> block:
858
859 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
860
861 use AnyEvent;
862
801=head1 SEE ALSO 863=head1 SEE ALSO
802 864
803Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 865Event 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>. 866L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
867L<Event::Lib>, L<Qt>.
805 868
806Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 869Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
807L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, 870L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>,
808L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>. 871L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>,
872L<AnyEvent::Impl::Qt>.
809 873
810Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 874Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
811 875
812=head1 AUTHOR 876=head1 AUTHOR
813 877

Diff Legend

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