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.164 by root, Tue Jul 8 19:50:25 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
… …
164 170
165Some event loops issue spurious readyness notifications, so you should 171Some event loops issue spurious readyness notifications, so you should
166always use non-blocking calls when reading/writing from/to your file 172always use non-blocking calls when reading/writing from/to your file
167handles. 173handles.
168 174
169Example:
170
171 # wait for readability of STDIN, then read a line and disable the watcher 175Example: wait for readability of STDIN, then read a line and disable the
176watcher.
177
172 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 178 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
173 chomp (my $input = <STDIN>); 179 chomp (my $input = <STDIN>);
174 warn "read: $input\n"; 180 warn "read: $input\n";
175 undef $w; 181 undef $w;
176 }); 182 });
… …
186 192
187Although the callback might get passed parameters, their value and 193Although the callback might get passed parameters, their value and
188presence is undefined and you cannot rely on them. Portable AnyEvent 194presence is undefined and you cannot rely on them. Portable AnyEvent
189callbacks cannot use arguments passed to time watcher callbacks. 195callbacks cannot use arguments passed to time watcher callbacks.
190 196
191The timer callback will be invoked at most once: if you want a repeating 197The callback will normally be invoked once only. If you specify another
192timer you have to create a new watcher (this is a limitation by both Tk 198parameter, C<interval>, as a positive number, then the callback will be
193and Glib). 199invoked regularly at that interval (in fractional seconds) after the first
200invocation.
194 201
195Example: 202The callback will be rescheduled before invoking the callback, but no
203attempt is done to avoid timer drift in most backends, so the interval is
204only approximate.
196 205
197 # fire an event after 7.7 seconds 206Example: fire an event after 7.7 seconds.
207
198 my $w = AnyEvent->timer (after => 7.7, cb => sub { 208 my $w = AnyEvent->timer (after => 7.7, cb => sub {
199 warn "timeout\n"; 209 warn "timeout\n";
200 }); 210 });
201 211
202 # to cancel the timer: 212 # to cancel the timer:
203 undef $w; 213 undef $w;
204 214
205Example 2:
206
207 # fire an event after 0.5 seconds, then roughly every second 215Example 2: fire an event after 0.5 seconds, then roughly every second.
208 my $w;
209 216
210 my $cb = sub {
211 # cancel the old timer while creating a new one
212 $w = AnyEvent->timer (after => 1, cb => $cb); 217 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
218 warn "timeout\n";
213 }; 219 };
214
215 # start the "loop" by creating the first watcher
216 $w = AnyEvent->timer (after => 0.5, cb => $cb);
217 220
218=head3 TIMING ISSUES 221=head3 TIMING ISSUES
219 222
220There are two ways to handle timers: based on real time (relative, "fire 223There are two ways to handle timers: based on real time (relative, "fire
221in 10 seconds") and based on wallclock time (absolute, "fire at 12 224in 10 seconds") and based on wallclock time (absolute, "fire at 12
… …
232on true relative time) and absolute (ev_periodic, based on wallclock time) 235on true relative time) and absolute (ev_periodic, based on wallclock time)
233timers. 236timers.
234 237
235AnyEvent always prefers relative timers, if available, matching the 238AnyEvent always prefers relative timers, if available, matching the
236AnyEvent API. 239AnyEvent API.
240
241AnyEvent has two additional methods that return the "current time":
242
243=over 4
244
245=item AnyEvent->time
246
247This returns the "current wallclock time" as a fractional number of
248seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
249return, and the result is guaranteed to be compatible with those).
250
251It progresses independently of any event loop processing, i.e. each call
252will check the system clock, which usually gets updated frequently.
253
254=item AnyEvent->now
255
256This also returns the "current wallclock time", but unlike C<time>, above,
257this value might change only once per event loop iteration, depending on
258the event loop (most return the same time as C<time>, above). This is the
259time that AnyEvent's timers get scheduled against.
260
261I<In almost all cases (in all cases if you don't care), this is the
262function to call when you want to know the current time.>
263
264This function is also often faster then C<< AnyEvent->time >>, and
265thus the preferred method if you want some timestamp (for example,
266L<AnyEvent::Handle> uses this to update it's activity timeouts).
267
268The rest of this section is only of relevance if you try to be very exact
269with your timing, you can skip it without bad conscience.
270
271For a practical example of when these times differ, consider L<Event::Lib>
272and L<EV> and the following set-up:
273
274The event loop is running and has just invoked one of your callback at
275time=500 (assume no other callbacks delay processing). In your callback,
276you wait a second by executing C<sleep 1> (blocking the process for a
277second) and then (at time=501) you create a relative timer that fires
278after three seconds.
279
280With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
281both return C<501>, because that is the current time, and the timer will
282be scheduled to fire at time=504 (C<501> + C<3>).
283
284With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
285time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
286last event processing phase started. With L<EV>, your timer gets scheduled
287to run at time=503 (C<500> + C<3>).
288
289In one sense, L<Event::Lib> is more exact, as it uses the current time
290regardless of any delays introduced by event processing. However, most
291callbacks do not expect large delays in processing, so this causes a
292higher drift (and a lot more system calls to get the current time).
293
294In another sense, L<EV> is more exact, as your timer will be scheduled at
295the same time, regardless of how long event processing actually took.
296
297In either case, if you care (and in most cases, you don't), then you
298can get whatever behaviour you want with any event loop, by taking the
299difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
300account.
301
302=back
237 303
238=head2 SIGNAL WATCHERS 304=head2 SIGNAL WATCHERS
239 305
240You can watch for signals using a signal watcher, C<signal> is the signal 306You 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 307I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
… …
283AnyEvent program, you I<have> to create at least one watcher before you 349AnyEvent program, you I<have> to create at least one watcher before you
284C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 350C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
285 351
286Example: fork a process and wait for it 352Example: fork a process and wait for it
287 353
288 my $done = AnyEvent->condvar; 354 my $done = AnyEvent->condvar;
289 355
290 my $pid = fork or exit 5; 356 my $pid = fork or exit 5;
291 357
292 my $w = AnyEvent->child ( 358 my $w = AnyEvent->child (
293 pid => $pid, 359 pid => $pid,
294 cb => sub { 360 cb => sub {
295 my ($pid, $status) = @_; 361 my ($pid, $status) = @_;
296 warn "pid $pid exited with status $status"; 362 warn "pid $pid exited with status $status";
297 $done->send; 363 $done->send;
298 }, 364 },
299 ); 365 );
300 366
301 # do something else, then wait for process exit 367 # do something else, then wait for process exit
302 $done->recv; 368 $done->recv;
303 369
304=head2 CONDITION VARIABLES 370=head2 CONDITION VARIABLES
305 371
306If you are familiar with some event loops you will know that all of them 372If 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 373require you to run some blocking "loop", "run" or similar function that
… …
528 594
529This is a mutator function that returns the callback set and optionally 595This is a mutator function that returns the callback set and optionally
530replaces it before doing so. 596replaces it before doing so.
531 597
532The callback will be called when the condition becomes "true", i.e. when 598The 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 599C<send> or C<croak> are called, with the only argument being the condition
534or at any later time is guaranteed not to block. 600variable itself. Calling C<recv> inside the callback or at any later time
601is guaranteed not to block.
535 602
536=back 603=back
537 604
538=head1 GLOBAL VARIABLES AND FUNCTIONS 605=head1 GLOBAL VARIABLES AND FUNCTIONS
539 606
… …
668=item L<AnyEvent::Util> 735=item L<AnyEvent::Util>
669 736
670Contains various utility functions that replace often-used but blocking 737Contains various utility functions that replace often-used but blocking
671functions such as C<inet_aton> by event-/callback-based versions. 738functions such as C<inet_aton> by event-/callback-based versions.
672 739
673=item L<AnyEvent::Handle>
674
675Provide read and write buffers and manages watchers for reads and writes.
676
677=item L<AnyEvent::Socket> 740=item L<AnyEvent::Socket>
678 741
679Provides various utility functions for (internet protocol) sockets, 742Provides various utility functions for (internet protocol) sockets,
680addresses and name resolution. Also functions to create non-blocking tcp 743addresses and name resolution. Also functions to create non-blocking tcp
681connections or tcp servers, with IPv6 and SRV record support and more. 744connections or tcp servers, with IPv6 and SRV record support and more.
682 745
746=item L<AnyEvent::Handle>
747
748Provide read and write buffers, manages watchers for reads and writes,
749supports raw and formatted I/O, I/O queued and fully transparent and
750non-blocking SSL/TLS.
751
683=item L<AnyEvent::DNS> 752=item L<AnyEvent::DNS>
684 753
685Provides rich asynchronous DNS resolver capabilities. 754Provides rich asynchronous DNS resolver capabilities.
686 755
756=item L<AnyEvent::HTTP>
757
758A simple-to-use HTTP library that is capable of making a lot of concurrent
759HTTP requests.
760
687=item L<AnyEvent::HTTPD> 761=item L<AnyEvent::HTTPD>
688 762
689Provides a simple web application server framework. 763Provides a simple web application server framework.
690 764
691=item L<AnyEvent::FastPing> 765=item L<AnyEvent::FastPing>
692 766
693The fastest ping in the west. 767The fastest ping in the west.
768
769=item L<AnyEvent::DBI>
770
771Executes L<DBI> requests asynchronously in a proxy process.
772
773=item L<AnyEvent::AIO>
774
775Truly asynchronous I/O, should be in the toolbox of every event
776programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
777together.
778
779=item L<AnyEvent::BDB>
780
781Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
782L<BDB> and AnyEvent together.
783
784=item L<AnyEvent::GPSD>
785
786A non-blocking interface to gpsd, a daemon delivering GPS information.
787
788=item L<AnyEvent::IGS>
789
790A non-blocking interface to the Internet Go Server protocol (used by
791L<App::IGS>).
694 792
695=item L<Net::IRC3> 793=item L<Net::IRC3>
696 794
697AnyEvent based IRC client module family. 795AnyEvent based IRC client module family.
698 796
… …
711 809
712=item L<Coro> 810=item L<Coro>
713 811
714Has special support for AnyEvent via L<Coro::AnyEvent>. 812Has special support for AnyEvent via L<Coro::AnyEvent>.
715 813
716=item L<AnyEvent::AIO>, L<IO::AIO>
717
718Truly asynchronous I/O, should be in the toolbox of every event
719programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
720together.
721
722=item L<AnyEvent::BDB>, L<BDB>
723
724Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
725IO::AIO and AnyEvent together.
726
727=item L<IO::Lambda> 814=item L<IO::Lambda>
728 815
729The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 816The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
730 817
731=back 818=back
… …
737no warnings; 824no warnings;
738use strict; 825use strict;
739 826
740use Carp; 827use Carp;
741 828
742our $VERSION = '4.05'; 829our $VERSION = 4.2;
743our $MODEL; 830our $MODEL;
744 831
745our $AUTOLOAD; 832our $AUTOLOAD;
746our @ISA; 833our @ISA;
747 834
… …
779 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 866 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
780 [Wx:: => AnyEvent::Impl::POE::], 867 [Wx:: => AnyEvent::Impl::POE::],
781 [Prima:: => AnyEvent::Impl::POE::], 868 [Prima:: => AnyEvent::Impl::POE::],
782); 869);
783 870
784our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 871our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
785 872
786our @post_detect; 873our @post_detect;
787 874
788sub post_detect(&) { 875sub post_detect(&) {
789 my ($cb) = @_; 876 my ($cb) = @_;
… …
873 $class->$func (@_); 960 $class->$func (@_);
874} 961}
875 962
876package AnyEvent::Base; 963package AnyEvent::Base;
877 964
965# default implementation for now and time
966
967use Time::HiRes ();
968
969sub time { Time::HiRes::time }
970sub now { Time::HiRes::time }
971
878# default implementation for ->condvar 972# default implementation for ->condvar
879 973
880sub condvar { 974sub condvar {
881 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 975 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
882} 976}
… …
902sub AnyEvent::Base::Signal::DESTROY { 996sub AnyEvent::Base::Signal::DESTROY {
903 my ($signal, $cb) = @{$_[0]}; 997 my ($signal, $cb) = @{$_[0]};
904 998
905 delete $SIG_CB{$signal}{$cb}; 999 delete $SIG_CB{$signal}{$cb};
906 1000
907 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} }; 1001 delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
908} 1002}
909 1003
910# default implementation for ->child 1004# default implementation for ->child
911 1005
912our %PID_CB; 1006our %PID_CB;
… …
1096This functionality might change in future versions. 1190This functionality might change in future versions.
1097 1191
1098For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1192For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1099could start your program like this: 1193could start your program like this:
1100 1194
1101 PERL_ANYEVENT_MODEL=Perl perl ... 1195 PERL_ANYEVENT_MODEL=Perl perl ...
1102 1196
1103=item C<PERL_ANYEVENT_PROTOCOLS> 1197=item C<PERL_ANYEVENT_PROTOCOLS>
1104 1198
1105Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences 1199Used 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 1200for IPv4 or IPv6. The default is unspecified (and might change, or be the result
… …
1581specified in the variable. 1675specified in the variable.
1582 1676
1583You can make AnyEvent completely ignore this variable by deleting it 1677You can make AnyEvent completely ignore this variable by deleting it
1584before the first watcher gets created, e.g. with a C<BEGIN> block: 1678before the first watcher gets created, e.g. with a C<BEGIN> block:
1585 1679
1586 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1680 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1587 1681
1588 use AnyEvent; 1682 use AnyEvent;
1589 1683
1590Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1684Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1591be used to probe what backend is used and gain other information (which is 1685be used to probe what backend is used and gain other information (which is
1592probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1686probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1687
1688
1689=head1 BUGS
1690
1691Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
1692to work around. If you suffer from memleaks, first upgrade to Perl 5.10
1693and check wether the leaks still show up. (Perl 5.10.0 has other annoying
1694mamleaks, such as leaking on C<map> and C<grep> but it is usually not as
1695pronounced).
1593 1696
1594 1697
1595=head1 SEE ALSO 1698=head1 SEE ALSO
1596 1699
1597Utility functions: L<AnyEvent::Util>. 1700Utility functions: L<AnyEvent::Util>.
… …
1614Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 1717Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1615 1718
1616 1719
1617=head1 AUTHOR 1720=head1 AUTHOR
1618 1721
1619 Marc Lehmann <schmorp@schmorp.de> 1722 Marc Lehmann <schmorp@schmorp.de>
1620 http://home.schmorp.de/ 1723 http://home.schmorp.de/
1621 1724
1622=cut 1725=cut
1623 1726
16241 17271
1625 1728

Diff Legend

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