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.108 by root, Sat May 10 00:22:02 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::detect
555
556If there are any code references in this array (you can C<push> to it
557before or after loading AnyEvent), then they will called directly after
558the event loop has been chosen.
559
560You should check C<$AnyEvent::MODEL> before adding to this array, though:
561if it contains a true value then the event loop has already been detected,
562and the array will be ignored.
563
552=back 564=back
553 565
554=head1 WHAT TO DO IN A MODULE 566=head1 WHAT TO DO IN A MODULE
555 567
556As a module author, you should C<use AnyEvent> and call AnyEvent methods 568As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
644 656
645High level API for event-based execution flow control. 657High level API for event-based execution flow control.
646 658
647=item L<Coro> 659=item L<Coro>
648 660
649Has special support for AnyEvent. 661Has special support for AnyEvent via L<Coro::AnyEvent>.
650 662
651=item L<IO::Lambda> 663=item L<IO::Lambda>
652 664
653The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 665The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
654 666
… …
671no warnings; 683no warnings;
672use strict; 684use strict;
673 685
674use Carp; 686use Carp;
675 687
676our $VERSION = '3.3'; 688our $VERSION = '3.4';
677our $MODEL; 689our $MODEL;
678 690
679our $AUTOLOAD; 691our $AUTOLOAD;
680our @ISA; 692our @ISA;
681 693
682our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 694our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
683 695
684our @REGISTRY; 696our @REGISTRY;
685 697
686my @models = ( 698my @models = (
687 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
688 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
689 [EV:: => AnyEvent::Impl::EV::], 699 [EV:: => AnyEvent::Impl::EV::],
690 [Event:: => AnyEvent::Impl::Event::], 700 [Event:: => AnyEvent::Impl::Event::],
691 [Tk:: => AnyEvent::Impl::Tk::], 701 [Tk:: => AnyEvent::Impl::Tk::],
692 [Wx:: => AnyEvent::Impl::POE::], 702 [Wx:: => AnyEvent::Impl::POE::],
693 [Prima:: => AnyEvent::Impl::POE::], 703 [Prima:: => AnyEvent::Impl::POE::],
… …
699 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 709 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
700); 710);
701 711
702our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 712our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
703 713
714our @detect;
715
704sub detect() { 716sub detect() {
705 unless ($MODEL) { 717 unless ($MODEL) {
706 no strict 'refs'; 718 no strict 'refs';
707 719
708 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 720 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
… …
741 last; 753 last;
742 } 754 }
743 } 755 }
744 756
745 $MODEL 757 $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."; 758 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.";
747 } 759 }
748 } 760 }
749 761
750 unshift @ISA, $MODEL; 762 unshift @ISA, $MODEL;
751 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 763 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
764
765 (shift @detect)->() while @detect;
752 } 766 }
753 767
754 $MODEL 768 $MODEL
755} 769}
756 770
… …
1397probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1411probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1398 1412
1399 1413
1400=head1 SEE ALSO 1414=head1 SEE ALSO
1401 1415
1402Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1416Event 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>. 1417L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1405 1418
1406Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1419Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1407L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1420L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1408L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1421L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1409L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. 1422L<AnyEvent::Impl::POE>.
1423
1424Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1410 1425
1411Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1426Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
1412 1427
1413 1428
1414=head1 AUTHOR 1429=head1 AUTHOR

Diff Legend

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