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.147 by root, Fri May 30 21:43:26 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
… …
226on true relative time) and absolute (ev_periodic, based on wallclock time) 232on true relative time) and absolute (ev_periodic, based on wallclock time)
227timers. 233timers.
228 234
229AnyEvent always prefers relative timers, if available, matching the 235AnyEvent always prefers relative timers, if available, matching the
230AnyEvent API. 236AnyEvent API.
237
238AnyEvent has two additional methods that return the "current time":
239
240=over 4
241
242=item AnyEvent->time
243
244This returns the "current wallclock time" as a fractional number of
245seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
246return, and the result is guaranteed to be compatible with those).
247
248It progresses independently of any event loop processing, i.e. each call
249will check the system clock, which usually gets updated frequently.
250
251=item AnyEvent->now
252
253This also returns the "current wallclock time", but unlike C<time>, above,
254this value might change only once per event loop iteration, depending on
255the event loop (most return the same time as C<time>, above). This is the
256time that AnyEvent's timers get scheduled against.
257
258I<In almost all cases (in all cases if you don't care), this is the
259function to call when you want to know the current time.>
260
261This function is also often faster then C<< AnyEvent->time >>, and
262thus the preferred method if you want some timestamp (for example,
263L<AnyEvent::Handle> uses this to update it's activity timeouts).
264
265The rest of this section is only of relevance if you try to be very exact
266with your timing, you can skip it without bad conscience.
267
268For a practical example of when these times differ, consider L<Event::Lib>
269and L<EV> and the following set-up:
270
271The event loop is running and has just invoked one of your callback at
272time=500 (assume no other callbacks delay processing). In your callback,
273you wait a second by executing C<sleep 1> (blocking the process for a
274second) and then (at time=501) you create a relative timer that fires
275after three seconds.
276
277With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
278both return C<501>, because that is the current time, and the timer will
279be scheduled to fire at time=504 (C<501> + C<3>).
280
281With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
282time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
283last event processing phase started. With L<EV>, your timer gets scheduled
284to run at time=503 (C<500> + C<3>).
285
286In one sense, L<Event::Lib> is more exact, as it uses the current time
287regardless of any delays introduced by event processing. However, most
288callbacks do not expect large delays in processing, so this causes a
289higher drift (and a lot more system calls to get the current time).
290
291In another sense, L<EV> is more exact, as your timer will be scheduled at
292the same time, regardless of how long event processing actually took.
293
294In either case, if you care (and in most cases, you don't), then you
295can get whatever behaviour you want with any event loop, by taking the
296difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
297account.
298
299=back
231 300
232=head2 SIGNAL WATCHERS 301=head2 SIGNAL WATCHERS
233 302
234You can watch for signals using a signal watcher, C<signal> is the signal 303You can watch for signals using a signal watcher, C<signal> is the signal
235I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 304I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
… …
311>> method, usually without arguments. The only argument pair allowed is 380>> method, usually without arguments. The only argument pair allowed is
312C<cb>, which specifies a callback to be called when the condition variable 381C<cb>, which specifies a callback to be called when the condition variable
313becomes true. 382becomes true.
314 383
315After creation, the condition variable is "false" until it becomes "true" 384After creation, the condition variable is "false" until it becomes "true"
316by calling the C<send> method. 385by calling the C<send> method (or calling the condition variable as if it
386were a callback, read about the caveats in the description for the C<<
387->send >> method).
317 388
318Condition variables are similar to callbacks, except that you can 389Condition variables are similar to callbacks, except that you can
319optionally wait for them. They can also be called merge points - points 390optionally wait for them. They can also be called merge points - points
320in time where multiple outstanding events have been processed. And yet 391in time where multiple outstanding events have been processed. And yet
321another way to call them is transactions - each condition variable can be 392another way to call them is transactions - each condition variable can be
… …
347 418
348There are two "sides" to a condition variable - the "producer side" which 419There are two "sides" to a condition variable - the "producer side" which
349eventually calls C<< -> send >>, and the "consumer side", which waits 420eventually calls C<< -> send >>, and the "consumer side", which waits
350for the send to occur. 421for the send to occur.
351 422
352Example: 423Example: wait for a timer.
353 424
354 # wait till the result is ready 425 # wait till the result is ready
355 my $result_ready = AnyEvent->condvar; 426 my $result_ready = AnyEvent->condvar;
356 427
357 # do something such as adding a timer 428 # do something such as adding a timer
… …
365 436
366 # this "blocks" (while handling events) till the callback 437 # this "blocks" (while handling events) till the callback
367 # calls send 438 # calls send
368 $result_ready->recv; 439 $result_ready->recv;
369 440
441Example: wait for a timer, but take advantage of the fact that
442condition variables are also code references.
443
444 my $done = AnyEvent->condvar;
445 my $delay = AnyEvent->timer (after => 5, cb => $done);
446 $done->recv;
447
370=head3 METHODS FOR PRODUCERS 448=head3 METHODS FOR PRODUCERS
371 449
372These methods should only be used by the producing side, i.e. the 450These methods should only be used by the producing side, i.e. the
373code/module that eventually sends the signal. Note that it is also 451code/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 452the 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 463If a callback has been set on the condition variable, it is called
386immediately from within send. 464immediately from within send.
387 465
388Any arguments passed to the C<send> call will be returned by all 466Any arguments passed to the C<send> call will be returned by all
389future C<< ->recv >> calls. 467future C<< ->recv >> calls.
468
469Condition variables are overloaded so one can call them directly
470(as a code reference). Calling them directly is the same as calling
471C<send>. Note, however, that many C-based event loops do not handle
472overloading, so as tempting as it may be, passing a condition variable
473instead of a callback does not work. Both the pure perl and EV loops
474support overloading, however, as well as all functions that use perl to
475invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
476example).
390 477
391=item $cv->croak ($error) 478=item $cv->croak ($error)
392 479
393Similar to send, but causes all call's to C<< ->recv >> to invoke 480Similar to send, but causes all call's to C<< ->recv >> to invoke
394C<Carp::croak> with the given error message/object/scalar. 481C<Carp::croak> with the given error message/object/scalar.
… …
601 688
602If it doesn't care, it can just "use AnyEvent" and use it itself, or not 689If 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 690do anything special (it does not need to be event-based) and let AnyEvent
604decide which implementation to chose if some module relies on it. 691decide which implementation to chose if some module relies on it.
605 692
606If the main program relies on a specific event model. For example, in 693If 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 694Gtk2 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 695event module before loading AnyEvent or any module that uses it: generally
609speaking, you should load it as early as possible. The reason is that 696speaking, you should load it as early as possible. The reason is that
610modules might create watchers when they are loaded, and AnyEvent will 697modules 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 698decide 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. 699might chose the wrong one unless you load the correct one yourself.
613 700
614You can chose to use a rather inefficient pure-perl implementation by 701You can chose to use a pure-perl implementation by loading the
615loading the C<AnyEvent::Impl::Perl> module, which gives you similar 702C<AnyEvent::Impl::Perl> module, which gives you similar behaviour
616behaviour everywhere, but letting AnyEvent chose is generally better. 703everywhere, but letting AnyEvent chose the model is generally better.
704
705=head2 MAINLOOP EMULATION
706
707Sometimes (often for short test scripts, or even standalone programs who
708only want to use AnyEvent), you do not want to run a specific event loop.
709
710In that case, you can use a condition variable like this:
711
712 AnyEvent->condvar->recv;
713
714This has the effect of entering the event loop and looping forever.
715
716Note that usually your program has some exit condition, in which case
717it is better to use the "traditional" approach of storing a condition
718variable somewhere, waiting for it, and sending it when the program should
719exit cleanly.
720
617 721
618=head1 OTHER MODULES 722=head1 OTHER MODULES
619 723
620The following is a non-exhaustive list of additional modules that use 724The following is a non-exhaustive list of additional modules that use
621AnyEvent and can therefore be mixed easily with other AnyEvent modules 725AnyEvent and can therefore be mixed easily with other AnyEvent modules
… …
637 741
638Provides various utility functions for (internet protocol) sockets, 742Provides various utility functions for (internet protocol) sockets,
639addresses and name resolution. Also functions to create non-blocking tcp 743addresses and name resolution. Also functions to create non-blocking tcp
640connections or tcp servers, with IPv6 and SRV record support and more. 744connections or tcp servers, with IPv6 and SRV record support and more.
641 745
746=item L<AnyEvent::DNS>
747
748Provides rich asynchronous DNS resolver capabilities.
749
642=item L<AnyEvent::HTTPD> 750=item L<AnyEvent::HTTPD>
643 751
644Provides a simple web application server framework. 752Provides a simple web application server framework.
645
646=item L<AnyEvent::DNS>
647
648Provides rich asynchronous DNS resolver capabilities.
649 753
650=item L<AnyEvent::FastPing> 754=item L<AnyEvent::FastPing>
651 755
652The fastest ping in the west. 756The fastest ping in the west.
653 757
… …
696no warnings; 800no warnings;
697use strict; 801use strict;
698 802
699use Carp; 803use Carp;
700 804
701our $VERSION = '3.6'; 805our $VERSION = 4.11;
702our $MODEL; 806our $MODEL;
703 807
704our $AUTOLOAD; 808our $AUTOLOAD;
705our @ISA; 809our @ISA;
706 810
811our @REGISTRY;
812
813our $WIN32;
814
815BEGIN {
816 my $win32 = ! ! ($^O =~ /mswin32/i);
817 eval "sub WIN32(){ $win32 }";
818}
819
707our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 820our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
708 821
709our @REGISTRY; 822our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
710
711our %PROTOCOL; # (ipv4|ipv6) => (1|2)
712 823
713{ 824{
714 my $idx; 825 my $idx;
715 $PROTOCOL{$_} = ++$idx 826 $PROTOCOL{$_} = ++$idx
827 for reverse split /\s*,\s*/,
716 for split /\s*,\s*/, $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 828 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
717} 829}
718 830
719my @models = ( 831my @models = (
720 [EV:: => AnyEvent::Impl::EV::], 832 [EV:: => AnyEvent::Impl::EV::],
721 [Event:: => AnyEvent::Impl::Event::], 833 [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::], 834 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
726 # everything below here will not be autoprobed as the pureperl backend should work everywhere 835 # everything below here will not be autoprobed
727 [Glib:: => AnyEvent::Impl::Glib::], 836 # as the pureperl backend should work everywhere
837 # and is usually faster
838 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
839 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
728 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 840 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
729 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 841 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
730 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 842 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
843 [Wx:: => AnyEvent::Impl::POE::],
844 [Prima:: => AnyEvent::Impl::POE::],
731); 845);
732 846
733our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 847our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
734 848
735our @post_detect; 849our @post_detect;
736 850
737sub post_detect(&) { 851sub post_detect(&) {
738 my ($cb) = @_; 852 my ($cb) = @_;
… …
755} 869}
756 870
757sub detect() { 871sub detect() {
758 unless ($MODEL) { 872 unless ($MODEL) {
759 no strict 'refs'; 873 no strict 'refs';
874 local $SIG{__DIE__};
760 875
761 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 876 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
762 my $model = "AnyEvent::Impl::$1"; 877 my $model = "AnyEvent::Impl::$1";
763 if (eval "require $model") { 878 if (eval "require $model") {
764 $MODEL = $model; 879 $MODEL = $model;
… …
821 $class->$func (@_); 936 $class->$func (@_);
822} 937}
823 938
824package AnyEvent::Base; 939package AnyEvent::Base;
825 940
941# default implementation for now and time
942
943use Time::HiRes ();
944
945sub time { Time::HiRes::time }
946sub now { Time::HiRes::time }
947
826# default implementation for ->condvar 948# default implementation for ->condvar
827 949
828sub condvar { 950sub condvar {
829 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 951 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
830} 952}
… …
887 or Carp::croak "required option 'pid' is missing"; 1009 or Carp::croak "required option 'pid' is missing";
888 1010
889 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1011 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
890 1012
891 unless ($WNOHANG) { 1013 unless ($WNOHANG) {
892 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 1014 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
893 } 1015 }
894 1016
895 unless ($CHLD_W) { 1017 unless ($CHLD_W) {
896 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1018 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
897 # child could be a zombie already, so make at least one round 1019 # child could be a zombie already, so make at least one round
… …
913package AnyEvent::CondVar; 1035package AnyEvent::CondVar;
914 1036
915our @ISA = AnyEvent::CondVar::Base::; 1037our @ISA = AnyEvent::CondVar::Base::;
916 1038
917package AnyEvent::CondVar::Base; 1039package AnyEvent::CondVar::Base;
1040
1041use overload
1042 '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1043 fallback => 1;
918 1044
919sub _send { 1045sub _send {
920 # nop 1046 # nop
921} 1047}
922 1048
… …
1072some (broken) firewalls drop such DNS packets, which is why it is off by 1198some (broken) firewalls drop such DNS packets, which is why it is off by
1073default. 1199default.
1074 1200
1075Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 1201Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1076EDNS0 in its DNS requests. 1202EDNS0 in its DNS requests.
1203
1204=item C<PERL_ANYEVENT_MAX_FORKS>
1205
1206The maximum number of child processes that C<AnyEvent::Util::fork_call>
1207will create in parallel.
1077 1208
1078=back 1209=back
1079 1210
1080=head1 EXAMPLE PROGRAM 1211=head1 EXAMPLE PROGRAM
1081 1212

Diff Legend

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