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.174 by root, Thu Jul 24 06:40:22 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.22; 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
1016 1027
1017package AnyEvent::Base; 1028package AnyEvent::Base;
1018 1029
1019# default implementation for now and time 1030# default implementation for now and time
1020 1031
1021use 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}
1022 1040
1023sub time { Time::HiRes::time } 1041sub time { _time }
1024sub now { Time::HiRes::time } 1042sub now { _time }
1025 1043
1026# default implementation for ->condvar 1044# default implementation for ->condvar
1027 1045
1028sub condvar { 1046sub condvar {
1029 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 1047 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
1030} 1048}
1031 1049
1032# default implementation for ->signal 1050# default implementation for ->signal
1033 1051
1034our %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}
1035 1064
1036sub signal { 1065sub signal {
1037 my (undef, %arg) = @_; 1066 my (undef, %arg) = @_;
1038 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
1039 my $signal = uc $arg{signal} 1086 my $signal = uc $arg{signal}
1040 or Carp::croak "required option 'signal' is missing"; 1087 or Carp::croak "required option 'signal' is missing";
1041 1088
1042 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1089 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1043 $SIG{$signal} ||= sub { 1090 $SIG{$signal} ||= sub {
1044 $_->() for values %{ $SIG_CB{$signal} || {} }; 1091 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1092 undef $SIG_EV{$signal};
1045 }; 1093 };
1046 1094
1047 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal" 1095 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
1048} 1096}
1049 1097
1168 1216
1169# undocumented/compatibility with pre-3.4 1217# undocumented/compatibility with pre-3.4
1170*broadcast = \&send; 1218*broadcast = \&send;
1171*wait = \&_wait; 1219*wait = \&_wait;
1172 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
1173=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1327=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1174 1328
1175This 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
1176a 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
1177provide AnyEvent compatibility. 1331provide AnyEvent compatibility.
1210 1364
1211I<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
1212condition variables: code blocking while waiting for a condition will 1366condition variables: code blocking while waiting for a condition will
1213C<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
1214not be done in an interactive application, so it makes sense. 1368not be done in an interactive application, so it makes sense.
1215
1216=head1 ENVIRONMENT VARIABLES
1217
1218The following environment variables are used by this module:
1219
1220=over 4
1221
1222=item C<PERL_ANYEVENT_VERBOSE>
1223
1224By default, AnyEvent will be completely silent except in fatal
1225conditions. You can set this environment variable to make AnyEvent more
1226talkative.
1227
1228When set to C<1> or higher, causes AnyEvent to warn about unexpected
1229conditions, such as not being able to load the event model specified by
1230C<PERL_ANYEVENT_MODEL>.
1231
1232When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1233model it chooses.
1234
1235=item C<PERL_ANYEVENT_STRICT>
1236
1237AnyEvent does not do much argument checking by default, as thorough
1238argument checking is very costly. Setting this variable to a true value
1239will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1240check the arguments passed to most method calls. If it finds any problems
1241it will croak.
1242
1243In other words, enables "strict" mode.
1244
1245Unlike C<use strict> it is definitely recommended ot keep it off in
1246production.
1247
1248=item C<PERL_ANYEVENT_MODEL>
1249
1250This can be used to specify the event model to be used by AnyEvent, before
1251auto detection and -probing kicks in. It must be a string consisting
1252entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1253and the resulting module name is loaded and if the load was successful,
1254used as event model. If it fails to load AnyEvent will proceed with
1255auto detection and -probing.
1256
1257This functionality might change in future versions.
1258
1259For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1260could start your program like this:
1261
1262 PERL_ANYEVENT_MODEL=Perl perl ...
1263
1264=item C<PERL_ANYEVENT_PROTOCOLS>
1265
1266Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1267for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1268of auto probing).
1269
1270Must be set to a comma-separated list of protocols or address families,
1271current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1272used, and preference will be given to protocols mentioned earlier in the
1273list.
1274
1275This variable can effectively be used for denial-of-service attacks
1276against local programs (e.g. when setuid), although the impact is likely
1277small, as the program has to handle connection errors already-
1278
1279Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1280but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1281- only support IPv4, never try to resolve or contact IPv6
1282addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1283IPv6, but prefer IPv6 over IPv4.
1284
1285=item C<PERL_ANYEVENT_EDNS0>
1286
1287Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1288for DNS. This extension is generally useful to reduce DNS traffic, but
1289some (broken) firewalls drop such DNS packets, which is why it is off by
1290default.
1291
1292Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1293EDNS0 in its DNS requests.
1294
1295=item C<PERL_ANYEVENT_MAX_FORKS>
1296
1297The maximum number of child processes that C<AnyEvent::Util::fork_call>
1298will create in parallel.
1299
1300=back
1301 1369
1302=head1 EXAMPLE PROGRAM 1370=head1 EXAMPLE PROGRAM
1303 1371
1304The 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
1305to 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
1499watcher. 1567watcher.
1500 1568
1501=head3 Results 1569=head3 Results
1502 1570
1503 name watchers bytes create invoke destroy comment 1571 name watchers bytes create invoke destroy comment
1504 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
1505 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
1506 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
1507 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
1508 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
1509 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
1510 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
1511 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
1512 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
1513 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
1514 1582
1515=head3 Discussion 1583=head3 Discussion
1516 1584
1517The benchmark does I<not> measure scalability of the event loop very 1585The benchmark does I<not> measure scalability of the event loop very
1518well. 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)
1720watchers, as the management overhead dominates. 1788watchers, as the management overhead dominates.
1721 1789
1722=back 1790=back
1723 1791
1724 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
1725=head1 FORK 1829=head1 FORK
1726 1830
1727Most 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
1728because 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>
1729calls. Only L<EV> is fully fork-aware. 1833calls. Only L<EV> is fully fork-aware.
1757=head1 BUGS 1861=head1 BUGS
1758 1862
1759Perl 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
1760to 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
1761and 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
1762mamleaks, 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
1763pronounced). 1867pronounced).
1764 1868
1765 1869
1766=head1 SEE ALSO 1870=head1 SEE ALSO
1767 1871

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines