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.142 by root, Tue May 27 02:34:30 2008 UTC vs.
Revision 1.155 by root, Fri Jun 6 07:07:01 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?
… …
132Many watchers either are used with "recursion" (repeating timers for 138Many watchers either are used with "recursion" (repeating timers for
133example), or need to refer to their watcher object in other ways. 139example), or need to refer to their watcher object in other ways.
134 140
135An any way to achieve that is this pattern: 141An any way to achieve that is this pattern:
136 142
137 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 143 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
138 # you can use $w here, for example to undef it 144 # you can use $w here, for example to undef it
139 undef $w; 145 undef $w;
140 }); 146 });
141 147
142Note 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,
143my variables are only visible after the statement in which they are 149my variables are only visible after the statement in which they are
144declared. 150declared.
145 151
… …
233timers. 239timers.
234 240
235AnyEvent always prefers relative timers, if available, matching the 241AnyEvent always prefers relative timers, if available, matching the
236AnyEvent API. 242AnyEvent API.
237 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
238=head2 SIGNAL WATCHERS 307=head2 SIGNAL WATCHERS
239 308
240You 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
241I<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
242be invoked whenever a signal occurs. 311be invoked whenever a signal occurs.
… …
283AnyEvent 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
284C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 353C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
285 354
286Example: fork a process and wait for it 355Example: fork a process and wait for it
287 356
288 my $done = AnyEvent->condvar; 357 my $done = AnyEvent->condvar;
289 358
290 my $pid = fork or exit 5; 359 my $pid = fork or exit 5;
291 360
292 my $w = AnyEvent->child ( 361 my $w = AnyEvent->child (
293 pid => $pid, 362 pid => $pid,
294 cb => sub { 363 cb => sub {
295 my ($pid, $status) = @_; 364 my ($pid, $status) = @_;
296 warn "pid $pid exited with status $status"; 365 warn "pid $pid exited with status $status";
297 $done->send; 366 $done->send;
298 }, 367 },
299 ); 368 );
300 369
301 # do something else, then wait for process exit 370 # do something else, then wait for process exit
302 $done->recv; 371 $done->recv;
303 372
304=head2 CONDITION VARIABLES 373=head2 CONDITION VARIABLES
305 374
306If 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
307require you to run some blocking "loop", "run" or similar function that 376require you to run some blocking "loop", "run" or similar function that
… …
528 597
529This is a mutator function that returns the callback set and optionally 598This is a mutator function that returns the callback set and optionally
530replaces it before doing so. 599replaces it before doing so.
531 600
532The 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
533C<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
534or 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.
535 605
536=back 606=back
537 607
538=head1 GLOBAL VARIABLES AND FUNCTIONS 608=head1 GLOBAL VARIABLES AND FUNCTIONS
539 609
… …
682 752
683=item L<AnyEvent::DNS> 753=item L<AnyEvent::DNS>
684 754
685Provides rich asynchronous DNS resolver capabilities. 755Provides rich asynchronous DNS resolver capabilities.
686 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
687=item L<AnyEvent::HTTPD> 762=item L<AnyEvent::HTTPD>
688 763
689Provides a simple web application server framework. 764Provides a simple web application server framework.
690 765
691=item L<AnyEvent::FastPing> 766=item L<AnyEvent::FastPing>
… …
737no warnings; 812no warnings;
738use strict; 813use strict;
739 814
740use Carp; 815use Carp;
741 816
742our $VERSION = '4.05'; 817our $VERSION = 4.14;
743our $MODEL; 818our $MODEL;
744 819
745our $AUTOLOAD; 820our $AUTOLOAD;
746our @ISA; 821our @ISA;
747 822
… …
779 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 854 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
780 [Wx:: => AnyEvent::Impl::POE::], 855 [Wx:: => AnyEvent::Impl::POE::],
781 [Prima:: => AnyEvent::Impl::POE::], 856 [Prima:: => AnyEvent::Impl::POE::],
782); 857);
783 858
784our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 859our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
785 860
786our @post_detect; 861our @post_detect;
787 862
788sub post_detect(&) { 863sub post_detect(&) {
789 my ($cb) = @_; 864 my ($cb) = @_;
… …
873 $class->$func (@_); 948 $class->$func (@_);
874} 949}
875 950
876package AnyEvent::Base; 951package AnyEvent::Base;
877 952
953# default implementation for now and time
954
955use Time::HiRes ();
956
957sub time { Time::HiRes::time }
958sub now { Time::HiRes::time }
959
878# default implementation for ->condvar 960# default implementation for ->condvar
879 961
880sub condvar { 962sub condvar {
881 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 963 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
882} 964}
… …
1096This functionality might change in future versions. 1178This functionality might change in future versions.
1097 1179
1098For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1180For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1099could start your program like this: 1181could start your program like this:
1100 1182
1101 PERL_ANYEVENT_MODEL=Perl perl ... 1183 PERL_ANYEVENT_MODEL=Perl perl ...
1102 1184
1103=item C<PERL_ANYEVENT_PROTOCOLS> 1185=item C<PERL_ANYEVENT_PROTOCOLS>
1104 1186
1105Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences 1187Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1106for IPv4 or IPv6. The default is unspecified (and might change, or be the result 1188for IPv4 or IPv6. The default is unspecified (and might change, or be the result
… …
1581specified in the variable. 1663specified in the variable.
1582 1664
1583You can make AnyEvent completely ignore this variable by deleting it 1665You can make AnyEvent completely ignore this variable by deleting it
1584before the first watcher gets created, e.g. with a C<BEGIN> block: 1666before the first watcher gets created, e.g. with a C<BEGIN> block:
1585 1667
1586 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1668 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1587 1669
1588 use AnyEvent; 1670 use AnyEvent;
1589 1671
1590Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1672Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1591be used to probe what backend is used and gain other information (which is 1673be used to probe what backend is used and gain other information (which is
1592probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1674probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1593 1675
… …
1614Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 1696Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1615 1697
1616 1698
1617=head1 AUTHOR 1699=head1 AUTHOR
1618 1700
1619 Marc Lehmann <schmorp@schmorp.de> 1701 Marc Lehmann <schmorp@schmorp.de>
1620 http://home.schmorp.de/ 1702 http://home.schmorp.de/
1621 1703
1622=cut 1704=cut
1623 1705
16241 17061
1625 1707

Diff Legend

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