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.149 by root, Sat May 31 01:41:22 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
… …
138Many watchers either are used with "recursion" (repeating timers for 138Many watchers either are used with "recursion" (repeating timers for
139example), or need to refer to their watcher object in other ways. 139example), or need to refer to their watcher object in other ways.
140 140
141An any way to achieve that is this pattern: 141An any way to achieve that is this pattern:
142 142
143 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 143 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
144 # you can use $w here, for example to undef it 144 # you can use $w here, for example to undef it
145 undef $w; 145 undef $w;
146 }); 146 });
147 147
148Note 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,
149my variables are only visible after the statement in which they are 149my variables are only visible after the statement in which they are
150declared. 150declared.
151 151
152=head2 I/O WATCHERS 152=head2 I/O WATCHERS
153 153
154You 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
155with the following mandatory key-value pairs as arguments: 155with the following mandatory key-value pairs as arguments:
156 156
157C<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
158for 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>
159which 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
160respectively. 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
161becomes ready. 161callback to invoke each time the file handle becomes ready.
162 162
163Although the callback might get passed parameters, their value and 163Although the callback might get passed parameters, their value and
164presence is undefined and you cannot rely on them. Portable AnyEvent 164presence is undefined and you cannot rely on them. Portable AnyEvent
165callbacks cannot use arguments passed to I/O watcher callbacks. 165callbacks cannot use arguments passed to I/O watcher callbacks.
166 166
… …
170 170
171Some event loops issue spurious readyness notifications, so you should 171Some event loops issue spurious readyness notifications, so you should
172always use non-blocking calls when reading/writing from/to your file 172always use non-blocking calls when reading/writing from/to your file
173handles. 173handles.
174 174
175Example:
176
177 # 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
178 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 178 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
179 chomp (my $input = <STDIN>); 179 chomp (my $input = <STDIN>);
180 warn "read: $input\n"; 180 warn "read: $input\n";
181 undef $w; 181 undef $w;
182 }); 182 });
… …
192 192
193Although the callback might get passed parameters, their value and 193Although the callback might get passed parameters, their value and
194presence is undefined and you cannot rely on them. Portable AnyEvent 194presence is undefined and you cannot rely on them. Portable AnyEvent
195callbacks cannot use arguments passed to time watcher callbacks. 195callbacks cannot use arguments passed to time watcher callbacks.
196 196
197The 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
198timer 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
199and 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.
200 202
201Example: 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.
202 206
203 # fire an event after 7.7 seconds 207Example: fire an event after 7.7 seconds.
208
204 my $w = AnyEvent->timer (after => 7.7, cb => sub { 209 my $w = AnyEvent->timer (after => 7.7, cb => sub {
205 warn "timeout\n"; 210 warn "timeout\n";
206 }); 211 });
207 212
208 # to cancel the timer: 213 # to cancel the timer:
209 undef $w; 214 undef $w;
210 215
211Example 2:
212
213 # fire an event after 0.5 seconds, then roughly every second 216Example 2: fire an event after 0.5 seconds, then roughly every second.
214 my $w;
215 217
216 my $cb = sub {
217 # cancel the old timer while creating a new one
218 $w = AnyEvent->timer (after => 1, cb => $cb); 218 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
219 warn "timeout\n";
219 }; 220 };
220
221 # start the "loop" by creating the first watcher
222 $w = AnyEvent->timer (after => 0.5, cb => $cb);
223 221
224=head3 TIMING ISSUES 222=head3 TIMING ISSUES
225 223
226There 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
227in 10 seconds") and based on wallclock time (absolute, "fire at 12 225in 10 seconds") and based on wallclock time (absolute, "fire at 12
… …
352AnyEvent 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
353C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 351C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
354 352
355Example: fork a process and wait for it 353Example: fork a process and wait for it
356 354
357 my $done = AnyEvent->condvar; 355 my $done = AnyEvent->condvar;
358 356
359 my $pid = fork or exit 5; 357 my $pid = fork or exit 5;
360 358
361 my $w = AnyEvent->child ( 359 my $w = AnyEvent->child (
362 pid => $pid, 360 pid => $pid,
363 cb => sub { 361 cb => sub {
364 my ($pid, $status) = @_; 362 my ($pid, $status) = @_;
365 warn "pid $pid exited with status $status"; 363 warn "pid $pid exited with status $status";
366 $done->send; 364 $done->send;
367 }, 365 },
368 ); 366 );
369 367
370 # do something else, then wait for process exit 368 # do something else, then wait for process exit
371 $done->recv; 369 $done->recv;
372 370
373=head2 CONDITION VARIABLES 371=head2 CONDITION VARIABLES
374 372
375If 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
376require you to run some blocking "loop", "run" or similar function that 374require you to run some blocking "loop", "run" or similar function that
… …
738=item L<AnyEvent::Util> 736=item L<AnyEvent::Util>
739 737
740Contains various utility functions that replace often-used but blocking 738Contains various utility functions that replace often-used but blocking
741functions such as C<inet_aton> by event-/callback-based versions. 739functions such as C<inet_aton> by event-/callback-based versions.
742 740
743=item L<AnyEvent::Handle>
744
745Provide read and write buffers and manages watchers for reads and writes.
746
747=item L<AnyEvent::Socket> 741=item L<AnyEvent::Socket>
748 742
749Provides various utility functions for (internet protocol) sockets, 743Provides various utility functions for (internet protocol) sockets,
750addresses and name resolution. Also functions to create non-blocking tcp 744addresses and name resolution. Also functions to create non-blocking tcp
751connections or tcp servers, with IPv6 and SRV record support and more. 745connections or tcp servers, with IPv6 and SRV record support and more.
752 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
753=item L<AnyEvent::DNS> 753=item L<AnyEvent::DNS>
754 754
755Provides rich asynchronous DNS resolver capabilities. 755Provides rich asynchronous DNS resolver capabilities.
756 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
757=item L<AnyEvent::HTTPD> 762=item L<AnyEvent::HTTPD>
758 763
759Provides a simple web application server framework. 764Provides a simple web application server framework.
760 765
761=item L<AnyEvent::FastPing> 766=item L<AnyEvent::FastPing>
762 767
763The 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>).
764 793
765=item L<Net::IRC3> 794=item L<Net::IRC3>
766 795
767AnyEvent based IRC client module family. 796AnyEvent based IRC client module family.
768 797
… …
781 810
782=item L<Coro> 811=item L<Coro>
783 812
784Has special support for AnyEvent via L<Coro::AnyEvent>. 813Has special support for AnyEvent via L<Coro::AnyEvent>.
785 814
786=item L<AnyEvent::AIO>, L<IO::AIO>
787
788Truly asynchronous I/O, should be in the toolbox of every event
789programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
790together.
791
792=item L<AnyEvent::BDB>, L<BDB>
793
794Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
795IO::AIO and AnyEvent together.
796
797=item L<IO::Lambda> 815=item L<IO::Lambda>
798 816
799The 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.
800 818
801=back 819=back
… …
807no warnings; 825no warnings;
808use strict; 826use strict;
809 827
810use Carp; 828use Carp;
811 829
812our $VERSION = 4.11; 830our $VERSION = 4.2;
813our $MODEL; 831our $MODEL;
814 832
815our $AUTOLOAD; 833our $AUTOLOAD;
816our @ISA; 834our @ISA;
817 835
… …
979sub AnyEvent::Base::Signal::DESTROY { 997sub AnyEvent::Base::Signal::DESTROY {
980 my ($signal, $cb) = @{$_[0]}; 998 my ($signal, $cb) = @{$_[0]};
981 999
982 delete $SIG_CB{$signal}{$cb}; 1000 delete $SIG_CB{$signal}{$cb};
983 1001
984 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} }; 1002 delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
985} 1003}
986 1004
987# default implementation for ->child 1005# default implementation for ->child
988 1006
989our %PID_CB; 1007our %PID_CB;
… …
1173This functionality might change in future versions. 1191This functionality might change in future versions.
1174 1192
1175For 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
1176could start your program like this: 1194could start your program like this:
1177 1195
1178 PERL_ANYEVENT_MODEL=Perl perl ... 1196 PERL_ANYEVENT_MODEL=Perl perl ...
1179 1197
1180=item C<PERL_ANYEVENT_PROTOCOLS> 1198=item C<PERL_ANYEVENT_PROTOCOLS>
1181 1199
1182Used 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
1183for 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
… …
1658specified in the variable. 1676specified in the variable.
1659 1677
1660You can make AnyEvent completely ignore this variable by deleting it 1678You can make AnyEvent completely ignore this variable by deleting it
1661before 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:
1662 1680
1663 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1681 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1664 1682
1665 use AnyEvent; 1683 use AnyEvent;
1666 1684
1667Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1685Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1668be 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
1669probably 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).
1670 1697
1671 1698
1672=head1 SEE ALSO 1699=head1 SEE ALSO
1673 1700
1674Utility functions: L<AnyEvent::Util>. 1701Utility functions: L<AnyEvent::Util>.
… …
1691Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 1718Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1692 1719
1693 1720
1694=head1 AUTHOR 1721=head1 AUTHOR
1695 1722
1696 Marc Lehmann <schmorp@schmorp.de> 1723 Marc Lehmann <schmorp@schmorp.de>
1697 http://home.schmorp.de/ 1724 http://home.schmorp.de/
1698 1725
1699=cut 1726=cut
1700 1727
17011 17281
1702 1729

Diff Legend

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