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.143 by root, Wed May 28 23:57:38 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.
249
250In almost all cases (in all cases if you don't care), this is the function
251to call when you want to know the current time.
252
253=item AnyEvent->now
254
255This also returns the "current wallclock time", but unlike C<time>, above,
256this value might change only once per event loop iteration, depending on
257the event loop (most return the same time as C<time>, above). This is the
258time that AnyEvent timers get scheduled against.
259
260For a practical example of when these times differ, consider L<Event::Lib>
261and L<EV> and the following set-up:
262
263The event loop is running and has just invoked one of your callback at
264time=500 (assume no other callbacks delay processing). In your callback,
265you wait a second by executing C<sleep 1> (blocking the process for a
266second) and then (at time=501) you create a relative timer that fires
267after three seconds.
268
269With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
270both return C<501>, because that is the current time, and the timer will
271be scheduled to fire at time=504 (C<501> + C<3>).
272
273With L<EV>m C<< AnyEvent->time >> returns C<501> (as that is the current
274time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
275last event processing phase started. With L<EV>, your timer gets scheduled
276to run at time=503 (C<500> + C<3>).
277
278In one sense, L<Event::Lib> is more exact, as it uses the current time
279regardless of any delays introduced by event processing. However, most
280callbacks do not expect large delays in processing, so this causes a
281higher drift (and a lot more syscalls to get the current time).
282
283In another sense, L<EV> is more exact, as your timer will be scheduled at
284the same time, regardless of how long event processing actually took.
285
286In either case, if you care (and in most cases, you don't), then you
287can get whatever behaviour you want with any event loop, by taking the
288difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
289account.
290
291=back
231 292
232=head2 SIGNAL WATCHERS 293=head2 SIGNAL WATCHERS
233 294
234You can watch for signals using a signal watcher, C<signal> is the signal 295You 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 296I<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 373C<cb>, which specifies a callback to be called when the condition variable
313becomes true. 374becomes true.
314 375
315After creation, the condition variable is "false" until it becomes "true" 376After creation, the condition variable is "false" until it becomes "true"
316by calling the C<send> method (or calling the condition variable as if it 377by calling the C<send> method (or calling the condition variable as if it
317were a callback). 378were a callback, read about the caveats in the description for the C<<
379->send >> method).
318 380
319Condition variables are similar to callbacks, except that you can 381Condition variables are similar to callbacks, except that you can
320optionally wait for them. They can also be called merge points - points 382optionally wait for them. They can also be called merge points - points
321in time where multiple outstanding events have been processed. And yet 383in time where multiple outstanding events have been processed. And yet
322another way to call them is transactions - each condition variable can be 384another way to call them is transactions - each condition variable can be
… …
394immediately from within send. 456immediately from within send.
395 457
396Any arguments passed to the C<send> call will be returned by all 458Any arguments passed to the C<send> call will be returned by all
397future C<< ->recv >> calls. 459future C<< ->recv >> calls.
398 460
399Condition variables are overloaded so one can call them directly (as a 461Condition variables are overloaded so one can call them directly
400code reference). Calling them directly is the same as calling C<send>. 462(as a code reference). Calling them directly is the same as calling
463C<send>. Note, however, that many C-based event loops do not handle
464overloading, so as tempting as it may be, passing a condition variable
465instead of a callback does not work. Both the pure perl and EV loops
466support overloading, however, as well as all functions that use perl to
467invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
468example).
401 469
402=item $cv->croak ($error) 470=item $cv->croak ($error)
403 471
404Similar to send, but causes all call's to C<< ->recv >> to invoke 472Similar to send, but causes all call's to C<< ->recv >> to invoke
405C<Carp::croak> with the given error message/object/scalar. 473C<Carp::croak> with the given error message/object/scalar.
… …
519The callback will be called when the condition becomes "true", i.e. when 587The 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 588C<send> or C<croak> are called. Calling C<recv> inside the callback
521or at any later time is guaranteed not to block. 589or at any later time is guaranteed not to block.
522 590
523=back 591=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 592
543=head1 GLOBAL VARIABLES AND FUNCTIONS 593=head1 GLOBAL VARIABLES AND FUNCTIONS
544 594
545=over 4 595=over 4
546 596
… …
630 680
631If it doesn't care, it can just "use AnyEvent" and use it itself, or not 681If 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 682do anything special (it does not need to be event-based) and let AnyEvent
633decide which implementation to chose if some module relies on it. 683decide which implementation to chose if some module relies on it.
634 684
635If the main program relies on a specific event model. For example, in 685If 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 686Gtk2 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 687event module before loading AnyEvent or any module that uses it: generally
638speaking, you should load it as early as possible. The reason is that 688speaking, you should load it as early as possible. The reason is that
639modules might create watchers when they are loaded, and AnyEvent will 689modules 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 690decide 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. 691might chose the wrong one unless you load the correct one yourself.
642 692
643You can chose to use a rather inefficient pure-perl implementation by 693You can chose to use a pure-perl implementation by loading the
644loading the C<AnyEvent::Impl::Perl> module, which gives you similar 694C<AnyEvent::Impl::Perl> module, which gives you similar behaviour
645behaviour everywhere, but letting AnyEvent chose is generally better. 695everywhere, but letting AnyEvent chose the model is generally better.
696
697=head2 MAINLOOP EMULATION
698
699Sometimes (often for short test scripts, or even standalone programs who
700only want to use AnyEvent), you do not want to run a specific event loop.
701
702In that case, you can use a condition variable like this:
703
704 AnyEvent->condvar->recv;
705
706This has the effect of entering the event loop and looping forever.
707
708Note that usually your program has some exit condition, in which case
709it is better to use the "traditional" approach of storing a condition
710variable somewhere, waiting for it, and sending it when the program should
711exit cleanly.
712
646 713
647=head1 OTHER MODULES 714=head1 OTHER MODULES
648 715
649The following is a non-exhaustive list of additional modules that use 716The following is a non-exhaustive list of additional modules that use
650AnyEvent and can therefore be mixed easily with other AnyEvent modules 717AnyEvent and can therefore be mixed easily with other AnyEvent modules
… …
666 733
667Provides various utility functions for (internet protocol) sockets, 734Provides various utility functions for (internet protocol) sockets,
668addresses and name resolution. Also functions to create non-blocking tcp 735addresses and name resolution. Also functions to create non-blocking tcp
669connections or tcp servers, with IPv6 and SRV record support and more. 736connections or tcp servers, with IPv6 and SRV record support and more.
670 737
738=item L<AnyEvent::DNS>
739
740Provides rich asynchronous DNS resolver capabilities.
741
671=item L<AnyEvent::HTTPD> 742=item L<AnyEvent::HTTPD>
672 743
673Provides a simple web application server framework. 744Provides a simple web application server framework.
674
675=item L<AnyEvent::DNS>
676
677Provides rich asynchronous DNS resolver capabilities.
678 745
679=item L<AnyEvent::FastPing> 746=item L<AnyEvent::FastPing>
680 747
681The fastest ping in the west. 748The fastest ping in the west.
682 749
… …
725no warnings; 792no warnings;
726use strict; 793use strict;
727 794
728use Carp; 795use Carp;
729 796
730our $VERSION = '4.03'; 797our $VERSION = '4.05';
731our $MODEL; 798our $MODEL;
732 799
733our $AUTOLOAD; 800our $AUTOLOAD;
734our @ISA; 801our @ISA;
735 802
803our @REGISTRY;
804
805our $WIN32;
806
807BEGIN {
808 my $win32 = ! ! ($^O =~ /mswin32/i);
809 eval "sub WIN32(){ $win32 }";
810}
811
736our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 812our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
737 813
738our @REGISTRY; 814our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
739
740our %PROTOCOL; # (ipv4|ipv6) => (1|2)
741 815
742{ 816{
743 my $idx; 817 my $idx;
744 $PROTOCOL{$_} = ++$idx 818 $PROTOCOL{$_} = ++$idx
819 for reverse split /\s*,\s*/,
745 for split /\s*,\s*/, $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 820 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
746} 821}
747 822
748my @models = ( 823my @models = (
749 [EV:: => AnyEvent::Impl::EV::], 824 [EV:: => AnyEvent::Impl::EV::],
750 [Event:: => AnyEvent::Impl::Event::], 825 [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::], 826 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
755 # everything below here will not be autoprobed as the pureperl backend should work everywhere 827 # everything below here will not be autoprobed
756 [Glib:: => AnyEvent::Impl::Glib::], 828 # as the pureperl backend should work everywhere
829 # and is usually faster
830 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
831 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
757 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 832 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
758 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 833 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
759 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 834 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
835 [Wx:: => AnyEvent::Impl::POE::],
836 [Prima:: => AnyEvent::Impl::POE::],
760); 837);
761 838
762our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 839our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
763 840
764our @post_detect; 841our @post_detect;
765 842
766sub post_detect(&) { 843sub post_detect(&) {
767 my ($cb) = @_; 844 my ($cb) = @_;
… …
784} 861}
785 862
786sub detect() { 863sub detect() {
787 unless ($MODEL) { 864 unless ($MODEL) {
788 no strict 'refs'; 865 no strict 'refs';
866 local $SIG{__DIE__};
789 867
790 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 868 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
791 my $model = "AnyEvent::Impl::$1"; 869 my $model = "AnyEvent::Impl::$1";
792 if (eval "require $model") { 870 if (eval "require $model") {
793 $MODEL = $model; 871 $MODEL = $model;
… …
850 $class->$func (@_); 928 $class->$func (@_);
851} 929}
852 930
853package AnyEvent::Base; 931package AnyEvent::Base;
854 932
933# default implementation for now and time
934
935use Time::HiRes ();
936
937sub time { Time::HiRes::time }
938sub now { Time::HiRes::time }
939
855# default implementation for ->condvar 940# default implementation for ->condvar
856 941
857sub condvar { 942sub condvar {
858 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 943 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
859} 944}
… …
916 or Carp::croak "required option 'pid' is missing"; 1001 or Carp::croak "required option 'pid' is missing";
917 1002
918 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1003 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
919 1004
920 unless ($WNOHANG) { 1005 unless ($WNOHANG) {
921 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 1006 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
922 } 1007 }
923 1008
924 unless ($CHLD_W) { 1009 unless ($CHLD_W) {
925 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1010 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
926 # child could be a zombie already, so make at least one round 1011 # 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 1190some (broken) firewalls drop such DNS packets, which is why it is off by
1106default. 1191default.
1107 1192
1108Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 1193Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1109EDNS0 in its DNS requests. 1194EDNS0 in its DNS requests.
1195
1196=item C<PERL_ANYEVENT_MAX_FORKS>
1197
1198The maximum number of child processes that C<AnyEvent::Util::fork_call>
1199will create in parallel.
1110 1200
1111=back 1201=back
1112 1202
1113=head1 EXAMPLE PROGRAM 1203=head1 EXAMPLE PROGRAM
1114 1204

Diff Legend

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