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.107 by root, Tue May 6 12:15:50 2008 UTC vs.
Revision 1.110 by root, Sat May 10 00:57:31 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, POE - various supported event loops 5EV, 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
… …
78The interface itself is vaguely similar, but not identical to the L<Event> 78The interface itself is vaguely similar, but not identical to the L<Event>
79module. 79module.
80 80
81During the first call of any watcher-creation method, the module tries 81During the first call of any watcher-creation method, the module tries
82to detect the currently loaded event loop by probing whether one of the 82to detect the currently loaded event loop by probing whether one of the
83following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>, 83following modules is already loaded: L<EV>,
84L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>, 84L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>,
85L<POE>. The first one found is used. If none are found, the module tries 85L<POE>. The first one found is used. If none are found, the module tries
86to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl 86to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl
87adaptor should always succeed) in the order given. The first one that can 87adaptor should always succeed) in the order given. The first one that can
88be successfully loaded will be used. If, after this, still none could be 88be successfully loaded will be used. If, after this, still none could be
… …
480while still suppporting blocking waits if the caller so desires). 480while still suppporting blocking waits if the caller so desires).
481 481
482Another reason I<never> to C<< ->wait >> in a module is that you cannot 482Another reason I<never> to C<< ->wait >> in a module is that you cannot
483sensibly have two C<< ->wait >>'s in parallel, as that would require 483sensibly have two C<< ->wait >>'s in parallel, as that would require
484multiple interpreters or coroutines/threads, none of which C<AnyEvent> 484multiple interpreters or coroutines/threads, none of which C<AnyEvent>
485can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and 485can supply.
486L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s 486
487from different coroutines, however). 487The L<Coro> module, however, I<can> and I<does> supply coroutines and, in
488fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe
489versions and also integrates coroutines into AnyEvent, making blocking
490C<< ->wait >> calls perfectly safe as long as they are done from another
491coroutine (one that doesn't run the event loop).
488 492
489You can ensure that C<< -wait >> never blocks by setting a callback and 493You can ensure that C<< -wait >> never blocks by setting a callback and
490only calling C<< ->wait >> from within that callback (or at a later 494only calling C<< ->wait >> from within that callback (or at a later
491time). This will work even when the event loop does not support blocking 495time). This will work even when the event loop does not support blocking
492waits otherwise. 496waits otherwise.
… …
519C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 523C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
520AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 524AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
521 525
522The known classes so far are: 526The known classes so far are:
523 527
524 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
525 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
526 AnyEvent::Impl::EV based on EV (an interface to libev, best choice). 528 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
527 AnyEvent::Impl::Event based on Event, second best choice. 529 AnyEvent::Impl::Event based on Event, second best choice.
528 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 530 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
529 AnyEvent::Impl::Glib based on Glib, third-best choice. 531 AnyEvent::Impl::Glib based on Glib, third-best choice.
530 AnyEvent::Impl::Tk based on Tk, very bad choice. 532 AnyEvent::Impl::Tk based on Tk, very bad choice.
… …
547Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 549Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
548if necessary. You should only call this function right before you would 550if necessary. You should only call this function right before you would
549have created an AnyEvent watcher anyway, that is, as late as possible at 551have created an AnyEvent watcher anyway, that is, as late as possible at
550runtime. 552runtime.
551 553
554=item $guard = AnyEvent::on_detect { BLOCK }
555
556Arranges for the code block to be executed as soon as the event model is
557autodetected (or immediately if this has already happened).
558
559If called in scalar or list context, then it creates and returns an object
560that automatically removes the callback again when it is destroyed.
561
562=item @AnyEvent::on_detect
563
564If there are any code references in this array (you can C<push> to it
565before or after loading AnyEvent), then they will called directly after
566the event loop has been chosen.
567
568You should check C<$AnyEvent::MODEL> before adding to this array, though:
569if it contains a true value then the event loop has already been detected,
570and the array will be ignored.
571
572Best use C<AnyEvent::on_detect { BLOCK }> instead.
573
552=back 574=back
553 575
554=head1 WHAT TO DO IN A MODULE 576=head1 WHAT TO DO IN A MODULE
555 577
556As a module author, you should C<use AnyEvent> and call AnyEvent methods 578As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
644 666
645High level API for event-based execution flow control. 667High level API for event-based execution flow control.
646 668
647=item L<Coro> 669=item L<Coro>
648 670
649Has special support for AnyEvent. 671Has special support for AnyEvent via L<Coro::AnyEvent>.
650 672
651=item L<IO::Lambda> 673=item L<IO::Lambda>
652 674
653The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 675The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
654 676
… …
671no warnings; 693no warnings;
672use strict; 694use strict;
673 695
674use Carp; 696use Carp;
675 697
676our $VERSION = '3.3'; 698our $VERSION = '3.4';
677our $MODEL; 699our $MODEL;
678 700
679our $AUTOLOAD; 701our $AUTOLOAD;
680our @ISA; 702our @ISA;
681 703
682our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 704our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
683 705
684our @REGISTRY; 706our @REGISTRY;
685 707
686my @models = ( 708my @models = (
687 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
688 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
689 [EV:: => AnyEvent::Impl::EV::], 709 [EV:: => AnyEvent::Impl::EV::],
690 [Event:: => AnyEvent::Impl::Event::], 710 [Event:: => AnyEvent::Impl::Event::],
691 [Tk:: => AnyEvent::Impl::Tk::], 711 [Tk:: => AnyEvent::Impl::Tk::],
692 [Wx:: => AnyEvent::Impl::POE::], 712 [Wx:: => AnyEvent::Impl::POE::],
693 [Prima:: => AnyEvent::Impl::POE::], 713 [Prima:: => AnyEvent::Impl::POE::],
… …
699 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 719 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
700); 720);
701 721
702our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 722our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
703 723
724our @on_detect;
725
726sub on_detect(&) {
727 my ($cb) = @_;
728
729 if ($MODEL) {
730 $cb->();
731
732 1
733 } else {
734 push @on_detect, $cb;
735
736 defined wantarray
737 ? bless \$cb, "AnyEvent::Util::Guard"
738 : ()
739 }
740}
741
742sub AnyEvent::Util::Guard::DESTROY {
743 @on_detect = grep $_ != ${$_[0]}, @on_detect;
744}
745
704sub detect() { 746sub detect() {
705 unless ($MODEL) { 747 unless ($MODEL) {
706 no strict 'refs'; 748 no strict 'refs';
707 749
708 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 750 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
… …
741 last; 783 last;
742 } 784 }
743 } 785 }
744 786
745 $MODEL 787 $MODEL
746 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."; 788 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.";
747 } 789 }
748 } 790 }
749 791
750 unshift @ISA, $MODEL; 792 unshift @ISA, $MODEL;
751 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 793 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
794
795 (shift @on_detect)->() while @on_detect;
752 } 796 }
753 797
754 $MODEL 798 $MODEL
755} 799}
756 800
… …
1397probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1441probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1398 1442
1399 1443
1400=head1 SEE ALSO 1444=head1 SEE ALSO
1401 1445
1402Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1446Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
1403L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
1404L<Event::Lib>, L<Qt>, L<POE>. 1447L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1405 1448
1406Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1449Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1407L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1450L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1408L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1451L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1409L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. 1452L<AnyEvent::Impl::POE>.
1453
1454Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1410 1455
1411Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1456Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
1412 1457
1413 1458
1414=head1 AUTHOR 1459=head1 AUTHOR

Diff Legend

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