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.136 by root, Sun May 25 23:52:02 2008 UTC vs.
Revision 1.149 by root, Sat May 31 01:41:22 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
… …
522 597
523This is a mutator function that returns the callback set and optionally 598This is a mutator function that returns the callback set and optionally
524replaces it before doing so. 599replaces it before doing so.
525 600
526The 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
527C<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
528or 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.
529 605
530=back 606=back
531 607
532=head1 GLOBAL VARIABLES AND FUNCTIONS 608=head1 GLOBAL VARIABLES AND FUNCTIONS
533 609
… …
731no warnings; 807no warnings;
732use strict; 808use strict;
733 809
734use Carp; 810use Carp;
735 811
736our $VERSION = '4.03'; 812our $VERSION = 4.11;
737our $MODEL; 813our $MODEL;
738 814
739our $AUTOLOAD; 815our $AUTOLOAD;
740our @ISA; 816our @ISA;
741 817
742our @REGISTRY; 818our @REGISTRY;
819
820our $WIN32;
821
822BEGIN {
823 my $win32 = ! ! ($^O =~ /mswin32/i);
824 eval "sub WIN32(){ $win32 }";
825}
743 826
744our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 827our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
745 828
746our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 829our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
747 830
… …
766 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 849 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
767 [Wx:: => AnyEvent::Impl::POE::], 850 [Wx:: => AnyEvent::Impl::POE::],
768 [Prima:: => AnyEvent::Impl::POE::], 851 [Prima:: => AnyEvent::Impl::POE::],
769); 852);
770 853
771our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 854our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
772 855
773our @post_detect; 856our @post_detect;
774 857
775sub post_detect(&) { 858sub post_detect(&) {
776 my ($cb) = @_; 859 my ($cb) = @_;
… …
793} 876}
794 877
795sub detect() { 878sub detect() {
796 unless ($MODEL) { 879 unless ($MODEL) {
797 no strict 'refs'; 880 no strict 'refs';
881 local $SIG{__DIE__};
798 882
799 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 883 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
800 my $model = "AnyEvent::Impl::$1"; 884 my $model = "AnyEvent::Impl::$1";
801 if (eval "require $model") { 885 if (eval "require $model") {
802 $MODEL = $model; 886 $MODEL = $model;
… …
859 $class->$func (@_); 943 $class->$func (@_);
860} 944}
861 945
862package AnyEvent::Base; 946package AnyEvent::Base;
863 947
948# default implementation for now and time
949
950use Time::HiRes ();
951
952sub time { Time::HiRes::time }
953sub now { Time::HiRes::time }
954
864# default implementation for ->condvar 955# default implementation for ->condvar
865 956
866sub condvar { 957sub condvar {
867 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 958 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
868} 959}
… …
925 or Carp::croak "required option 'pid' is missing"; 1016 or Carp::croak "required option 'pid' is missing";
926 1017
927 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1018 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
928 1019
929 unless ($WNOHANG) { 1020 unless ($WNOHANG) {
930 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 1021 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
931 } 1022 }
932 1023
933 unless ($CHLD_W) { 1024 unless ($CHLD_W) {
934 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1025 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
935 # child could be a zombie already, so make at least one round 1026 # child could be a zombie already, so make at least one round
… …
1114some (broken) firewalls drop such DNS packets, which is why it is off by 1205some (broken) firewalls drop such DNS packets, which is why it is off by
1115default. 1206default.
1116 1207
1117Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 1208Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1118EDNS0 in its DNS requests. 1209EDNS0 in its DNS requests.
1210
1211=item C<PERL_ANYEVENT_MAX_FORKS>
1212
1213The maximum number of child processes that C<AnyEvent::Util::fork_call>
1214will create in parallel.
1119 1215
1120=back 1216=back
1121 1217
1122=head1 EXAMPLE PROGRAM 1218=head1 EXAMPLE PROGRAM
1123 1219

Diff Legend

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