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.251 by root, Mon Jul 20 22:39:57 2009 UTC vs.
Revision 1.261 by root, Tue Jul 28 12:56:17 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - events independent of event loop implementation 3AnyEvent - the DBI of event loop programming
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt
6event loops. 6and POE are various supported event loops/environments.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
… …
47 47
48There is a mailinglist for discussing all things AnyEvent, and an IRC 48There is a mailinglist for discussing all things AnyEvent, and an IRC
49channel, too. 49channel, too.
50 50
51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software 51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
52Respository>, at L<http://anyevent.schmorp.de>, for more info. 52Repository>, at L<http://anyevent.schmorp.de>, for more info.
53 53
54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
55 55
56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
57nowadays. So what is different about AnyEvent? 57nowadays. So what is different about AnyEvent?
… …
400 400
401=head2 CHILD PROCESS WATCHERS 401=head2 CHILD PROCESS WATCHERS
402 402
403You can also watch on a child process exit and catch its exit status. 403You can also watch on a child process exit and catch its exit status.
404 404
405The child process is specified by the C<pid> argument (if set to C<0>, it 405The child process is specified by the C<pid> argument (one some backends,
406watches for any child process exit). The watcher will triggered only when 406using C<0> watches for any child process exit, on others this will
407the child process has finished and an exit status is available, not on 407croak). The watcher will be triggered only when the child process has
408any trace events (stopped/continued). 408finished and an exit status is available, not on any trace events
409(stopped/continued).
409 410
410The callback will be called with the pid and exit status (as returned by 411The callback will be called with the pid and exit status (as returned by
411waitpid), so unlike other watcher types, you I<can> rely on child watcher 412waitpid), so unlike other watcher types, you I<can> rely on child watcher
412callback arguments. 413callback arguments.
413 414
… …
796 797
797 AnyEvent::Impl::Glib based on Glib, slow but very stable. 798 AnyEvent::Impl::Glib based on Glib, slow but very stable.
798 AnyEvent::Impl::Tk based on Tk, very broken. 799 AnyEvent::Impl::Tk based on Tk, very broken.
799 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 800 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
800 AnyEvent::Impl::POE based on POE, very slow, some limitations. 801 AnyEvent::Impl::POE based on POE, very slow, some limitations.
802 AnyEvent::Impl::Irssi used when running within irssi.
801 803
802=item Backends with special needs. 804=item Backends with special needs.
803 805
804Qt requires the Qt::Application to be instantiated first, but will 806Qt requires the Qt::Application to be instantiated first, but will
805otherwise be picked up automatically. As long as the main program 807otherwise be picked up automatically. As long as the main program
… …
879event module detection too early, for example, L<AnyEvent::AIO> creates 881event module detection too early, for example, L<AnyEvent::AIO> creates
880and installs the global L<IO::AIO> watcher in a C<post_detect> block to 882and installs the global L<IO::AIO> watcher in a C<post_detect> block to
881avoid autodetecting the event module at load time. 883avoid autodetecting the event module at load time.
882 884
883If called in scalar or list context, then it creates and returns an object 885If called in scalar or list context, then it creates and returns an object
884that automatically removes the callback again when it is destroyed. See 886that automatically removes the callback again when it is destroyed (or
887C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
885L<Coro::BDB> for a case where this is useful. 888a case where this is useful.
889
890Example: Create a watcher for the IO::AIO module and store it in
891C<$WATCHER>. Only do so after the event loop is initialised, though.
892
893 our WATCHER;
894
895 my $guard = AnyEvent::post_detect {
896 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
897 };
898
899 # the ||= is important in case post_detect immediately runs the block,
900 # as to not clobber the newly-created watcher. assigning both watcher and
901 # post_detect guard to the same variable has the advantage of users being
902 # able to just C<undef $WATCHER> if the watcher causes them grief.
903
904 $WATCHER ||= $guard;
886 905
887=item @AnyEvent::post_detect 906=item @AnyEvent::post_detect
888 907
889If there are any code references in this array (you can C<push> to it 908If there are any code references in this array (you can C<push> to it
890before or after loading AnyEvent), then they will called directly after 909before or after loading AnyEvent), then they will called directly after
… …
1067 1086
1068BEGIN { AnyEvent::common_sense } 1087BEGIN { AnyEvent::common_sense }
1069 1088
1070use Carp (); 1089use Carp ();
1071 1090
1072our $VERSION = 4.86; 1091our $VERSION = 4.881;
1073our $MODEL; 1092our $MODEL;
1074 1093
1075our $AUTOLOAD; 1094our $AUTOLOAD;
1076our @ISA; 1095our @ISA;
1077 1096
… …
1102 for reverse split /\s*,\s*/, 1121 for reverse split /\s*,\s*/,
1103 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1122 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1104} 1123}
1105 1124
1106my @models = ( 1125my @models = (
1107 [EV:: => AnyEvent::Impl::EV::], 1126 [EV:: => AnyEvent::Impl::EV:: , 1],
1108 [Event:: => AnyEvent::Impl::Event::], 1127 [Event:: => AnyEvent::Impl::Event::, 1],
1109 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1128 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1110 # everything below here will not be autoprobed 1129 # everything below here will not (normally) be autoprobed
1111 # as the pureperl backend should work everywhere 1130 # as the pureperl backend should work everywhere
1112 # and is usually faster 1131 # and is usually faster
1113 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1132 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1114 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1133 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1134 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1115 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1135 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1116 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1136 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1117 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1137 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1118 [Wx:: => AnyEvent::Impl::POE::], 1138 [Wx:: => AnyEvent::Impl::POE::],
1119 [Prima:: => AnyEvent::Impl::POE::], 1139 [Prima:: => AnyEvent::Impl::POE::],
1120 # IO::Async is just too broken - we would need workarounds for its 1140 # IO::Async is just too broken - we would need workarounds for its
1121 # byzantine signal and broken child handling, among others. 1141 # byzantine signal and broken child handling, among others.
1122 # IO::Async is rather hard to detect, as it doesn't have any 1142 # IO::Async is rather hard to detect, as it doesn't have any
1123 # obvious default class. 1143 # obvious default class.
1124# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1144# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1125# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1145# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1126# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1146# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1127); 1147);
1128 1148
1129our %method = map +($_ => 1), 1149our %method = map +($_ => 1),
1130 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1150 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
1131 1151
… …
1135 my ($cb) = @_; 1155 my ($cb) = @_;
1136 1156
1137 if ($MODEL) { 1157 if ($MODEL) {
1138 $cb->(); 1158 $cb->();
1139 1159
1140 1 1160 undef
1141 } else { 1161 } else {
1142 push @post_detect, $cb; 1162 push @post_detect, $cb;
1143 1163
1144 defined wantarray 1164 defined wantarray
1145 ? bless \$cb, "AnyEvent::Util::postdetect" 1165 ? bless \$cb, "AnyEvent::Util::postdetect"
… …
1177 } 1197 }
1178 } 1198 }
1179 } 1199 }
1180 1200
1181 unless ($MODEL) { 1201 unless ($MODEL) {
1182 # try to load a model 1202 # try to autoload a model
1183
1184 for (@REGISTRY, @models) { 1203 for (@REGISTRY, @models) {
1185 my ($package, $model) = @$_; 1204 my ($package, $model, $autoload) = @$_;
1205 if (
1206 $autoload
1186 if (eval "require $package" 1207 and eval "require $package"
1187 and ${"$package\::VERSION"} > 0 1208 and ${"$package\::VERSION"} > 0
1188 and eval "require $model") { 1209 and eval "require $model"
1210 ) {
1189 $MODEL = $model; 1211 $MODEL = $model;
1190 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2; 1212 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1191 last; 1213 last;
1192 } 1214 }
1193 } 1215 }
1194 1216
1195 $MODEL 1217 $MODEL
… …
1284 $_->() for values %{ $SIG_CB{$_} || {} }; 1306 $_->() for values %{ $SIG_CB{$_} || {} };
1285 } 1307 }
1286 } 1308 }
1287} 1309}
1288 1310
1289# install a dumym wakeupw atcher to reduce signal catching latency 1311# install a dummy wakeup watcher to reduce signal catching latency
1290sub _sig_add() { 1312sub _sig_add() {
1291 unless ($SIG_COUNT++) { 1313 unless ($SIG_COUNT++) {
1292 # try to align timer on a full-second boundary, if possible 1314 # try to align timer on a full-second boundary, if possible
1293 my $NOW = AnyEvent->now; 1315 my $NOW = AnyEvent->now;
1294 1316
… …
1309 my (undef, %arg) = @_; 1331 my (undef, %arg) = @_;
1310 1332
1311 my $signal = uc $arg{signal} 1333 my $signal = uc $arg{signal}
1312 or Carp::croak "required option 'signal' is missing"; 1334 or Carp::croak "required option 'signal' is missing";
1313 1335
1314 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1315
1316 if ($HAVE_ASYNC_INTERRUPT) { 1336 if ($HAVE_ASYNC_INTERRUPT) {
1317 # async::interrupt 1337 # async::interrupt
1338
1339 $signal = Async::Interrupt::sig2num ($signal);
1340 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1318 1341
1319 $SIG_ASY{$signal} ||= do { 1342 $SIG_ASY{$signal} ||= do {
1320 my $asy = new Async::Interrupt 1343 my $asy = new Async::Interrupt
1321 cb => sub { undef $SIG_EV{$signal} }, 1344 cb => sub { undef $SIG_EV{$signal} },
1322 signal => $signal, 1345 signal => $signal,
… …
1328 }; 1351 };
1329 1352
1330 } else { 1353 } else {
1331 # pure perl 1354 # pure perl
1332 1355
1356 # AE::Util has been loaded in signal
1357 $signal = AnyEvent::Util::sig2name ($signal);
1358 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1359
1333 $SIG{$signal} ||= sub { 1360 $SIG{$signal} ||= sub {
1334 local $!; 1361 local $!;
1335 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1362 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1336 undef $SIG_EV{$signal}; 1363 undef $SIG_EV{$signal};
1337 }; 1364 };
… …
1344 bless [$signal, $arg{cb}], "AnyEvent::Base::signal" 1371 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1345} 1372}
1346 1373
1347sub signal { 1374sub signal {
1348 # probe for availability of Async::Interrupt 1375 # probe for availability of Async::Interrupt
1349 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 0.6 (); 1") { 1376 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 1.0 (); 1") {
1350 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1377 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1351 1378
1352 $HAVE_ASYNC_INTERRUPT = 1; 1379 $HAVE_ASYNC_INTERRUPT = 1;
1353 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1380 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1354 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec); 1381 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
… …
1405our %PID_CB; 1432our %PID_CB;
1406our $CHLD_W; 1433our $CHLD_W;
1407our $CHLD_DELAY_W; 1434our $CHLD_DELAY_W;
1408our $WNOHANG; 1435our $WNOHANG;
1409 1436
1437sub _emit_childstatus($$) {
1438 my (undef, $rpid, $rstatus) = @_;
1439
1440 $_->($rpid, $rstatus)
1441 for values %{ $PID_CB{$rpid} || {} },
1442 values %{ $PID_CB{0} || {} };
1443}
1444
1410sub _sigchld { 1445sub _sigchld {
1446 my $pid;
1447
1448 AnyEvent->_emit_childstatus ($pid, $?)
1411 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1449 while ($pid = waitpid -1, $WNOHANG) > 0;
1412 $_->($pid, $?)
1413 for values %{ $PID_CB{$pid} || {} },
1414 values %{ $PID_CB{0} || {} };
1415 }
1416} 1450}
1417 1451
1418sub child { 1452sub child {
1419 my (undef, %arg) = @_; 1453 my (undef, %arg) = @_;
1420 1454
… …
2399L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2433L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2400 2434
2401Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2435Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2402L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2436L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2403L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2437L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2404L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>. 2438L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>.
2405 2439
2406Non-blocking file handles, sockets, TCP clients and 2440Non-blocking file handles, sockets, TCP clients and
2407servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2441servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2408 2442
2409Asynchronous DNS: L<AnyEvent::DNS>. 2443Asynchronous DNS: L<AnyEvent::DNS>.

Diff Legend

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