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.134 by root, Sun May 25 04:44:04 2008 UTC vs.
Revision 1.160 by root, Sun Jun 22 12:17:47 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, 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
… …
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
… …
126Many watchers either are used with "recursion" (repeating timers for 138Many watchers either are used with "recursion" (repeating timers for
127example), or need to refer to their watcher object in other ways. 139example), or need to refer to their watcher object in other ways.
128 140
129An any way to achieve that is this pattern: 141An any way to achieve that is this pattern:
130 142
131 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 143 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
132 # you can use $w here, for example to undef it 144 # you can use $w here, for example to undef it
133 undef $w; 145 undef $w;
134 }); 146 });
135 147
136Note that C<my $w; $w => combination. This is necessary because in Perl, 148Note that C<my $w; $w => combination. This is necessary because in Perl,
137my variables are only visible after the statement in which they are 149my variables are only visible after the statement in which they are
138declared. 150declared.
139 151
… …
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.
231 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
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
236be invoked whenever a signal occurs. 311be invoked whenever a signal occurs.
… …
277AnyEvent program, you I<have> to create at least one watcher before you 352AnyEvent program, you I<have> to create at least one watcher before you
278C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 353C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
279 354
280Example: fork a process and wait for it 355Example: fork a process and wait for it
281 356
282 my $done = AnyEvent->condvar; 357 my $done = AnyEvent->condvar;
283 358
284 my $pid = fork or exit 5; 359 my $pid = fork or exit 5;
285 360
286 my $w = AnyEvent->child ( 361 my $w = AnyEvent->child (
287 pid => $pid, 362 pid => $pid,
288 cb => sub { 363 cb => sub {
289 my ($pid, $status) = @_; 364 my ($pid, $status) = @_;
290 warn "pid $pid exited with status $status"; 365 warn "pid $pid exited with status $status";
291 $done->send; 366 $done->send;
292 }, 367 },
293 ); 368 );
294 369
295 # do something else, then wait for process exit 370 # do something else, then wait for process exit
296 $done->recv; 371 $done->recv;
297 372
298=head2 CONDITION VARIABLES 373=head2 CONDITION VARIABLES
299 374
300If you are familiar with some event loops you will know that all of them 375If you are familiar with some event loops you will know that all of them
301require you to run some blocking "loop", "run" or similar function that 376require you to run some blocking "loop", "run" or similar function that
… …
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.
… …
515 597
516This is a mutator function that returns the callback set and optionally 598This is a mutator function that returns the callback set and optionally
517replaces it before doing so. 599replaces it before doing so.
518 600
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, with the only argument being the condition
521or at any later time is guaranteed not to block. 603variable itself. Calling C<recv> inside the callback or at any later time
604is guaranteed not to block.
522 605
523=back 606=back
524 607
525=head1 GLOBAL VARIABLES AND FUNCTIONS 608=head1 GLOBAL VARIABLES AND FUNCTIONS
526 609
… …
669 752
670=item L<AnyEvent::DNS> 753=item L<AnyEvent::DNS>
671 754
672Provides rich asynchronous DNS resolver capabilities. 755Provides rich asynchronous DNS resolver capabilities.
673 756
757=item L<AnyEvent::HTTP>
758
759A simple-to-use HTTP library that is capable of making a lot of concurrent
760HTTP requests.
761
674=item L<AnyEvent::HTTPD> 762=item L<AnyEvent::HTTPD>
675 763
676Provides a simple web application server framework. 764Provides a simple web application server framework.
677 765
678=item L<AnyEvent::FastPing> 766=item L<AnyEvent::FastPing>
679 767
680The fastest ping in the west. 768The fastest ping in the west.
769
770=item L<AnyEvent::DBI>
771
772Executes DBI requests asynchronously in a proxy process.
681 773
682=item L<Net::IRC3> 774=item L<Net::IRC3>
683 775
684AnyEvent based IRC client module family. 776AnyEvent based IRC client module family.
685 777
… …
724no warnings; 816no warnings;
725use strict; 817use strict;
726 818
727use Carp; 819use Carp;
728 820
729our $VERSION = '4.03'; 821our $VERSION = 4.152;
730our $MODEL; 822our $MODEL;
731 823
732our $AUTOLOAD; 824our $AUTOLOAD;
733our @ISA; 825our @ISA;
734 826
827our @REGISTRY;
828
829our $WIN32;
830
831BEGIN {
832 my $win32 = ! ! ($^O =~ /mswin32/i);
833 eval "sub WIN32(){ $win32 }";
834}
835
735our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 836our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
736 837
737our @REGISTRY; 838our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
738
739our %PROTOCOL; # (ipv4|ipv6) => (1|2)
740 839
741{ 840{
742 my $idx; 841 my $idx;
743 $PROTOCOL{$_} = ++$idx 842 $PROTOCOL{$_} = ++$idx
843 for reverse split /\s*,\s*/,
744 for split /\s*,\s*/, $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 844 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
745} 845}
746 846
747my @models = ( 847my @models = (
748 [EV:: => AnyEvent::Impl::EV::], 848 [EV:: => AnyEvent::Impl::EV::],
749 [Event:: => AnyEvent::Impl::Event::], 849 [Event:: => AnyEvent::Impl::Event::],
750 [Tk:: => AnyEvent::Impl::Tk::],
751 [Wx:: => AnyEvent::Impl::POE::],
752 [Prima:: => AnyEvent::Impl::POE::],
753 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 850 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
754 # everything below here will not be autoprobed as the pureperl backend should work everywhere 851 # everything below here will not be autoprobed
755 [Glib:: => AnyEvent::Impl::Glib::], 852 # as the pureperl backend should work everywhere
853 # and is usually faster
854 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
855 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
756 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 856 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
757 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 857 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
758 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 858 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
859 [Wx:: => AnyEvent::Impl::POE::],
860 [Prima:: => AnyEvent::Impl::POE::],
759); 861);
760 862
761our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 863our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
762 864
763our @post_detect; 865our @post_detect;
764 866
765sub post_detect(&) { 867sub post_detect(&) {
766 my ($cb) = @_; 868 my ($cb) = @_;
… …
783} 885}
784 886
785sub detect() { 887sub detect() {
786 unless ($MODEL) { 888 unless ($MODEL) {
787 no strict 'refs'; 889 no strict 'refs';
890 local $SIG{__DIE__};
788 891
789 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 892 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
790 my $model = "AnyEvent::Impl::$1"; 893 my $model = "AnyEvent::Impl::$1";
791 if (eval "require $model") { 894 if (eval "require $model") {
792 $MODEL = $model; 895 $MODEL = $model;
… …
849 $class->$func (@_); 952 $class->$func (@_);
850} 953}
851 954
852package AnyEvent::Base; 955package AnyEvent::Base;
853 956
957# default implementation for now and time
958
959use Time::HiRes ();
960
961sub time { Time::HiRes::time }
962sub now { Time::HiRes::time }
963
854# default implementation for ->condvar 964# default implementation for ->condvar
855 965
856sub condvar { 966sub condvar {
857 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 967 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
858} 968}
… …
915 or Carp::croak "required option 'pid' is missing"; 1025 or Carp::croak "required option 'pid' is missing";
916 1026
917 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1027 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
918 1028
919 unless ($WNOHANG) { 1029 unless ($WNOHANG) {
920 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 1030 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
921 } 1031 }
922 1032
923 unless ($CHLD_W) { 1033 unless ($CHLD_W) {
924 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1034 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
925 # child could be a zombie already, so make at least one round 1035 # child could be a zombie already, so make at least one round
… …
1072This functionality might change in future versions. 1182This functionality might change in future versions.
1073 1183
1074For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1184For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1075could start your program like this: 1185could start your program like this:
1076 1186
1077 PERL_ANYEVENT_MODEL=Perl perl ... 1187 PERL_ANYEVENT_MODEL=Perl perl ...
1078 1188
1079=item C<PERL_ANYEVENT_PROTOCOLS> 1189=item C<PERL_ANYEVENT_PROTOCOLS>
1080 1190
1081Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences 1191Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1082for IPv4 or IPv6. The default is unspecified (and might change, or be the result 1192for IPv4 or IPv6. The default is unspecified (and might change, or be the result
… …
1104some (broken) firewalls drop such DNS packets, which is why it is off by 1214some (broken) firewalls drop such DNS packets, which is why it is off by
1105default. 1215default.
1106 1216
1107Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 1217Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1108EDNS0 in its DNS requests. 1218EDNS0 in its DNS requests.
1219
1220=item C<PERL_ANYEVENT_MAX_FORKS>
1221
1222The maximum number of child processes that C<AnyEvent::Util::fork_call>
1223will create in parallel.
1109 1224
1110=back 1225=back
1111 1226
1112=head1 EXAMPLE PROGRAM 1227=head1 EXAMPLE PROGRAM
1113 1228
… …
1552specified in the variable. 1667specified in the variable.
1553 1668
1554You can make AnyEvent completely ignore this variable by deleting it 1669You can make AnyEvent completely ignore this variable by deleting it
1555before the first watcher gets created, e.g. with a C<BEGIN> block: 1670before the first watcher gets created, e.g. with a C<BEGIN> block:
1556 1671
1557 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1672 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1558 1673
1559 use AnyEvent; 1674 use AnyEvent;
1560 1675
1561Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1676Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1562be used to probe what backend is used and gain other information (which is 1677be used to probe what backend is used and gain other information (which is
1563probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1678probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1679
1680
1681=head1 BUGS
1682
1683Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
1684to work around. If you suffer from memleaks, first upgrade to Perl 5.10
1685and check wether the leaks still show up. (Perl 5.10.0 has other annoying
1686mamleaks, such as leaking on C<map> and C<grep> but it is usually not as
1687pronounced).
1564 1688
1565 1689
1566=head1 SEE ALSO 1690=head1 SEE ALSO
1567 1691
1568Utility functions: L<AnyEvent::Util>. 1692Utility functions: L<AnyEvent::Util>.
… …
1585Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 1709Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1586 1710
1587 1711
1588=head1 AUTHOR 1712=head1 AUTHOR
1589 1713
1590 Marc Lehmann <schmorp@schmorp.de> 1714 Marc Lehmann <schmorp@schmorp.de>
1591 http://home.schmorp.de/ 1715 http://home.schmorp.de/
1592 1716
1593=cut 1717=cut
1594 1718
15951 17191
1596 1720

Diff Legend

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