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.109 by root, Sat May 10 00:45:18 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 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
559=item @AnyEvent::on_detect
560
561If there are any code references in this array (you can C<push> to it
562before or after loading AnyEvent), then they will called directly after
563the event loop has been chosen.
564
565You should check C<$AnyEvent::MODEL> before adding to this array, though:
566if it contains a true value then the event loop has already been detected,
567and the array will be ignored.
568
569Best use C<AnyEvent::on_detect { BLOCK }> instead.
570
552=back 571=back
553 572
554=head1 WHAT TO DO IN A MODULE 573=head1 WHAT TO DO IN A MODULE
555 574
556As a module author, you should C<use AnyEvent> and call AnyEvent methods 575As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
644 663
645High level API for event-based execution flow control. 664High level API for event-based execution flow control.
646 665
647=item L<Coro> 666=item L<Coro>
648 667
649Has special support for AnyEvent. 668Has special support for AnyEvent via L<Coro::AnyEvent>.
650 669
651=item L<IO::Lambda> 670=item L<IO::Lambda>
652 671
653The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 672The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
654 673
… …
671no warnings; 690no warnings;
672use strict; 691use strict;
673 692
674use Carp; 693use Carp;
675 694
676our $VERSION = '3.3'; 695our $VERSION = '3.4';
677our $MODEL; 696our $MODEL;
678 697
679our $AUTOLOAD; 698our $AUTOLOAD;
680our @ISA; 699our @ISA;
681 700
682our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 701our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
683 702
684our @REGISTRY; 703our @REGISTRY;
685 704
686my @models = ( 705my @models = (
687 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
688 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
689 [EV:: => AnyEvent::Impl::EV::], 706 [EV:: => AnyEvent::Impl::EV::],
690 [Event:: => AnyEvent::Impl::Event::], 707 [Event:: => AnyEvent::Impl::Event::],
691 [Tk:: => AnyEvent::Impl::Tk::], 708 [Tk:: => AnyEvent::Impl::Tk::],
692 [Wx:: => AnyEvent::Impl::POE::], 709 [Wx:: => AnyEvent::Impl::POE::],
693 [Prima:: => AnyEvent::Impl::POE::], 710 [Prima:: => AnyEvent::Impl::POE::],
… …
699 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 716 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
700); 717);
701 718
702our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 719our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
703 720
721our @on_detect;
722
723sub on_detect(&) {
724 if ($MODEL) {
725 $_[0]->();
726 } else {
727 push @on_detect, $_[0];
728 }
729}
730
704sub detect() { 731sub detect() {
705 unless ($MODEL) { 732 unless ($MODEL) {
706 no strict 'refs'; 733 no strict 'refs';
707 734
708 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 735 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
… …
741 last; 768 last;
742 } 769 }
743 } 770 }
744 771
745 $MODEL 772 $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."; 773 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.";
747 } 774 }
748 } 775 }
749 776
750 unshift @ISA, $MODEL; 777 unshift @ISA, $MODEL;
751 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 778 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
779
780 (shift @on_detect)->() while @on_detect;
752 } 781 }
753 782
754 $MODEL 783 $MODEL
755} 784}
756 785
… …
1397probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1426probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1398 1427
1399 1428
1400=head1 SEE ALSO 1429=head1 SEE ALSO
1401 1430
1402Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1431Event 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>. 1432L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1405 1433
1406Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1434Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1407L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1435L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1408L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1436L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1409L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. 1437L<AnyEvent::Impl::POE>.
1438
1439Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1410 1440
1411Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1441Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
1412 1442
1413 1443
1414=head1 AUTHOR 1444=head1 AUTHOR

Diff Legend

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