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

Diff Legend

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