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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines