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.129 by elmex, Sat May 24 15:19:30 2008 UTC vs.
Revision 1.142 by root, Tue May 27 02:34:30 2008 UTC

… …
48isn't itself. What's worse, all the potential users of your module are 48isn't itself. What's worse, all the potential users of your module are
49I<also> forced to use the same event loop you use. 49I<also> forced to use the same event loop you use.
50 50
51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
52fine. AnyEvent + Tk works fine etc. etc. but none of these work together 52fine. AnyEvent + Tk works fine etc. etc. but none of these work together
53with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if 53with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if
54your module uses one of those, every user of your module has to use it, 54your module uses one of those, every user of your module has to use it,
55too. But if your module uses AnyEvent, it works transparently with all 55too. But if your module uses AnyEvent, it works transparently with all
56event models it supports (including stuff like POE and IO::Async, as long 56event models it supports (including stuff like POE and IO::Async, as long
57as those use one of the supported event loops. It is trivial to add new 57as those use one of the supported event loops. It is trivial to add new
58event loops to AnyEvent, too, so it is future-proof). 58event loops to AnyEvent, too, so it is future-proof).
… …
62modules, you get an enormous amount of code and strict rules you have to 62modules, you get an enormous amount of code and strict rules you have to
63follow. AnyEvent, on the other hand, is lean and up to the point, by only 63follow. AnyEvent, on the other hand, is lean and up to the point, by only
64offering the functionality that is necessary, in as thin as a wrapper as 64offering the functionality that is necessary, in as thin as a wrapper as
65technically possible. 65technically possible.
66 66
67Of course, AnyEvent comes with a big (and fully optional!) toolbox
68of useful functionality, such as an asynchronous DNS resolver, 100%
69non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
70such as Windows) and lots of real-world knowledge and workarounds for
71platform bugs and differences.
72
67Of course, if you want lots of policy (this can arguably be somewhat 73Now, if you I<do want> lots of policy (this can arguably be somewhat
68useful) and you want to force your users to use the one and only event 74useful) and you want to force your users to use the one and only event
69model, you should I<not> use this module. 75model, you should I<not> use this module.
70 76
71=head1 DESCRIPTION 77=head1 DESCRIPTION
72 78
… …
102starts using it, all bets are off. Maybe you should tell their authors to 108starts using it, all bets are off. Maybe you should tell their authors to
103use AnyEvent so their modules work together with others seamlessly... 109use AnyEvent so their modules work together with others seamlessly...
104 110
105The pure-perl implementation of AnyEvent is called 111The pure-perl implementation of AnyEvent is called
106C<AnyEvent::Impl::Perl>. Like other event modules you can load it 112C<AnyEvent::Impl::Perl>. Like other event modules you can load it
107explicitly. 113explicitly and enjoy the high availability of that event loop :)
108 114
109=head1 WATCHERS 115=head1 WATCHERS
110 116
111AnyEvent has the central concept of a I<watcher>, which is an object that 117AnyEvent has the central concept of a I<watcher>, which is an object that
112stores relevant data for each kind of event you are waiting for, such as 118stores relevant data for each kind of event you are waiting for, such as
… …
311>> method, usually without arguments. The only argument pair allowed is 317>> method, usually without arguments. The only argument pair allowed is
312C<cb>, which specifies a callback to be called when the condition variable 318C<cb>, which specifies a callback to be called when the condition variable
313becomes true. 319becomes true.
314 320
315After creation, the condition variable is "false" until it becomes "true" 321After creation, the condition variable is "false" until it becomes "true"
316by calling the C<send> method. 322by calling the C<send> method (or calling the condition variable as if it
323were a callback, read about the caveats in the description for the C<<
324->send >> method).
317 325
318Condition variables are similar to callbacks, except that you can 326Condition variables are similar to callbacks, except that you can
319optionally wait for them. They can also be called merge points - points 327optionally wait for them. They can also be called merge points - points
320in time where multiple outstanding events have been processed. And yet 328in time where multiple outstanding events have been processed. And yet
321another way to call them is transactions - each condition variable can be 329another way to call them is transactions - each condition variable can be
… …
347 355
348There are two "sides" to a condition variable - the "producer side" which 356There are two "sides" to a condition variable - the "producer side" which
349eventually calls C<< -> send >>, and the "consumer side", which waits 357eventually calls C<< -> send >>, and the "consumer side", which waits
350for the send to occur. 358for the send to occur.
351 359
352Example: 360Example: wait for a timer.
353 361
354 # wait till the result is ready 362 # wait till the result is ready
355 my $result_ready = AnyEvent->condvar; 363 my $result_ready = AnyEvent->condvar;
356 364
357 # do something such as adding a timer 365 # do something such as adding a timer
… …
365 373
366 # this "blocks" (while handling events) till the callback 374 # this "blocks" (while handling events) till the callback
367 # calls send 375 # calls send
368 $result_ready->recv; 376 $result_ready->recv;
369 377
378Example: wait for a timer, but take advantage of the fact that
379condition variables are also code references.
380
381 my $done = AnyEvent->condvar;
382 my $delay = AnyEvent->timer (after => 5, cb => $done);
383 $done->recv;
384
370=head3 METHODS FOR PRODUCERS 385=head3 METHODS FOR PRODUCERS
371 386
372These methods should only be used by the producing side, i.e. the 387These methods should only be used by the producing side, i.e. the
373code/module that eventually sends the signal. Note that it is also 388code/module that eventually sends the signal. Note that it is also
374the producer side which creates the condvar in most cases, but it isn't 389the producer side which creates the condvar in most cases, but it isn't
… …
385If a callback has been set on the condition variable, it is called 400If a callback has been set on the condition variable, it is called
386immediately from within send. 401immediately from within send.
387 402
388Any arguments passed to the C<send> call will be returned by all 403Any arguments passed to the C<send> call will be returned by all
389future C<< ->recv >> calls. 404future C<< ->recv >> calls.
405
406Condition variables are overloaded so one can call them directly
407(as a code reference). Calling them directly is the same as calling
408C<send>. Note, however, that many C-based event loops do not handle
409overloading, so as tempting as it may be, passing a condition variable
410instead of a callback does not work. Both the pure perl and EV loops
411support overloading, however, as well as all functions that use perl to
412invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
413example).
390 414
391=item $cv->croak ($error) 415=item $cv->croak ($error)
392 416
393Similar to send, but causes all call's to C<< ->recv >> to invoke 417Similar to send, but causes all call's to C<< ->recv >> to invoke
394C<Carp::croak> with the given error message/object/scalar. 418C<Carp::croak> with the given error message/object/scalar.
… …
601 625
602If it doesn't care, it can just "use AnyEvent" and use it itself, or not 626If it doesn't care, it can just "use AnyEvent" and use it itself, or not
603do anything special (it does not need to be event-based) and let AnyEvent 627do anything special (it does not need to be event-based) and let AnyEvent
604decide which implementation to chose if some module relies on it. 628decide which implementation to chose if some module relies on it.
605 629
606If the main program relies on a specific event model. For example, in 630If the main program relies on a specific event model - for example, in
607Gtk2 programs you have to rely on the Glib module. You should load the 631Gtk2 programs you have to rely on the Glib module - you should load the
608event module before loading AnyEvent or any module that uses it: generally 632event module before loading AnyEvent or any module that uses it: generally
609speaking, you should load it as early as possible. The reason is that 633speaking, you should load it as early as possible. The reason is that
610modules might create watchers when they are loaded, and AnyEvent will 634modules might create watchers when they are loaded, and AnyEvent will
611decide on the event model to use as soon as it creates watchers, and it 635decide on the event model to use as soon as it creates watchers, and it
612might chose the wrong one unless you load the correct one yourself. 636might chose the wrong one unless you load the correct one yourself.
613 637
614You can chose to use a rather inefficient pure-perl implementation by 638You can chose to use a pure-perl implementation by loading the
615loading the C<AnyEvent::Impl::Perl> module, which gives you similar 639C<AnyEvent::Impl::Perl> module, which gives you similar behaviour
616behaviour everywhere, but letting AnyEvent chose is generally better. 640everywhere, but letting AnyEvent chose the model is generally better.
641
642=head2 MAINLOOP EMULATION
643
644Sometimes (often for short test scripts, or even standalone programs who
645only want to use AnyEvent), you do not want to run a specific event loop.
646
647In that case, you can use a condition variable like this:
648
649 AnyEvent->condvar->recv;
650
651This has the effect of entering the event loop and looping forever.
652
653Note that usually your program has some exit condition, in which case
654it is better to use the "traditional" approach of storing a condition
655variable somewhere, waiting for it, and sending it when the program should
656exit cleanly.
657
617 658
618=head1 OTHER MODULES 659=head1 OTHER MODULES
619 660
620The following is a non-exhaustive list of additional modules that use 661The following is a non-exhaustive list of additional modules that use
621AnyEvent and can therefore be mixed easily with other AnyEvent modules 662AnyEvent and can therefore be mixed easily with other AnyEvent modules
… …
637 678
638Provides various utility functions for (internet protocol) sockets, 679Provides various utility functions for (internet protocol) sockets,
639addresses and name resolution. Also functions to create non-blocking tcp 680addresses and name resolution. Also functions to create non-blocking tcp
640connections or tcp servers, with IPv6 and SRV record support and more. 681connections or tcp servers, with IPv6 and SRV record support and more.
641 682
683=item L<AnyEvent::DNS>
684
685Provides rich asynchronous DNS resolver capabilities.
686
642=item L<AnyEvent::HTTPD> 687=item L<AnyEvent::HTTPD>
643 688
644Provides a simple web application server framework. 689Provides a simple web application server framework.
645
646=item L<AnyEvent::DNS>
647
648Provides rich asynchronous DNS resolver capabilities.
649 690
650=item L<AnyEvent::FastPing> 691=item L<AnyEvent::FastPing>
651 692
652The fastest ping in the west. 693The fastest ping in the west.
653 694
… …
696no warnings; 737no warnings;
697use strict; 738use strict;
698 739
699use Carp; 740use Carp;
700 741
701our $VERSION = '3.6'; 742our $VERSION = '4.05';
702our $MODEL; 743our $MODEL;
703 744
704our $AUTOLOAD; 745our $AUTOLOAD;
705our @ISA; 746our @ISA;
706 747
748our @REGISTRY;
749
750our $WIN32;
751
752BEGIN {
753 my $win32 = ! ! ($^O =~ /mswin32/i);
754 eval "sub WIN32(){ $win32 }";
755}
756
707our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 757our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
708 758
709our @REGISTRY; 759our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
710
711our %PROTOCOL; # (ipv4|ipv6) => (1|2)
712 760
713{ 761{
714 my $idx; 762 my $idx;
715 $PROTOCOL{$_} = ++$idx 763 $PROTOCOL{$_} = ++$idx
764 for reverse split /\s*,\s*/,
716 for split /\s*,\s*/, $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 765 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
717} 766}
718 767
719my @models = ( 768my @models = (
720 [EV:: => AnyEvent::Impl::EV::], 769 [EV:: => AnyEvent::Impl::EV::],
721 [Event:: => AnyEvent::Impl::Event::], 770 [Event:: => AnyEvent::Impl::Event::],
722 [Tk:: => AnyEvent::Impl::Tk::],
723 [Wx:: => AnyEvent::Impl::POE::],
724 [Prima:: => AnyEvent::Impl::POE::],
725 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 771 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
726 # everything below here will not be autoprobed as the pureperl backend should work everywhere 772 # everything below here will not be autoprobed
727 [Glib:: => AnyEvent::Impl::Glib::], 773 # as the pureperl backend should work everywhere
774 # and is usually faster
775 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
776 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
728 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 777 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
729 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 778 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
730 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 779 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
780 [Wx:: => AnyEvent::Impl::POE::],
781 [Prima:: => AnyEvent::Impl::POE::],
731); 782);
732 783
733our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 784our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
734 785
735our @post_detect; 786our @post_detect;
… …
755} 806}
756 807
757sub detect() { 808sub detect() {
758 unless ($MODEL) { 809 unless ($MODEL) {
759 no strict 'refs'; 810 no strict 'refs';
811 local $SIG{__DIE__};
760 812
761 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 813 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
762 my $model = "AnyEvent::Impl::$1"; 814 my $model = "AnyEvent::Impl::$1";
763 if (eval "require $model") { 815 if (eval "require $model") {
764 $MODEL = $model; 816 $MODEL = $model;
… …
887 or Carp::croak "required option 'pid' is missing"; 939 or Carp::croak "required option 'pid' is missing";
888 940
889 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 941 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
890 942
891 unless ($WNOHANG) { 943 unless ($WNOHANG) {
892 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 944 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
893 } 945 }
894 946
895 unless ($CHLD_W) { 947 unless ($CHLD_W) {
896 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 948 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
897 # child could be a zombie already, so make at least one round 949 # child could be a zombie already, so make at least one round
… …
913package AnyEvent::CondVar; 965package AnyEvent::CondVar;
914 966
915our @ISA = AnyEvent::CondVar::Base::; 967our @ISA = AnyEvent::CondVar::Base::;
916 968
917package AnyEvent::CondVar::Base; 969package AnyEvent::CondVar::Base;
970
971use overload
972 '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
973 fallback => 1;
918 974
919sub _send { 975sub _send {
920 # nop 976 # nop
921} 977}
922 978
… …
1072some (broken) firewalls drop such DNS packets, which is why it is off by 1128some (broken) firewalls drop such DNS packets, which is why it is off by
1073default. 1129default.
1074 1130
1075Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 1131Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1076EDNS0 in its DNS requests. 1132EDNS0 in its DNS requests.
1133
1134=item C<PERL_ANYEVENT_MAX_FORKS>
1135
1136The maximum number of child processes that C<AnyEvent::Util::fork_call>
1137will create in parallel.
1077 1138
1078=back 1139=back
1079 1140
1080=head1 EXAMPLE PROGRAM 1141=head1 EXAMPLE PROGRAM
1081 1142

Diff Legend

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