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.133 by root, Sun May 25 03:44:03 2008 UTC vs.
Revision 1.148 by root, Sat May 31 00:40:16 2008 UTC

… …
17 }); 17 });
18 18
19 my $w = AnyEvent->condvar; # stores whether a condition was flagged 19 my $w = AnyEvent->condvar; # stores whether a condition was flagged
20 $w->send; # wake up current and all future recv's 20 $w->send; # wake up current and all future recv's
21 $w->recv; # enters "main loop" till $condvar gets ->send 21 $w->recv; # enters "main loop" till $condvar gets ->send
22
23=head1 INTRODUCTION/TUTORIAL
24
25This manpage is mainly a reference manual. If you are interested
26in a tutorial or some gentle introduction, have a look at the
27L<AnyEvent::Intro> manpage.
22 28
23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 29=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24 30
25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 31Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26nowadays. So what is different about AnyEvent? 32nowadays. So what is different about AnyEvent?
… …
48isn't itself. What's worse, all the potential users of your module are 54isn't itself. What's worse, all the potential users of your module are
49I<also> forced to use the same event loop you use. 55I<also> forced to use the same event loop you use.
50 56
51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 57AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
52fine. AnyEvent + Tk works fine etc. etc. but none of these work together 58fine. 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 59with 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, 60your 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 61too. But if your module uses AnyEvent, it works transparently with all
56event models it supports (including stuff like POE and IO::Async, as long 62event 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 63as those use one of the supported event loops. It is trivial to add new
58event loops to AnyEvent, too, so it is future-proof). 64event loops to AnyEvent, too, so it is future-proof).
… …
62modules, you get an enormous amount of code and strict rules you have to 68modules, 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 69follow. 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 70offering the functionality that is necessary, in as thin as a wrapper as
65technically possible. 71technically possible.
66 72
73Of course, AnyEvent comes with a big (and fully optional!) toolbox
74of useful functionality, such as an asynchronous DNS resolver, 100%
75non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
76such as Windows) and lots of real-world knowledge and workarounds for
77platform bugs and differences.
78
67Of course, if you want lots of policy (this can arguably be somewhat 79Now, 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 80useful) and you want to force your users to use the one and only event
69model, you should I<not> use this module. 81model, you should I<not> use this module.
70 82
71=head1 DESCRIPTION 83=head1 DESCRIPTION
72 84
… …
102starts using it, all bets are off. Maybe you should tell their authors to 114starts using it, all bets are off. Maybe you should tell their authors to
103use AnyEvent so their modules work together with others seamlessly... 115use AnyEvent so their modules work together with others seamlessly...
104 116
105The pure-perl implementation of AnyEvent is called 117The pure-perl implementation of AnyEvent is called
106C<AnyEvent::Impl::Perl>. Like other event modules you can load it 118C<AnyEvent::Impl::Perl>. Like other event modules you can load it
107explicitly. 119explicitly and enjoy the high availability of that event loop :)
108 120
109=head1 WATCHERS 121=head1 WATCHERS
110 122
111AnyEvent has the central concept of a I<watcher>, which is an object that 123AnyEvent 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 124stores 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) 238on true relative time) and absolute (ev_periodic, based on wallclock time)
227timers. 239timers.
228 240
229AnyEvent always prefers relative timers, if available, matching the 241AnyEvent always prefers relative timers, if available, matching the
230AnyEvent API. 242AnyEvent API.
243
244AnyEvent has two additional methods that return the "current time":
245
246=over 4
247
248=item AnyEvent->time
249
250This returns the "current wallclock time" as a fractional number of
251seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
252return, and the result is guaranteed to be compatible with those).
253
254It progresses independently of any event loop processing, i.e. each call
255will check the system clock, which usually gets updated frequently.
256
257=item AnyEvent->now
258
259This also returns the "current wallclock time", but unlike C<time>, above,
260this value might change only once per event loop iteration, depending on
261the event loop (most return the same time as C<time>, above). This is the
262time that AnyEvent's timers get scheduled against.
263
264I<In almost all cases (in all cases if you don't care), this is the
265function to call when you want to know the current time.>
266
267This function is also often faster then C<< AnyEvent->time >>, and
268thus the preferred method if you want some timestamp (for example,
269L<AnyEvent::Handle> uses this to update it's activity timeouts).
270
271The rest of this section is only of relevance if you try to be very exact
272with your timing, you can skip it without bad conscience.
273
274For a practical example of when these times differ, consider L<Event::Lib>
275and L<EV> and the following set-up:
276
277The event loop is running and has just invoked one of your callback at
278time=500 (assume no other callbacks delay processing). In your callback,
279you wait a second by executing C<sleep 1> (blocking the process for a
280second) and then (at time=501) you create a relative timer that fires
281after three seconds.
282
283With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
284both return C<501>, because that is the current time, and the timer will
285be scheduled to fire at time=504 (C<501> + C<3>).
286
287With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
288time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
289last event processing phase started. With L<EV>, your timer gets scheduled
290to run at time=503 (C<500> + C<3>).
291
292In one sense, L<Event::Lib> is more exact, as it uses the current time
293regardless of any delays introduced by event processing. However, most
294callbacks do not expect large delays in processing, so this causes a
295higher drift (and a lot more system calls to get the current time).
296
297In another sense, L<EV> is more exact, as your timer will be scheduled at
298the same time, regardless of how long event processing actually took.
299
300In either case, if you care (and in most cases, you don't), then you
301can get whatever behaviour you want with any event loop, by taking the
302difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
303account.
304
305=back
231 306
232=head2 SIGNAL WATCHERS 307=head2 SIGNAL WATCHERS
233 308
234You can watch for signals using a signal watcher, C<signal> is the signal 309You 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 310I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
… …
312C<cb>, which specifies a callback to be called when the condition variable 387C<cb>, which specifies a callback to be called when the condition variable
313becomes true. 388becomes true.
314 389
315After creation, the condition variable is "false" until it becomes "true" 390After creation, the condition variable is "false" until it becomes "true"
316by calling the C<send> method (or calling the condition variable as if it 391by calling the C<send> method (or calling the condition variable as if it
317were a callback). 392were a callback, read about the caveats in the description for the C<<
393->send >> method).
318 394
319Condition variables are similar to callbacks, except that you can 395Condition variables are similar to callbacks, except that you can
320optionally wait for them. They can also be called merge points - points 396optionally wait for them. They can also be called merge points - points
321in time where multiple outstanding events have been processed. And yet 397in time where multiple outstanding events have been processed. And yet
322another way to call them is transactions - each condition variable can be 398another way to call them is transactions - each condition variable can be
… …
394immediately from within send. 470immediately from within send.
395 471
396Any arguments passed to the C<send> call will be returned by all 472Any arguments passed to the C<send> call will be returned by all
397future C<< ->recv >> calls. 473future C<< ->recv >> calls.
398 474
399Condition variables are overloaded so one can call them directly (as a 475Condition variables are overloaded so one can call them directly
400code reference). Calling them directly is the same as calling C<send>. 476(as a code reference). Calling them directly is the same as calling
477C<send>. Note, however, that many C-based event loops do not handle
478overloading, so as tempting as it may be, passing a condition variable
479instead of a callback does not work. Both the pure perl and EV loops
480support overloading, however, as well as all functions that use perl to
481invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
482example).
401 483
402=item $cv->croak ($error) 484=item $cv->croak ($error)
403 485
404Similar to send, but causes all call's to C<< ->recv >> to invoke 486Similar to send, but causes all call's to C<< ->recv >> to invoke
405C<Carp::croak> with the given error message/object/scalar. 487C<Carp::croak> with the given error message/object/scalar.
… …
519The callback will be called when the condition becomes "true", i.e. when 601The callback will be called when the condition becomes "true", i.e. when
520C<send> or C<croak> are called. Calling C<recv> inside the callback 602C<send> or C<croak> are called. Calling C<recv> inside the callback
521or at any later time is guaranteed not to block. 603or at any later time is guaranteed not to block.
522 604
523=back 605=back
524
525=head3 MAINLOOP EMULATION
526
527Sometimes (often for short test scripts, or even standalone programs
528who only want to use AnyEvent), you I<do> want your program to block
529indefinitely in some event loop.
530
531In that case, you cna use a condition variable like this:
532
533 AnyEvent->condvar->recv;
534
535This has the effect of entering the event loop and looping forever.
536
537Note that usually your program has some exit condition, in which case
538it is better to use the "traditional" approach of storing a condition
539variable, waiting for it, and sending it when the program should exit
540cleanly.
541
542 606
543=head1 GLOBAL VARIABLES AND FUNCTIONS 607=head1 GLOBAL VARIABLES AND FUNCTIONS
544 608
545=over 4 609=over 4
546 610
… …
630 694
631If it doesn't care, it can just "use AnyEvent" and use it itself, or not 695If it doesn't care, it can just "use AnyEvent" and use it itself, or not
632do anything special (it does not need to be event-based) and let AnyEvent 696do anything special (it does not need to be event-based) and let AnyEvent
633decide which implementation to chose if some module relies on it. 697decide which implementation to chose if some module relies on it.
634 698
635If the main program relies on a specific event model. For example, in 699If the main program relies on a specific event model - for example, in
636Gtk2 programs you have to rely on the Glib module. You should load the 700Gtk2 programs you have to rely on the Glib module - you should load the
637event module before loading AnyEvent or any module that uses it: generally 701event module before loading AnyEvent or any module that uses it: generally
638speaking, you should load it as early as possible. The reason is that 702speaking, you should load it as early as possible. The reason is that
639modules might create watchers when they are loaded, and AnyEvent will 703modules might create watchers when they are loaded, and AnyEvent will
640decide on the event model to use as soon as it creates watchers, and it 704decide on the event model to use as soon as it creates watchers, and it
641might chose the wrong one unless you load the correct one yourself. 705might chose the wrong one unless you load the correct one yourself.
642 706
643You can chose to use a rather inefficient pure-perl implementation by 707You can chose to use a pure-perl implementation by loading the
644loading the C<AnyEvent::Impl::Perl> module, which gives you similar 708C<AnyEvent::Impl::Perl> module, which gives you similar behaviour
645behaviour everywhere, but letting AnyEvent chose is generally better. 709everywhere, but letting AnyEvent chose the model is generally better.
710
711=head2 MAINLOOP EMULATION
712
713Sometimes (often for short test scripts, or even standalone programs who
714only want to use AnyEvent), you do not want to run a specific event loop.
715
716In that case, you can use a condition variable like this:
717
718 AnyEvent->condvar->recv;
719
720This has the effect of entering the event loop and looping forever.
721
722Note that usually your program has some exit condition, in which case
723it is better to use the "traditional" approach of storing a condition
724variable somewhere, waiting for it, and sending it when the program should
725exit cleanly.
726
646 727
647=head1 OTHER MODULES 728=head1 OTHER MODULES
648 729
649The following is a non-exhaustive list of additional modules that use 730The following is a non-exhaustive list of additional modules that use
650AnyEvent and can therefore be mixed easily with other AnyEvent modules 731AnyEvent and can therefore be mixed easily with other AnyEvent modules
… …
666 747
667Provides various utility functions for (internet protocol) sockets, 748Provides various utility functions for (internet protocol) sockets,
668addresses and name resolution. Also functions to create non-blocking tcp 749addresses and name resolution. Also functions to create non-blocking tcp
669connections or tcp servers, with IPv6 and SRV record support and more. 750connections or tcp servers, with IPv6 and SRV record support and more.
670 751
752=item L<AnyEvent::DNS>
753
754Provides rich asynchronous DNS resolver capabilities.
755
671=item L<AnyEvent::HTTPD> 756=item L<AnyEvent::HTTPD>
672 757
673Provides a simple web application server framework. 758Provides a simple web application server framework.
674
675=item L<AnyEvent::DNS>
676
677Provides rich asynchronous DNS resolver capabilities.
678 759
679=item L<AnyEvent::FastPing> 760=item L<AnyEvent::FastPing>
680 761
681The fastest ping in the west. 762The fastest ping in the west.
682 763
… …
725no warnings; 806no warnings;
726use strict; 807use strict;
727 808
728use Carp; 809use Carp;
729 810
730our $VERSION = '4.03'; 811our $VERSION = 4.11;
731our $MODEL; 812our $MODEL;
732 813
733our $AUTOLOAD; 814our $AUTOLOAD;
734our @ISA; 815our @ISA;
735 816
817our @REGISTRY;
818
819our $WIN32;
820
821BEGIN {
822 my $win32 = ! ! ($^O =~ /mswin32/i);
823 eval "sub WIN32(){ $win32 }";
824}
825
736our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 826our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
737 827
738our @REGISTRY; 828our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
739
740our %PROTOCOL; # (ipv4|ipv6) => (1|2)
741 829
742{ 830{
743 my $idx; 831 my $idx;
744 $PROTOCOL{$_} = ++$idx 832 $PROTOCOL{$_} = ++$idx
833 for reverse split /\s*,\s*/,
745 for split /\s*,\s*/, $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 834 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
746} 835}
747 836
748my @models = ( 837my @models = (
749 [EV:: => AnyEvent::Impl::EV::], 838 [EV:: => AnyEvent::Impl::EV::],
750 [Event:: => AnyEvent::Impl::Event::], 839 [Event:: => AnyEvent::Impl::Event::],
751 [Tk:: => AnyEvent::Impl::Tk::],
752 [Wx:: => AnyEvent::Impl::POE::],
753 [Prima:: => AnyEvent::Impl::POE::],
754 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 840 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
755 # everything below here will not be autoprobed as the pureperl backend should work everywhere 841 # everything below here will not be autoprobed
756 [Glib:: => AnyEvent::Impl::Glib::], 842 # as the pureperl backend should work everywhere
843 # and is usually faster
844 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
845 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
757 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 846 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
758 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 847 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
759 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 848 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
849 [Wx:: => AnyEvent::Impl::POE::],
850 [Prima:: => AnyEvent::Impl::POE::],
760); 851);
761 852
762our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 853our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
763 854
764our @post_detect; 855our @post_detect;
765 856
766sub post_detect(&) { 857sub post_detect(&) {
767 my ($cb) = @_; 858 my ($cb) = @_;
… …
784} 875}
785 876
786sub detect() { 877sub detect() {
787 unless ($MODEL) { 878 unless ($MODEL) {
788 no strict 'refs'; 879 no strict 'refs';
880 local $SIG{__DIE__};
789 881
790 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 882 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
791 my $model = "AnyEvent::Impl::$1"; 883 my $model = "AnyEvent::Impl::$1";
792 if (eval "require $model") { 884 if (eval "require $model") {
793 $MODEL = $model; 885 $MODEL = $model;
… …
850 $class->$func (@_); 942 $class->$func (@_);
851} 943}
852 944
853package AnyEvent::Base; 945package AnyEvent::Base;
854 946
947# default implementation for now and time
948
949use Time::HiRes ();
950
951sub time { Time::HiRes::time }
952sub now { Time::HiRes::time }
953
855# default implementation for ->condvar 954# default implementation for ->condvar
856 955
857sub condvar { 956sub condvar {
858 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 957 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
859} 958}
… …
916 or Carp::croak "required option 'pid' is missing"; 1015 or Carp::croak "required option 'pid' is missing";
917 1016
918 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1017 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
919 1018
920 unless ($WNOHANG) { 1019 unless ($WNOHANG) {
921 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 1020 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
922 } 1021 }
923 1022
924 unless ($CHLD_W) { 1023 unless ($CHLD_W) {
925 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1024 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
926 # child could be a zombie already, so make at least one round 1025 # child could be a zombie already, so make at least one round
… …
1105some (broken) firewalls drop such DNS packets, which is why it is off by 1204some (broken) firewalls drop such DNS packets, which is why it is off by
1106default. 1205default.
1107 1206
1108Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 1207Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1109EDNS0 in its DNS requests. 1208EDNS0 in its DNS requests.
1209
1210=item C<PERL_ANYEVENT_MAX_FORKS>
1211
1212The maximum number of child processes that C<AnyEvent::Util::fork_call>
1213will create in parallel.
1110 1214
1111=back 1215=back
1112 1216
1113=head1 EXAMPLE PROGRAM 1217=head1 EXAMPLE PROGRAM
1114 1218

Diff Legend

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