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.144 by root, Thu May 29 00:14:35 2008 UTC vs.
Revision 1.168 by root, Tue Jul 8 23:53:37 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
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 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.
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?
27 33
28Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of 34Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
29policy> and AnyEvent is I<small and efficient>. 35policy> and AnyEvent is I<small and efficient>.
30 36
31First and foremost, I<AnyEvent is not an event model> itself, it only 37First and foremost, I<AnyEvent is not an event model> itself, it only
32interfaces to whatever event model the main program happens to use in a 38interfaces to whatever event model the main program happens to use, in a
33pragmatic way. For event models and certain classes of immortals alike, 39pragmatic way. For event models and certain classes of immortals alike,
34the statement "there can only be one" is a bitter reality: In general, 40the statement "there can only be one" is a bitter reality: In general,
35only one event loop can be active at the same time in a process. AnyEvent 41only one event loop can be active at the same time in a process. AnyEvent
36helps hiding the differences between those event loops. 42cannot change this, but it can hide the differences between those event
43loops.
37 44
38The goal of AnyEvent is to offer module authors the ability to do event 45The goal of AnyEvent is to offer module authors the ability to do event
39programming (waiting for I/O or timer events) without subscribing to a 46programming (waiting for I/O or timer events) without subscribing to a
40religion, a way of living, and most importantly: without forcing your 47religion, a way of living, and most importantly: without forcing your
41module users into the same thing by forcing them to use the same event 48module users into the same thing by forcing them to use the same event
42model you use. 49model you use.
43 50
44For modules like POE or IO::Async (which is a total misnomer as it is 51For modules like POE or IO::Async (which is a total misnomer as it is
45actually doing all I/O I<synchronously>...), using them in your module is 52actually doing all I/O I<synchronously>...), using them in your module is
46like joining a cult: After you joined, you are dependent on them and you 53like joining a cult: After you joined, you are dependent on them and you
47cannot use anything else, as it is simply incompatible to everything that 54cannot use anything else, as they are simply incompatible to everything
48isn't itself. What's worse, all the potential users of your module are 55that isn't them. What's worse, all the potential users of your
49I<also> forced to use the same event loop you use. 56module are I<also> forced to use the same event loop you use.
50 57
51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 58AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
52fine. AnyEvent + Tk works fine etc. etc. but none of these work together 59fine. 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 60with 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, 61your 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 62too. But if your module uses AnyEvent, it works transparently with all
56event models it supports (including stuff like POE and IO::Async, as long 63event models it supports (including stuff like IO::Async, as long as those
57as those use one of the supported event loops. It is trivial to add new 64use one of the supported event loops. It is trivial to add new event loops
58event loops to AnyEvent, too, so it is future-proof). 65to AnyEvent, too, so it is future-proof).
59 66
60In addition to being free of having to use I<the one and only true event 67In addition to being free of having to use I<the one and only true event
61model>, AnyEvent also is free of bloat and policy: with POE or similar 68model>, AnyEvent also is free of bloat and policy: with POE or similar
62modules, you get an enormous amount of code and strict rules you have to 69modules, 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 70follow. AnyEvent, on the other hand, is lean and up to the point, by only
132Many watchers either are used with "recursion" (repeating timers for 139Many watchers either are used with "recursion" (repeating timers for
133example), or need to refer to their watcher object in other ways. 140example), or need to refer to their watcher object in other ways.
134 141
135An any way to achieve that is this pattern: 142An any way to achieve that is this pattern:
136 143
137 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 144 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
138 # you can use $w here, for example to undef it 145 # you can use $w here, for example to undef it
139 undef $w; 146 undef $w;
140 }); 147 });
141 148
142Note that C<my $w; $w => combination. This is necessary because in Perl, 149Note that C<my $w; $w => combination. This is necessary because in Perl,
143my variables are only visible after the statement in which they are 150my variables are only visible after the statement in which they are
144declared. 151declared.
145 152
146=head2 I/O WATCHERS 153=head2 I/O WATCHERS
147 154
148You can create an I/O watcher by calling the C<< AnyEvent->io >> method 155You can create an I/O watcher by calling the C<< AnyEvent->io >> method
149with the following mandatory key-value pairs as arguments: 156with the following mandatory key-value pairs as arguments:
150 157
151C<fh> the Perl I<file handle> (I<not> file descriptor) to watch 158C<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>, 159(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, 160must 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 161waiting for "r"eadable or "w"ritable events, respectively. C<cb> is the
155becomes ready. 162callback to invoke each time the file handle becomes ready.
156 163
157Although the callback might get passed parameters, their value and 164Although the callback might get passed parameters, their value and
158presence is undefined and you cannot rely on them. Portable AnyEvent 165presence is undefined and you cannot rely on them. Portable AnyEvent
159callbacks cannot use arguments passed to I/O watcher callbacks. 166callbacks cannot use arguments passed to I/O watcher callbacks.
160 167
164 171
165Some event loops issue spurious readyness notifications, so you should 172Some event loops issue spurious readyness notifications, so you should
166always use non-blocking calls when reading/writing from/to your file 173always use non-blocking calls when reading/writing from/to your file
167handles. 174handles.
168 175
169Example:
170
171 # wait for readability of STDIN, then read a line and disable the watcher 176Example: wait for readability of STDIN, then read a line and disable the
177watcher.
178
172 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 179 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
173 chomp (my $input = <STDIN>); 180 chomp (my $input = <STDIN>);
174 warn "read: $input\n"; 181 warn "read: $input\n";
175 undef $w; 182 undef $w;
176 }); 183 });
186 193
187Although the callback might get passed parameters, their value and 194Although the callback might get passed parameters, their value and
188presence is undefined and you cannot rely on them. Portable AnyEvent 195presence is undefined and you cannot rely on them. Portable AnyEvent
189callbacks cannot use arguments passed to time watcher callbacks. 196callbacks cannot use arguments passed to time watcher callbacks.
190 197
191The timer callback will be invoked at most once: if you want a repeating 198The 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 199parameter, C<interval>, as a strictly positive number (> 0), then the
193and Glib). 200callback will be invoked regularly at that interval (in fractional
201seconds) after the first invocation. If C<interval> is specified with a
202false value, then it is treated as if it were missing.
194 203
195Example: 204The callback will be rescheduled before invoking the callback, but no
205attempt is done to avoid timer drift in most backends, so the interval is
206only approximate.
196 207
197 # fire an event after 7.7 seconds 208Example: fire an event after 7.7 seconds.
209
198 my $w = AnyEvent->timer (after => 7.7, cb => sub { 210 my $w = AnyEvent->timer (after => 7.7, cb => sub {
199 warn "timeout\n"; 211 warn "timeout\n";
200 }); 212 });
201 213
202 # to cancel the timer: 214 # to cancel the timer:
203 undef $w; 215 undef $w;
204 216
205Example 2:
206
207 # fire an event after 0.5 seconds, then roughly every second 217Example 2: fire an event after 0.5 seconds, then roughly every second.
208 my $w;
209 218
210 my $cb = sub {
211 # cancel the old timer while creating a new one
212 $w = AnyEvent->timer (after => 1, cb => $cb); 219 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
220 warn "timeout\n";
213 }; 221 };
214
215 # start the "loop" by creating the first watcher
216 $w = AnyEvent->timer (after => 0.5, cb => $cb);
217 222
218=head3 TIMING ISSUES 223=head3 TIMING ISSUES
219 224
220There are two ways to handle timers: based on real time (relative, "fire 225There are two ways to handle timers: based on real time (relative, "fire
221in 10 seconds") and based on wallclock time (absolute, "fire at 12 226in 10 seconds") and based on wallclock time (absolute, "fire at 12
299=back 304=back
300 305
301=head2 SIGNAL WATCHERS 306=head2 SIGNAL WATCHERS
302 307
303You can watch for signals using a signal watcher, C<signal> is the signal 308You can watch for signals using a signal watcher, C<signal> is the signal
304I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 309I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
305be invoked whenever a signal occurs. 310callback to be invoked whenever a signal occurs.
306 311
307Although the callback might get passed parameters, their value and 312Although the callback might get passed parameters, their value and
308presence is undefined and you cannot rely on them. Portable AnyEvent 313presence is undefined and you cannot rely on them. Portable AnyEvent
309callbacks cannot use arguments passed to signal watcher callbacks. 314callbacks cannot use arguments passed to signal watcher callbacks.
310 315
346AnyEvent program, you I<have> to create at least one watcher before you 351AnyEvent program, you I<have> to create at least one watcher before you
347C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 352C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
348 353
349Example: fork a process and wait for it 354Example: fork a process and wait for it
350 355
351 my $done = AnyEvent->condvar; 356 my $done = AnyEvent->condvar;
352 357
353 my $pid = fork or exit 5; 358 my $pid = fork or exit 5;
354 359
355 my $w = AnyEvent->child ( 360 my $w = AnyEvent->child (
356 pid => $pid, 361 pid => $pid,
357 cb => sub { 362 cb => sub {
358 my ($pid, $status) = @_; 363 my ($pid, $status) = @_;
359 warn "pid $pid exited with status $status"; 364 warn "pid $pid exited with status $status";
360 $done->send; 365 $done->send;
361 }, 366 },
362 ); 367 );
363 368
364 # do something else, then wait for process exit 369 # do something else, then wait for process exit
365 $done->recv; 370 $done->recv;
366 371
367=head2 CONDITION VARIABLES 372=head2 CONDITION VARIABLES
368 373
369If you are familiar with some event loops you will know that all of them 374If you are familiar with some event loops you will know that all of them
370require you to run some blocking "loop", "run" or similar function that 375require you to run some blocking "loop", "run" or similar function that
591 596
592This is a mutator function that returns the callback set and optionally 597This is a mutator function that returns the callback set and optionally
593replaces it before doing so. 598replaces it before doing so.
594 599
595The callback will be called when the condition becomes "true", i.e. when 600The callback will be called when the condition becomes "true", i.e. when
596C<send> or C<croak> are called. Calling C<recv> inside the callback 601C<send> or C<croak> are called, with the only argument being the condition
597or at any later time is guaranteed not to block. 602variable itself. Calling C<recv> inside the callback or at any later time
603is guaranteed not to block.
598 604
599=back 605=back
600 606
601=head1 GLOBAL VARIABLES AND FUNCTIONS 607=head1 GLOBAL VARIABLES AND FUNCTIONS
602 608
731=item L<AnyEvent::Util> 737=item L<AnyEvent::Util>
732 738
733Contains various utility functions that replace often-used but blocking 739Contains various utility functions that replace often-used but blocking
734functions such as C<inet_aton> by event-/callback-based versions. 740functions such as C<inet_aton> by event-/callback-based versions.
735 741
736=item L<AnyEvent::Handle>
737
738Provide read and write buffers and manages watchers for reads and writes.
739
740=item L<AnyEvent::Socket> 742=item L<AnyEvent::Socket>
741 743
742Provides various utility functions for (internet protocol) sockets, 744Provides various utility functions for (internet protocol) sockets,
743addresses and name resolution. Also functions to create non-blocking tcp 745addresses and name resolution. Also functions to create non-blocking tcp
744connections or tcp servers, with IPv6 and SRV record support and more. 746connections or tcp servers, with IPv6 and SRV record support and more.
745 747
748=item L<AnyEvent::Handle>
749
750Provide read and write buffers, manages watchers for reads and writes,
751supports raw and formatted I/O, I/O queued and fully transparent and
752non-blocking SSL/TLS.
753
746=item L<AnyEvent::DNS> 754=item L<AnyEvent::DNS>
747 755
748Provides rich asynchronous DNS resolver capabilities. 756Provides rich asynchronous DNS resolver capabilities.
749 757
758=item L<AnyEvent::HTTP>
759
760A simple-to-use HTTP library that is capable of making a lot of concurrent
761HTTP requests.
762
750=item L<AnyEvent::HTTPD> 763=item L<AnyEvent::HTTPD>
751 764
752Provides a simple web application server framework. 765Provides a simple web application server framework.
753 766
754=item L<AnyEvent::FastPing> 767=item L<AnyEvent::FastPing>
755 768
756The fastest ping in the west. 769The fastest ping in the west.
770
771=item L<AnyEvent::DBI>
772
773Executes L<DBI> requests asynchronously in a proxy process.
774
775=item L<AnyEvent::AIO>
776
777Truly asynchronous I/O, should be in the toolbox of every event
778programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
779together.
780
781=item L<AnyEvent::BDB>
782
783Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
784L<BDB> and AnyEvent together.
785
786=item L<AnyEvent::GPSD>
787
788A non-blocking interface to gpsd, a daemon delivering GPS information.
789
790=item L<AnyEvent::IGS>
791
792A non-blocking interface to the Internet Go Server protocol (used by
793L<App::IGS>).
757 794
758=item L<Net::IRC3> 795=item L<Net::IRC3>
759 796
760AnyEvent based IRC client module family. 797AnyEvent based IRC client module family.
761 798
774 811
775=item L<Coro> 812=item L<Coro>
776 813
777Has special support for AnyEvent via L<Coro::AnyEvent>. 814Has special support for AnyEvent via L<Coro::AnyEvent>.
778 815
779=item L<AnyEvent::AIO>, L<IO::AIO>
780
781Truly asynchronous I/O, should be in the toolbox of every event
782programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
783together.
784
785=item L<AnyEvent::BDB>, L<BDB>
786
787Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
788IO::AIO and AnyEvent together.
789
790=item L<IO::Lambda> 816=item L<IO::Lambda>
791 817
792The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 818The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
793 819
794=back 820=back
800no warnings; 826no warnings;
801use strict; 827use strict;
802 828
803use Carp; 829use Carp;
804 830
805our $VERSION = '4.05'; 831our $VERSION = 4.2;
806our $MODEL; 832our $MODEL;
807 833
808our $AUTOLOAD; 834our $AUTOLOAD;
809our @ISA; 835our @ISA;
810 836
913 $MODEL 939 $MODEL
914 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib."; 940 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.";
915 } 941 }
916 } 942 }
917 943
944 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
945
918 unshift @ISA, $MODEL; 946 unshift @ISA, $MODEL;
919 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 947
948 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
920 949
921 (shift @post_detect)->() while @post_detect; 950 (shift @post_detect)->() while @post_detect;
922 } 951 }
923 952
924 $MODEL 953 $MODEL
972sub AnyEvent::Base::Signal::DESTROY { 1001sub AnyEvent::Base::Signal::DESTROY {
973 my ($signal, $cb) = @{$_[0]}; 1002 my ($signal, $cb) = @{$_[0]};
974 1003
975 delete $SIG_CB{$signal}{$cb}; 1004 delete $SIG_CB{$signal}{$cb};
976 1005
977 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} }; 1006 delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
978} 1007}
979 1008
980# default implementation for ->child 1009# default implementation for ->child
981 1010
982our %PID_CB; 1011our %PID_CB;
1152C<PERL_ANYEVENT_MODEL>. 1181C<PERL_ANYEVENT_MODEL>.
1153 1182
1154When set to C<2> or higher, cause AnyEvent to report to STDERR which event 1183When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1155model it chooses. 1184model it chooses.
1156 1185
1186=item C<PERL_ANYEVENT_STRICT>
1187
1188AnyEvent does not do much argument checking by default, as thorough
1189argument checking is very costly. Setting this variable to a true value
1190will cause AnyEvent to thoroughly check the arguments passed to most
1191method calls and croaks if it finds any problems. In other words, enables
1192"strict" mode. Unlike C<use strict> it is definitely recommended ot keep
1193it off in production.
1194
1157=item C<PERL_ANYEVENT_MODEL> 1195=item C<PERL_ANYEVENT_MODEL>
1158 1196
1159This can be used to specify the event model to be used by AnyEvent, before 1197This can be used to specify the event model to be used by AnyEvent, before
1160auto detection and -probing kicks in. It must be a string consisting 1198auto detection and -probing kicks in. It must be a string consisting
1161entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 1199entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1166This functionality might change in future versions. 1204This functionality might change in future versions.
1167 1205
1168For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1206For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1169could start your program like this: 1207could start your program like this:
1170 1208
1171 PERL_ANYEVENT_MODEL=Perl perl ... 1209 PERL_ANYEVENT_MODEL=Perl perl ...
1172 1210
1173=item C<PERL_ANYEVENT_PROTOCOLS> 1211=item C<PERL_ANYEVENT_PROTOCOLS>
1174 1212
1175Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences 1213Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1176for IPv4 or IPv6. The default is unspecified (and might change, or be the result 1214for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1651specified in the variable. 1689specified in the variable.
1652 1690
1653You can make AnyEvent completely ignore this variable by deleting it 1691You can make AnyEvent completely ignore this variable by deleting it
1654before the first watcher gets created, e.g. with a C<BEGIN> block: 1692before the first watcher gets created, e.g. with a C<BEGIN> block:
1655 1693
1656 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1694 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1657 1695
1658 use AnyEvent; 1696 use AnyEvent;
1659 1697
1660Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1698Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1661be used to probe what backend is used and gain other information (which is 1699be used to probe what backend is used and gain other information (which is
1662probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1700probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and
1701$ENV{PERL_ANYEGENT_STRICT}.
1702
1703
1704=head1 BUGS
1705
1706Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
1707to work around. If you suffer from memleaks, first upgrade to Perl 5.10
1708and check wether the leaks still show up. (Perl 5.10.0 has other annoying
1709mamleaks, such as leaking on C<map> and C<grep> but it is usually not as
1710pronounced).
1663 1711
1664 1712
1665=head1 SEE ALSO 1713=head1 SEE ALSO
1666 1714
1667Utility functions: L<AnyEvent::Util>. 1715Utility functions: L<AnyEvent::Util>.
1684Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 1732Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1685 1733
1686 1734
1687=head1 AUTHOR 1735=head1 AUTHOR
1688 1736
1689 Marc Lehmann <schmorp@schmorp.de> 1737 Marc Lehmann <schmorp@schmorp.de>
1690 http://home.schmorp.de/ 1738 http://home.schmorp.de/
1691 1739
1692=cut 1740=cut
1693 1741
16941 17421
1695 1743

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines