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.112 by root, Sat May 10 01:04:42 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::post_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. See
561L<Coro::BDB> for a case where this is useful.
562
563=item @AnyEvent::post_detect
564
565If there are any code references in this array (you can C<push> to it
566before or after loading AnyEvent), then they will called directly after
567the event loop has been chosen.
568
569You should check C<$AnyEvent::MODEL> before adding to this array, though:
570if it contains a true value then the event loop has already been detected,
571and the array will be ignored.
572
573Best use C<AnyEvent::post_detect { BLOCK }> instead.
574
552=back 575=back
553 576
554=head1 WHAT TO DO IN A MODULE 577=head1 WHAT TO DO IN A MODULE
555 578
556As a module author, you should C<use AnyEvent> and call AnyEvent methods 579As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
644 667
645High level API for event-based execution flow control. 668High level API for event-based execution flow control.
646 669
647=item L<Coro> 670=item L<Coro>
648 671
649Has special support for AnyEvent. 672Has special support for AnyEvent via L<Coro::AnyEvent>.
650 673
651=item L<IO::Lambda> 674=item L<IO::Lambda>
652 675
653The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 676The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
654 677
… …
671no warnings; 694no warnings;
672use strict; 695use strict;
673 696
674use Carp; 697use Carp;
675 698
676our $VERSION = '3.3'; 699our $VERSION = '3.4';
677our $MODEL; 700our $MODEL;
678 701
679our $AUTOLOAD; 702our $AUTOLOAD;
680our @ISA; 703our @ISA;
681 704
682our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 705our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
683 706
684our @REGISTRY; 707our @REGISTRY;
685 708
686my @models = ( 709my @models = (
687 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
688 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
689 [EV:: => AnyEvent::Impl::EV::], 710 [EV:: => AnyEvent::Impl::EV::],
690 [Event:: => AnyEvent::Impl::Event::], 711 [Event:: => AnyEvent::Impl::Event::],
691 [Tk:: => AnyEvent::Impl::Tk::], 712 [Tk:: => AnyEvent::Impl::Tk::],
692 [Wx:: => AnyEvent::Impl::POE::], 713 [Wx:: => AnyEvent::Impl::POE::],
693 [Prima:: => AnyEvent::Impl::POE::], 714 [Prima:: => AnyEvent::Impl::POE::],
… …
699 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 720 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
700); 721);
701 722
702our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 723our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
703 724
725our @post_detect;
726
727sub post_detect(&) {
728 my ($cb) = @_;
729
730 if ($MODEL) {
731 $cb->();
732
733 1
734 } else {
735 push @post_detect, $cb;
736
737 defined wantarray
738 ? bless \$cb, "AnyEvent::Util::Guard"
739 : ()
740 }
741}
742
743sub AnyEvent::Util::Guard::DESTROY {
744 @post_detect = grep $_ != ${$_[0]}, @post_detect;
745}
746
704sub detect() { 747sub detect() {
705 unless ($MODEL) { 748 unless ($MODEL) {
706 no strict 'refs'; 749 no strict 'refs';
707 750
708 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 751 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
… …
741 last; 784 last;
742 } 785 }
743 } 786 }
744 787
745 $MODEL 788 $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."; 789 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.";
747 } 790 }
748 } 791 }
749 792
750 unshift @ISA, $MODEL; 793 unshift @ISA, $MODEL;
751 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 794 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
795
796 (shift @post_detect)->() while @post_detect;
752 } 797 }
753 798
754 $MODEL 799 $MODEL
755} 800}
756 801
… …
1397probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1442probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1398 1443
1399 1444
1400=head1 SEE ALSO 1445=head1 SEE ALSO
1401 1446
1402Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1447Event 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>. 1448L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1405 1449
1406Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1450Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1407L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1451L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1408L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1452L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1409L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. 1453L<AnyEvent::Impl::POE>.
1454
1455Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1410 1456
1411Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1457Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
1412 1458
1413 1459
1414=head1 AUTHOR 1460=head1 AUTHOR

Diff Legend

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