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.113 by root, Sat May 10 20:30:35 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
… …
608 631
609=item L<AnyEvent::Handle> 632=item L<AnyEvent::Handle>
610 633
611Provide read and write buffers and manages watchers for reads and writes. 634Provide read and write buffers and manages watchers for reads and writes.
612 635
613=item L<AnyEvent::Socket>
614
615Provides a means to do non-blocking connects, accepts etc.
616
617=item L<AnyEvent::HTTPD> 636=item L<AnyEvent::HTTPD>
618 637
619Provides a simple web application server framework. 638Provides a simple web application server framework.
620 639
621=item L<AnyEvent::DNS> 640=item L<AnyEvent::DNS>
… …
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>.
669
670=item L<AnyEvent::AIO>, L<IO::AIO>
671
672Truly asynchronous I/O, should be in the toolbox of every event
673programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
674together.
675
676=item L<AnyEvent::BDB>, L<BDB>
677
678Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
679IO::AIO and AnyEvent together.
650 680
651=item L<IO::Lambda> 681=item L<IO::Lambda>
652 682
653The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 683The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
654
655=item L<IO::AIO>
656
657Truly asynchronous I/O, should be in the toolbox of every event
658programmer. Can be trivially made to use AnyEvent.
659
660=item L<BDB>
661
662Truly asynchronous Berkeley DB access. Can be trivially made to use
663AnyEvent.
664 684
665=back 685=back
666 686
667=cut 687=cut
668 688
… …
671no warnings; 691no warnings;
672use strict; 692use strict;
673 693
674use Carp; 694use Carp;
675 695
676our $VERSION = '3.3'; 696our $VERSION = '3.4';
677our $MODEL; 697our $MODEL;
678 698
679our $AUTOLOAD; 699our $AUTOLOAD;
680our @ISA; 700our @ISA;
681 701
682our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 702our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
683 703
684our @REGISTRY; 704our @REGISTRY;
685 705
686my @models = ( 706my @models = (
687 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
688 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
689 [EV:: => AnyEvent::Impl::EV::], 707 [EV:: => AnyEvent::Impl::EV::],
690 [Event:: => AnyEvent::Impl::Event::], 708 [Event:: => AnyEvent::Impl::Event::],
691 [Tk:: => AnyEvent::Impl::Tk::], 709 [Tk:: => AnyEvent::Impl::Tk::],
692 [Wx:: => AnyEvent::Impl::POE::], 710 [Wx:: => AnyEvent::Impl::POE::],
693 [Prima:: => AnyEvent::Impl::POE::], 711 [Prima:: => AnyEvent::Impl::POE::],
… …
699 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 717 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
700); 718);
701 719
702our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 720our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
703 721
722our @post_detect;
723
724sub post_detect(&) {
725 my ($cb) = @_;
726
727 if ($MODEL) {
728 $cb->();
729
730 1
731 } else {
732 push @post_detect, $cb;
733
734 defined wantarray
735 ? bless \$cb, "AnyEvent::Util::Guard"
736 : ()
737 }
738}
739
740sub AnyEvent::Util::Guard::DESTROY {
741 @post_detect = grep $_ != ${$_[0]}, @post_detect;
742}
743
704sub detect() { 744sub detect() {
705 unless ($MODEL) { 745 unless ($MODEL) {
706 no strict 'refs'; 746 no strict 'refs';
707 747
708 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 748 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
… …
741 last; 781 last;
742 } 782 }
743 } 783 }
744 784
745 $MODEL 785 $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."; 786 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.";
747 } 787 }
748 } 788 }
749 789
750 unshift @ISA, $MODEL; 790 unshift @ISA, $MODEL;
751 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 791 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
792
793 (shift @post_detect)->() while @post_detect;
752 } 794 }
753 795
754 $MODEL 796 $MODEL
755} 797}
756 798
… …
1397probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1439probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1398 1440
1399 1441
1400=head1 SEE ALSO 1442=head1 SEE ALSO
1401 1443
1402Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1444Event 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>. 1445L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1405 1446
1406Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1447Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1407L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1448L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1408L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1449L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1409L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. 1450L<AnyEvent::Impl::POE>.
1451
1452Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1410 1453
1411Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1454Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
1412 1455
1413 1456
1414=head1 AUTHOR 1457=head1 AUTHOR

Diff Legend

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