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.247 by root, Sat Jul 18 22:24:17 2009 UTC vs.
Revision 1.263 by root, Wed Jul 29 12:39:21 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 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
… …
40=head1 INTRODUCTION/TUTORIAL 40=head1 INTRODUCTION/TUTORIAL
41 41
42This manpage is mainly a reference manual. If you are interested 42This manpage is mainly a reference manual. If you are interested
43in a tutorial or some gentle introduction, have a look at the 43in a tutorial or some gentle introduction, have a look at the
44L<AnyEvent::Intro> manpage. 44L<AnyEvent::Intro> manpage.
45
46=head1 SUPPORT
47
48There is a mailinglist for discussing all things AnyEvent, and an IRC
49channel, too.
50
51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
52Repository>, at L<http://anyevent.schmorp.de>, for more info.
45 53
46=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
47 55
48Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
49nowadays. So what is different about AnyEvent? 57nowadays. So what is different about AnyEvent?
… …
392 400
393=head2 CHILD PROCESS WATCHERS 401=head2 CHILD PROCESS WATCHERS
394 402
395You 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.
396 404
397The 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,
398watches for any child process exit). The watcher will triggered only when 406using C<0> watches for any child process exit, on others this will
399the child process has finished and an exit status is available, not on 407croak). The watcher will be triggered only when the child process has
400any trace events (stopped/continued). 408finished and an exit status is available, not on any trace events
409(stopped/continued).
401 410
402The 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
403waitpid), 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
404callback arguments. 413callback arguments.
405 414
… …
509Condition variables are similar to callbacks, except that you can 518Condition variables are similar to callbacks, except that you can
510optionally wait for them. They can also be called merge points - points 519optionally wait for them. They can also be called merge points - points
511in time where multiple outstanding events have been processed. And yet 520in time where multiple outstanding events have been processed. And yet
512another way to call them is transactions - each condition variable can be 521another way to call them is transactions - each condition variable can be
513used to represent a transaction, which finishes at some point and delivers 522used to represent a transaction, which finishes at some point and delivers
514a result. 523a result. And yet some people know them as "futures" - a promise to
524compute/deliver something that you can wait for.
515 525
516Condition variables are very useful to signal that something has finished, 526Condition variables are very useful to signal that something has finished,
517for example, if you write a module that does asynchronous http requests, 527for example, if you write a module that does asynchronous http requests,
518then a condition variable would be the ideal candidate to signal the 528then a condition variable would be the ideal candidate to signal the
519availability of results. The user can either act when the callback is 529availability of results. The user can either act when the callback is
… …
787 797
788 AnyEvent::Impl::Glib based on Glib, slow but very stable. 798 AnyEvent::Impl::Glib based on Glib, slow but very stable.
789 AnyEvent::Impl::Tk based on Tk, very broken. 799 AnyEvent::Impl::Tk based on Tk, very broken.
790 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 800 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
791 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.
792 803
793=item Backends with special needs. 804=item Backends with special needs.
794 805
795Qt requires the Qt::Application to be instantiated first, but will 806Qt requires the Qt::Application to be instantiated first, but will
796otherwise be picked up automatically. As long as the main program 807otherwise be picked up automatically. As long as the main program
… …
870event module detection too early, for example, L<AnyEvent::AIO> creates 881event module detection too early, for example, L<AnyEvent::AIO> creates
871and 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
872avoid autodetecting the event module at load time. 883avoid autodetecting the event module at load time.
873 884
874If 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
875that 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
876L<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;
877 905
878=item @AnyEvent::post_detect 906=item @AnyEvent::post_detect
879 907
880If 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
881before or after loading AnyEvent), then they will called directly after 909before or after loading AnyEvent), then they will called directly after
… …
1058 1086
1059BEGIN { AnyEvent::common_sense } 1087BEGIN { AnyEvent::common_sense }
1060 1088
1061use Carp (); 1089use Carp ();
1062 1090
1063our $VERSION = 4.85; 1091our $VERSION = 4.881;
1064our $MODEL; 1092our $MODEL;
1065 1093
1066our $AUTOLOAD; 1094our $AUTOLOAD;
1067our @ISA; 1095our @ISA;
1068 1096
… …
1093 for reverse split /\s*,\s*/, 1121 for reverse split /\s*,\s*/,
1094 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1122 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1095} 1123}
1096 1124
1097my @models = ( 1125my @models = (
1098 [EV:: => AnyEvent::Impl::EV::], 1126 [EV:: => AnyEvent::Impl::EV:: , 1],
1099 [Event:: => AnyEvent::Impl::Event::], 1127 [Event:: => AnyEvent::Impl::Event::, 1],
1100 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1128 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1101 # everything below here will not be autoprobed 1129 # everything below here will not (normally) be autoprobed
1102 # as the pureperl backend should work everywhere 1130 # as the pureperl backend should work everywhere
1103 # and is usually faster 1131 # and is usually faster
1104 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1132 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1105 [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
1106 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1135 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1107 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1136 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1108 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1137 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1109 [Wx:: => AnyEvent::Impl::POE::], 1138 [Wx:: => AnyEvent::Impl::POE::],
1110 [Prima:: => AnyEvent::Impl::POE::], 1139 [Prima:: => AnyEvent::Impl::POE::],
1111 # 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
1112 # byzantine signal and broken child handling, among others. 1141 # byzantine signal and broken child handling, among others.
1113 # 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
1114 # obvious default class. 1143 # obvious default class.
1115# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1144# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1116# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1145# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1117# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1146# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1118); 1147);
1119 1148
1120our %method = map +($_ => 1), 1149our %method = map +($_ => 1),
1121 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);
1122 1151
… …
1126 my ($cb) = @_; 1155 my ($cb) = @_;
1127 1156
1128 if ($MODEL) { 1157 if ($MODEL) {
1129 $cb->(); 1158 $cb->();
1130 1159
1131 1 1160 undef
1132 } else { 1161 } else {
1133 push @post_detect, $cb; 1162 push @post_detect, $cb;
1134 1163
1135 defined wantarray 1164 defined wantarray
1136 ? bless \$cb, "AnyEvent::Util::postdetect" 1165 ? bless \$cb, "AnyEvent::Util::postdetect"
… …
1168 } 1197 }
1169 } 1198 }
1170 } 1199 }
1171 1200
1172 unless ($MODEL) { 1201 unless ($MODEL) {
1173 # try to load a model 1202 # try to autoload a model
1174
1175 for (@REGISTRY, @models) { 1203 for (@REGISTRY, @models) {
1176 my ($package, $model) = @$_; 1204 my ($package, $model, $autoload) = @$_;
1205 if (
1206 $autoload
1177 if (eval "require $package" 1207 and eval "require $package"
1178 and ${"$package\::VERSION"} > 0 1208 and ${"$package\::VERSION"} > 0
1179 and eval "require $model") { 1209 and eval "require $model"
1210 ) {
1180 $MODEL = $model; 1211 $MODEL = $model;
1181 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2; 1212 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1182 last; 1213 last;
1183 } 1214 }
1184 } 1215 }
1185 1216
1186 $MODEL 1217 $MODEL
… …
1258} 1289}
1259 1290
1260# default implementation for ->signal 1291# default implementation for ->signal
1261 1292
1262our $HAVE_ASYNC_INTERRUPT; 1293our $HAVE_ASYNC_INTERRUPT;
1294
1295sub _have_async_interrupt() {
1296 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT}
1297 && eval "use Async::Interrupt 1.0 (); 1")
1298 unless defined $HAVE_ASYNC_INTERRUPT;
1299
1300 $HAVE_ASYNC_INTERRUPT
1301}
1302
1263our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1303our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1264our (%SIG_ASY, %SIG_ASY_W); 1304our (%SIG_ASY, %SIG_ASY_W);
1265our ($SIG_COUNT, $SIG_TW); 1305our ($SIG_COUNT, $SIG_TW);
1266 1306
1267sub _signal_exec { 1307sub _signal_exec {
… …
1275 $_->() for values %{ $SIG_CB{$_} || {} }; 1315 $_->() for values %{ $SIG_CB{$_} || {} };
1276 } 1316 }
1277 } 1317 }
1278} 1318}
1279 1319
1280# install a dumym wakeupw atcher to reduce signal catching latency 1320# install a dummy wakeup watcher to reduce signal catching latency
1281sub _sig_add() { 1321sub _sig_add() {
1282 unless ($SIG_COUNT++) { 1322 unless ($SIG_COUNT++) {
1283 # try to align timer on a full-second boundary, if possible 1323 # try to align timer on a full-second boundary, if possible
1284 my $NOW = AnyEvent->now; 1324 my $NOW = AnyEvent->now;
1285 1325
… …
1294sub _sig_del { 1334sub _sig_del {
1295 undef $SIG_TW 1335 undef $SIG_TW
1296 unless --$SIG_COUNT; 1336 unless --$SIG_COUNT;
1297} 1337}
1298 1338
1339our %SIGNAME2NUM;
1340our @SIGNUM2NAME;
1341our $_sig_name_init; $_sig_name_init = sub {
1342 undef $_sig_name_init;
1343
1344 if (_have_async_interrupt) {
1345 *sig2num = \&Async::Interrupt::sig2num;
1346 *sig2name = \&Async::Interrupt::sig2name;
1347 } else {
1348 require Config;
1349
1350 @SIGNAME2NUM{ split ' ', $Config::Config{sig_name} }
1351 = split ' ', $Config::Config{sig_num};
1352 @SIGNUM2NAME[values %SIGNAME2NUM] = keys %SIGNAME2NUM;
1353
1354 *sig2num = sub($) {
1355 $_[0] > 0 ? shift : $SIGNAME2NUM{+shift}
1356 };
1357 *sig2name = sub ($) {
1358 $_[0] > 0 ? $SIGNUM2NAME[+shift] : shift
1359 };
1360 }
1361};
1362
1363sub sig2num ($) { &$_sig_name_init; &sig2num }
1364sub sig2name($) { &$_sig_name_init; &sig2name }
1365
1299sub _signal { 1366sub _signal {
1300 my (undef, %arg) = @_; 1367 my (undef, %arg) = @_;
1301 1368
1302 my $signal = uc $arg{signal} 1369 my $signal = uc $arg{signal}
1303 or Carp::croak "required option 'signal' is missing"; 1370 or Carp::croak "required option 'signal' is missing";
1304 1371
1305 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1306
1307 if ($HAVE_ASYNC_INTERRUPT) { 1372 if ($HAVE_ASYNC_INTERRUPT) {
1308 # async::interrupt 1373 # async::interrupt
1309 1374
1310 $SIG_ASY{$signal} ||= do { 1375 $signal = sig2num $signal;
1311 my $asy = new Async::Interrupt 1376 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1377
1378 $SIG_ASY{$signal} ||= new Async::Interrupt
1312 cb => sub { undef $SIG_EV{$signal} }, 1379 cb => sub { undef $SIG_EV{$signal} },
1313 signal => $signal, 1380 signal => $signal,
1314 pipe => [$SIGPIPE_R->filenos], 1381 pipe => [$SIGPIPE_R->filenos],
1315 ;
1316 $asy->pipe_autodrain (0); 1382 pipe_autodrain => 0,
1317
1318 $asy
1319 }; 1383 ;
1320 1384
1321 } else { 1385 } else {
1322 # pure perl 1386 # pure perl
1387
1388 # AE::Util has been loaded in signal
1389 $signal = sig2name $signal;
1390 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1323 1391
1324 $SIG{$signal} ||= sub { 1392 $SIG{$signal} ||= sub {
1325 local $!; 1393 local $!;
1326 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1394 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1327 undef $SIG_EV{$signal}; 1395 undef $SIG_EV{$signal};
… …
1335 bless [$signal, $arg{cb}], "AnyEvent::Base::signal" 1403 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1336} 1404}
1337 1405
1338sub signal { 1406sub signal {
1339 # probe for availability of Async::Interrupt 1407 # probe for availability of Async::Interrupt
1340 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 0.6 (); 1") { 1408 if (_have_async_interrupt) {
1341 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1409 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1342 1410
1343 $HAVE_ASYNC_INTERRUPT = 1;
1344 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1411 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1345 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec); 1412 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1346 1413
1347 } else { 1414 } else {
1348 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1415 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
… …
1396our %PID_CB; 1463our %PID_CB;
1397our $CHLD_W; 1464our $CHLD_W;
1398our $CHLD_DELAY_W; 1465our $CHLD_DELAY_W;
1399our $WNOHANG; 1466our $WNOHANG;
1400 1467
1468sub _emit_childstatus($$) {
1469 my (undef, $rpid, $rstatus) = @_;
1470
1471 $_->($rpid, $rstatus)
1472 for values %{ $PID_CB{$rpid} || {} },
1473 values %{ $PID_CB{0} || {} };
1474}
1475
1401sub _sigchld { 1476sub _sigchld {
1477 my $pid;
1478
1479 AnyEvent->_emit_childstatus ($pid, $?)
1402 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1480 while ($pid = waitpid -1, $WNOHANG) > 0;
1403 $_->($pid, $?)
1404 for values %{ $PID_CB{$pid} || {} },
1405 values %{ $PID_CB{0} || {} };
1406 }
1407} 1481}
1408 1482
1409sub child { 1483sub child {
1410 my (undef, %arg) = @_; 1484 my (undef, %arg) = @_;
1411 1485
… …
2313 2387
2314=item L<JSON> and L<JSON::XS> 2388=item L<JSON> and L<JSON::XS>
2315 2389
2316This module is required when you want to read or write JSON data via 2390This module is required when you want to read or write JSON data via
2317L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2391L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2318advantage of the ulta-high-speed L<JSON::XS> module when it is installed. 2392advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2319 2393
2320In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is 2394In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2321installed. 2395installed.
2322 2396
2323=item L<Net::SSLeay> 2397=item L<Net::SSLeay>
… …
2390L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2464L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2391 2465
2392Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2466Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2393L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2467L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2394L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2468L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2395L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>. 2469L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>.
2396 2470
2397Non-blocking file handles, sockets, TCP clients and 2471Non-blocking file handles, sockets, TCP clients and
2398servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2472servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2399 2473
2400Asynchronous DNS: L<AnyEvent::DNS>. 2474Asynchronous DNS: L<AnyEvent::DNS>.

Diff Legend

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