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.261 by root, Tue Jul 28 12:56:17 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
… …
1275 $_->() for values %{ $SIG_CB{$_} || {} }; 1306 $_->() for values %{ $SIG_CB{$_} || {} };
1276 } 1307 }
1277 } 1308 }
1278} 1309}
1279 1310
1280# install a dumym wakeupw atcher to reduce signal catching latency 1311# install a dummy wakeup watcher to reduce signal catching latency
1281sub _sig_add() { 1312sub _sig_add() {
1282 unless ($SIG_COUNT++) { 1313 unless ($SIG_COUNT++) {
1283 # try to align timer on a full-second boundary, if possible 1314 # try to align timer on a full-second boundary, if possible
1284 my $NOW = AnyEvent->now; 1315 my $NOW = AnyEvent->now;
1285 1316
… …
1300 my (undef, %arg) = @_; 1331 my (undef, %arg) = @_;
1301 1332
1302 my $signal = uc $arg{signal} 1333 my $signal = uc $arg{signal}
1303 or Carp::croak "required option 'signal' is missing"; 1334 or Carp::croak "required option 'signal' is missing";
1304 1335
1305 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1306
1307 if ($HAVE_ASYNC_INTERRUPT) { 1336 if ($HAVE_ASYNC_INTERRUPT) {
1308 # async::interrupt 1337 # async::interrupt
1338
1339 $signal = Async::Interrupt::sig2num ($signal);
1340 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1309 1341
1310 $SIG_ASY{$signal} ||= do { 1342 $SIG_ASY{$signal} ||= do {
1311 my $asy = new Async::Interrupt 1343 my $asy = new Async::Interrupt
1312 cb => sub { undef $SIG_EV{$signal} }, 1344 cb => sub { undef $SIG_EV{$signal} },
1313 signal => $signal, 1345 signal => $signal,
… …
1319 }; 1351 };
1320 1352
1321 } else { 1353 } else {
1322 # pure perl 1354 # pure perl
1323 1355
1356 # AE::Util has been loaded in signal
1357 $signal = AnyEvent::Util::sig2name ($signal);
1358 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1359
1324 $SIG{$signal} ||= sub { 1360 $SIG{$signal} ||= sub {
1325 local $!; 1361 local $!;
1326 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1362 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1327 undef $SIG_EV{$signal}; 1363 undef $SIG_EV{$signal};
1328 }; 1364 };
… …
1335 bless [$signal, $arg{cb}], "AnyEvent::Base::signal" 1371 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1336} 1372}
1337 1373
1338sub signal { 1374sub signal {
1339 # probe for availability of Async::Interrupt 1375 # probe for availability of Async::Interrupt
1340 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") {
1341 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;
1342 1378
1343 $HAVE_ASYNC_INTERRUPT = 1; 1379 $HAVE_ASYNC_INTERRUPT = 1;
1344 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1380 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1345 $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);
… …
1396our %PID_CB; 1432our %PID_CB;
1397our $CHLD_W; 1433our $CHLD_W;
1398our $CHLD_DELAY_W; 1434our $CHLD_DELAY_W;
1399our $WNOHANG; 1435our $WNOHANG;
1400 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
1401sub _sigchld { 1445sub _sigchld {
1446 my $pid;
1447
1448 AnyEvent->_emit_childstatus ($pid, $?)
1402 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1449 while ($pid = waitpid -1, $WNOHANG) > 0;
1403 $_->($pid, $?)
1404 for values %{ $PID_CB{$pid} || {} },
1405 values %{ $PID_CB{0} || {} };
1406 }
1407} 1450}
1408 1451
1409sub child { 1452sub child {
1410 my (undef, %arg) = @_; 1453 my (undef, %arg) = @_;
1411 1454
… …
2313 2356
2314=item L<JSON> and L<JSON::XS> 2357=item L<JSON> and L<JSON::XS>
2315 2358
2316This module is required when you want to read or write JSON data via 2359This 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 2360L<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. 2361advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2319 2362
2320In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is 2363In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2321installed. 2364installed.
2322 2365
2323=item L<Net::SSLeay> 2366=item L<Net::SSLeay>
… …
2390L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2433L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2391 2434
2392Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2435Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2393L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2436L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2394L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2437L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2395L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>. 2438L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>.
2396 2439
2397Non-blocking file handles, sockets, TCP clients and 2440Non-blocking file handles, sockets, TCP clients and
2398servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2441servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2399 2442
2400Asynchronous DNS: L<AnyEvent::DNS>. 2443Asynchronous DNS: L<AnyEvent::DNS>.

Diff Legend

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