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.173 by root, Mon Jul 21 03:47:22 2008 UTC vs.
Revision 1.197 by root, Thu Mar 26 15:51:44 2009 UTC

137These watchers are normal Perl objects with normal Perl lifetime. After 137These watchers are normal Perl objects with normal Perl lifetime. After
138creating a watcher it will immediately "watch" for events and invoke the 138creating a watcher it will immediately "watch" for events and invoke the
139callback when the event occurs (of course, only when the event model 139callback when the event occurs (of course, only when the event model
140is in control). 140is in control).
141 141
142Note that B<callbacks must not permanently change global variables>
143potentially in use by the event loop (such as C<$_> or C<$[>) and that B<<
144callbacks must not C<die> >>. The former is good programming practise in
145Perl and the latter stems from the fact that exception handling differs
146widely between event loops.
147
142To disable the watcher you have to destroy it (e.g. by setting the 148To disable the watcher you have to destroy it (e.g. by setting the
143variable you store it in to C<undef> or otherwise deleting all references 149variable you store it in to C<undef> or otherwise deleting all references
144to it). 150to it).
145 151
146All watchers are created by calling a method on the C<AnyEvent> class. 152All watchers are created by calling a method on the C<AnyEvent> class.
340=head2 CHILD PROCESS WATCHERS 346=head2 CHILD PROCESS WATCHERS
341 347
342You can also watch on a child process exit and catch its exit status. 348You can also watch on a child process exit and catch its exit status.
343 349
344The child process is specified by the C<pid> argument (if set to C<0>, it 350The child process is specified by the C<pid> argument (if set to C<0>, it
345watches for any child process exit). The watcher will trigger as often 351watches for any child process exit). The watcher will triggered only when
346as status change for the child are received. This works by installing a 352the child process has finished and an exit status is available, not on
347signal handler for C<SIGCHLD>. The callback will be called with the pid 353any trace events (stopped/continued).
348and exit status (as returned by waitpid), so unlike other watcher types, 354
349you I<can> rely on child watcher callback arguments. 355The callback will be called with the pid and exit status (as returned by
356waitpid), so unlike other watcher types, you I<can> rely on child watcher
357callback arguments.
358
359This watcher type works by installing a signal handler for C<SIGCHLD>,
360and since it cannot be shared, nothing else should use SIGCHLD or reap
361random child processes (waiting for specific child processes, e.g. inside
362C<system>, is just fine).
350 363
351There is a slight catch to child watchers, however: you usually start them 364There is a slight catch to child watchers, however: you usually start them
352I<after> the child process was created, and this means the process could 365I<after> the child process was created, and this means the process could
353have exited already (and no SIGCHLD will be sent anymore). 366have exited already (and no SIGCHLD will be sent anymore).
354 367
389 402
390The instrument to do that is called a "condition variable", so called 403The instrument to do that is called a "condition variable", so called
391because they represent a condition that must become true. 404because they represent a condition that must become true.
392 405
393Condition variables can be created by calling the C<< AnyEvent->condvar 406Condition variables can be created by calling the C<< AnyEvent->condvar
394
395>> method, usually without arguments. The only argument pair allowed is 407>> method, usually without arguments. The only argument pair allowed is
396 408
397C<cb>, which specifies a callback to be called when the condition variable 409C<cb>, which specifies a callback to be called when the condition variable
398becomes true, with the condition variable as the first argument (but not 410becomes true, with the condition variable as the first argument (but not
399the results). 411the results).
819=item L<AnyEvent::IGS> 831=item L<AnyEvent::IGS>
820 832
821A non-blocking interface to the Internet Go Server protocol (used by 833A non-blocking interface to the Internet Go Server protocol (used by
822L<App::IGS>). 834L<App::IGS>).
823 835
824=item L<Net::IRC3> 836=item L<AnyEvent::IRC>
825 837
826AnyEvent based IRC client module family. 838AnyEvent based IRC client module family (replacing the older Net::IRC3).
827 839
828=item L<Net::XMPP2> 840=item L<Net::XMPP2>
829 841
830AnyEvent based XMPP (Jabber protocol) module family. 842AnyEvent based XMPP (Jabber protocol) module family.
831 843
851=cut 863=cut
852 864
853package AnyEvent; 865package AnyEvent;
854 866
855no warnings; 867no warnings;
856use strict; 868use strict qw(vars subs);
857 869
858use Carp; 870use Carp;
859 871
860our $VERSION = 4.22; 872our $VERSION = 4.341;
861our $MODEL; 873our $MODEL;
862 874
863our $AUTOLOAD; 875our $AUTOLOAD;
864our @ISA; 876our @ISA;
865 877
998# to support binding more than one watcher per filehandle (they usually 1010# to support binding more than one watcher per filehandle (they usually
999# allow only one watcher per fd, so we dup it to get a different one). 1011# allow only one watcher per fd, so we dup it to get a different one).
1000sub _dupfh($$$$) { 1012sub _dupfh($$$$) {
1001 my ($poll, $fh, $r, $w) = @_; 1013 my ($poll, $fh, $r, $w) = @_;
1002 1014
1003 require Fcntl;
1004
1005 # cygwin requires the fh mode to be matching, unix doesn't 1015 # cygwin requires the fh mode to be matching, unix doesn't
1006 my ($rw, $mode) = $poll eq "r" ? ($r, "<") 1016 my ($rw, $mode) = $poll eq "r" ? ($r, "<")
1007 : $poll eq "w" ? ($w, ">") 1017 : $poll eq "w" ? ($w, ">")
1008 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'"; 1018 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1009 1019
1017 1027
1018package AnyEvent::Base; 1028package AnyEvent::Base;
1019 1029
1020# default implementation for now and time 1030# default implementation for now and time
1021 1031
1022use Time::HiRes (); 1032BEGIN {
1033 if (eval "use Time::HiRes (); time (); 1") {
1034 *_time = \&Time::HiRes::time;
1035 # if (eval "use POSIX (); (POSIX::times())...
1036 } else {
1037 *_time = sub { time }; # epic fail
1038 }
1039}
1023 1040
1024sub time { Time::HiRes::time } 1041sub time { _time }
1025sub now { Time::HiRes::time } 1042sub now { _time }
1026 1043
1027# default implementation for ->condvar 1044# default implementation for ->condvar
1028 1045
1029sub condvar { 1046sub condvar {
1030 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 1047 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
1031} 1048}
1032 1049
1033# default implementation for ->signal 1050# default implementation for ->signal
1034 1051
1035our %SIG_CB; 1052our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1053
1054sub _signal_exec {
1055 while (%SIG_EV) {
1056 sysread $SIGPIPE_R, my $dummy, 4;
1057 for (keys %SIG_EV) {
1058 delete $SIG_EV{$_};
1059 $_->() for values %{ $SIG_CB{$_} || {} };
1060 }
1061 }
1062}
1036 1063
1037sub signal { 1064sub signal {
1038 my (undef, %arg) = @_; 1065 my (undef, %arg) = @_;
1039 1066
1067 unless ($SIGPIPE_R) {
1068 if (AnyEvent::WIN32) {
1069 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1070 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R) if $SIGPIPE_R;
1071 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case
1072 } else {
1073 pipe $SIGPIPE_R, $SIGPIPE_W;
1074 require Fcntl;
1075 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
1076 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
1077 }
1078
1079 $SIGPIPE_R
1080 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1081
1082 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1083 }
1084
1040 my $signal = uc $arg{signal} 1085 my $signal = uc $arg{signal}
1041 or Carp::croak "required option 'signal' is missing"; 1086 or Carp::croak "required option 'signal' is missing";
1042 1087
1043 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1088 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1044 $SIG{$signal} ||= sub { 1089 $SIG{$signal} ||= sub {
1045 $_->() for values %{ $SIG_CB{$signal} || {} }; 1090 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1091 undef $SIG_EV{$signal};
1046 }; 1092 };
1047 1093
1048 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal" 1094 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
1049} 1095}
1050 1096
1169 1215
1170# undocumented/compatibility with pre-3.4 1216# undocumented/compatibility with pre-3.4
1171*broadcast = \&send; 1217*broadcast = \&send;
1172*wait = \&_wait; 1218*wait = \&_wait;
1173 1219
1220=head1 ERROR AND EXCEPTION HANDLING
1221
1222In general, AnyEvent does not do any error handling - it relies on the
1223caller to do that if required. The L<AnyEvent::Strict> module (see also
1224the C<PERL_ANYEVENT_STRICT> environment variable, below) provides strict
1225checking of all AnyEvent methods, however, which is highly useful during
1226development.
1227
1228As for exception handling (i.e. runtime errors and exceptions thrown while
1229executing a callback), this is not only highly event-loop specific, but
1230also not in any way wrapped by this module, as this is the job of the main
1231program.
1232
1233The pure perl event loop simply re-throws the exception (usually
1234within C<< condvar->recv >>), the L<Event> and L<EV> modules call C<<
1235$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1236so on.
1237
1238=head1 ENVIRONMENT VARIABLES
1239
1240The following environment variables are used by this module or its
1241submodules:
1242
1243=over 4
1244
1245=item C<PERL_ANYEVENT_VERBOSE>
1246
1247By default, AnyEvent will be completely silent except in fatal
1248conditions. You can set this environment variable to make AnyEvent more
1249talkative.
1250
1251When set to C<1> or higher, causes AnyEvent to warn about unexpected
1252conditions, such as not being able to load the event model specified by
1253C<PERL_ANYEVENT_MODEL>.
1254
1255When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1256model it chooses.
1257
1258=item C<PERL_ANYEVENT_STRICT>
1259
1260AnyEvent does not do much argument checking by default, as thorough
1261argument checking is very costly. Setting this variable to a true value
1262will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1263check the arguments passed to most method calls. If it finds any problems
1264it will croak.
1265
1266In other words, enables "strict" mode.
1267
1268Unlike C<use strict>, it is definitely recommended ot keep it off in
1269production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while
1270developing programs can be very useful, however.
1271
1272=item C<PERL_ANYEVENT_MODEL>
1273
1274This can be used to specify the event model to be used by AnyEvent, before
1275auto detection and -probing kicks in. It must be a string consisting
1276entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1277and the resulting module name is loaded and if the load was successful,
1278used as event model. If it fails to load AnyEvent will proceed with
1279auto detection and -probing.
1280
1281This functionality might change in future versions.
1282
1283For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1284could start your program like this:
1285
1286 PERL_ANYEVENT_MODEL=Perl perl ...
1287
1288=item C<PERL_ANYEVENT_PROTOCOLS>
1289
1290Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1291for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1292of auto probing).
1293
1294Must be set to a comma-separated list of protocols or address families,
1295current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1296used, and preference will be given to protocols mentioned earlier in the
1297list.
1298
1299This variable can effectively be used for denial-of-service attacks
1300against local programs (e.g. when setuid), although the impact is likely
1301small, as the program has to handle conenction and other failures anyways.
1302
1303Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1304but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1305- only support IPv4, never try to resolve or contact IPv6
1306addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1307IPv6, but prefer IPv6 over IPv4.
1308
1309=item C<PERL_ANYEVENT_EDNS0>
1310
1311Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1312for DNS. This extension is generally useful to reduce DNS traffic, but
1313some (broken) firewalls drop such DNS packets, which is why it is off by
1314default.
1315
1316Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1317EDNS0 in its DNS requests.
1318
1319=item C<PERL_ANYEVENT_MAX_FORKS>
1320
1321The maximum number of child processes that C<AnyEvent::Util::fork_call>
1322will create in parallel.
1323
1324=back
1325
1174=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1326=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1175 1327
1176This is an advanced topic that you do not normally need to use AnyEvent in 1328This is an advanced topic that you do not normally need to use AnyEvent in
1177a module. This section is only of use to event loop authors who want to 1329a module. This section is only of use to event loop authors who want to
1178provide AnyEvent compatibility. 1330provide AnyEvent compatibility.
1211 1363
1212I<rxvt-unicode> also cheats a bit by not providing blocking access to 1364I<rxvt-unicode> also cheats a bit by not providing blocking access to
1213condition variables: code blocking while waiting for a condition will 1365condition variables: code blocking while waiting for a condition will
1214C<die>. This still works with most modules/usages, and blocking calls must 1366C<die>. This still works with most modules/usages, and blocking calls must
1215not be done in an interactive application, so it makes sense. 1367not be done in an interactive application, so it makes sense.
1216
1217=head1 ENVIRONMENT VARIABLES
1218
1219The following environment variables are used by this module:
1220
1221=over 4
1222
1223=item C<PERL_ANYEVENT_VERBOSE>
1224
1225By default, AnyEvent will be completely silent except in fatal
1226conditions. You can set this environment variable to make AnyEvent more
1227talkative.
1228
1229When set to C<1> or higher, causes AnyEvent to warn about unexpected
1230conditions, such as not being able to load the event model specified by
1231C<PERL_ANYEVENT_MODEL>.
1232
1233When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1234model it chooses.
1235
1236=item C<PERL_ANYEVENT_STRICT>
1237
1238AnyEvent does not do much argument checking by default, as thorough
1239argument checking is very costly. Setting this variable to a true value
1240will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1241check the arguments passed to most method calls. If it finds any problems
1242it will croak.
1243
1244In other words, enables "strict" mode.
1245
1246Unlike C<use strict> it is definitely recommended ot keep it off in
1247production.
1248
1249=item C<PERL_ANYEVENT_MODEL>
1250
1251This can be used to specify the event model to be used by AnyEvent, before
1252auto detection and -probing kicks in. It must be a string consisting
1253entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1254and the resulting module name is loaded and if the load was successful,
1255used as event model. If it fails to load AnyEvent will proceed with
1256auto detection and -probing.
1257
1258This functionality might change in future versions.
1259
1260For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1261could start your program like this:
1262
1263 PERL_ANYEVENT_MODEL=Perl perl ...
1264
1265=item C<PERL_ANYEVENT_PROTOCOLS>
1266
1267Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1268for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1269of auto probing).
1270
1271Must be set to a comma-separated list of protocols or address families,
1272current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1273used, and preference will be given to protocols mentioned earlier in the
1274list.
1275
1276This variable can effectively be used for denial-of-service attacks
1277against local programs (e.g. when setuid), although the impact is likely
1278small, as the program has to handle connection errors already-
1279
1280Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1281but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1282- only support IPv4, never try to resolve or contact IPv6
1283addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1284IPv6, but prefer IPv6 over IPv4.
1285
1286=item C<PERL_ANYEVENT_EDNS0>
1287
1288Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1289for DNS. This extension is generally useful to reduce DNS traffic, but
1290some (broken) firewalls drop such DNS packets, which is why it is off by
1291default.
1292
1293Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1294EDNS0 in its DNS requests.
1295
1296=item C<PERL_ANYEVENT_MAX_FORKS>
1297
1298The maximum number of child processes that C<AnyEvent::Util::fork_call>
1299will create in parallel.
1300
1301=back
1302 1368
1303=head1 EXAMPLE PROGRAM 1369=head1 EXAMPLE PROGRAM
1304 1370
1305The following program uses an I/O watcher to read data from STDIN, a timer 1371The following program uses an I/O watcher to read data from STDIN, a timer
1306to display a message once per second, and a condition variable to quit the 1372to display a message once per second, and a condition variable to quit the
1500watcher. 1566watcher.
1501 1567
1502=head3 Results 1568=head3 Results
1503 1569
1504 name watchers bytes create invoke destroy comment 1570 name watchers bytes create invoke destroy comment
1505 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1571 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1506 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1572 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1507 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1573 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1508 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1574 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1509 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1575 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1510 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1576 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1511 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1577 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1512 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1578 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1513 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1579 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1514 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1580 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1515 1581
1516=head3 Discussion 1582=head3 Discussion
1517 1583
1518The benchmark does I<not> measure scalability of the event loop very 1584The benchmark does I<not> measure scalability of the event loop very
1519well. For example, a select-based event loop (such as the pure perl one) 1585well. For example, a select-based event loop (such as the pure perl one)
1721watchers, as the management overhead dominates. 1787watchers, as the management overhead dominates.
1722 1788
1723=back 1789=back
1724 1790
1725 1791
1792=head1 SIGNALS
1793
1794AnyEvent currently installs handlers for these signals:
1795
1796=over 4
1797
1798=item SIGCHLD
1799
1800A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
1801emulation for event loops that do not support them natively. Also, some
1802event loops install a similar handler.
1803
1804=item SIGPIPE
1805
1806A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
1807when AnyEvent gets loaded.
1808
1809The rationale for this is that AnyEvent users usually do not really depend
1810on SIGPIPE delivery (which is purely an optimisation for shell use, or
1811badly-written programs), but C<SIGPIPE> can cause spurious and rare
1812program exits as a lot of people do not expect C<SIGPIPE> when writing to
1813some random socket.
1814
1815The rationale for installing a no-op handler as opposed to ignoring it is
1816that this way, the handler will be restored to defaults on exec.
1817
1818Feel free to install your own handler, or reset it to defaults.
1819
1820=back
1821
1822=cut
1823
1824$SIG{PIPE} = sub { }
1825 unless defined $SIG{PIPE};
1826
1827
1726=head1 FORK 1828=head1 FORK
1727 1829
1728Most event libraries are not fork-safe. The ones who are usually are 1830Most event libraries are not fork-safe. The ones who are usually are
1729because they rely on inefficient but fork-safe C<select> or C<poll> 1831because they rely on inefficient but fork-safe C<select> or C<poll>
1730calls. Only L<EV> is fully fork-aware. 1832calls. Only L<EV> is fully fork-aware.
1758=head1 BUGS 1860=head1 BUGS
1759 1861
1760Perl 5.8 has numerous memleaks that sometimes hit this module and are hard 1862Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
1761to work around. If you suffer from memleaks, first upgrade to Perl 5.10 1863to work around. If you suffer from memleaks, first upgrade to Perl 5.10
1762and check wether the leaks still show up. (Perl 5.10.0 has other annoying 1864and check wether the leaks still show up. (Perl 5.10.0 has other annoying
1763mamleaks, such as leaking on C<map> and C<grep> but it is usually not as 1865memleaks, such as leaking on C<map> and C<grep> but it is usually not as
1764pronounced). 1866pronounced).
1765 1867
1766 1868
1767=head1 SEE ALSO 1869=head1 SEE ALSO
1768 1870

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines