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.244 by root, Fri Jul 17 23:15:57 2009 UTC vs.
Revision 1.259 by root, Tue Jul 28 02:07:18 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?
… …
368 376
369This watcher might use C<%SIG> (depending on the event loop used), 377This watcher might use C<%SIG> (depending on the event loop used),
370so programs overwriting those signals directly will likely not work 378so programs overwriting those signals directly will likely not work
371correctly. 379correctly.
372 380
381Example: exit on SIGINT
382
383 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
384
385=head3 Signal Races, Delays and Workarounds
386
373Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not 387Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
374support attaching callbacks to signals, which is a pity, as you cannot do 388callbacks to signals in a generic way, which is a pity, as you cannot do
375race-free signal handling in perl. AnyEvent will try to do it's best, but 389race-free signal handling in perl. AnyEvent will try to do it's best, but
376in some cases, signals will be delayed. The maximum time a signal might 390in some cases, signals will be delayed. The maximum time a signal might
377be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 391be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
378seconds). This variable can be changed only before the first signal 392seconds). This variable can be changed only before the first signal
379watcher is created, and should be left alone otherwise. Higher values 393watcher is created, and should be left alone otherwise. Higher values
380will cause fewer spurious wake-ups, which is better for power and CPU 394will cause fewer spurious wake-ups, which is better for power and CPU
381saving. All these problems can be avoided by installing the optional 395saving. All these problems can be avoided by installing the optional
382L<Async::Interrupt> module. 396L<Async::Interrupt> module. This will not work with inherently broken
383 397event loops such as L<Event> or L<Event::Lib> (and not with L<POE>
384Example: exit on SIGINT 398currently, as POE does it's own workaround with one-second latency). With
385 399those, you just have to suffer the delays.
386 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
387 400
388=head2 CHILD PROCESS WATCHERS 401=head2 CHILD PROCESS WATCHERS
389 402
390You 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.
391 404
392The 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,
393watches for any child process exit). The watcher will triggered only when 406using C<0> watches for any child process exit, on others this will
394the child process has finished and an exit status is available, not on 407croak). The watcher will be triggered only when the child process has
395any trace events (stopped/continued). 408finished and an exit status is available, not on any trace events
409(stopped/continued).
396 410
397The 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
398waitpid), 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
399callback arguments. 413callback arguments.
400 414
… …
504Condition variables are similar to callbacks, except that you can 518Condition variables are similar to callbacks, except that you can
505optionally wait for them. They can also be called merge points - points 519optionally wait for them. They can also be called merge points - points
506in time where multiple outstanding events have been processed. And yet 520in time where multiple outstanding events have been processed. And yet
507another way to call them is transactions - each condition variable can be 521another way to call them is transactions - each condition variable can be
508used to represent a transaction, which finishes at some point and delivers 522used to represent a transaction, which finishes at some point and delivers
509a result. 523a result. And yet some people know them as "futures" - a promise to
524compute/deliver something that you can wait for.
510 525
511Condition variables are very useful to signal that something has finished, 526Condition variables are very useful to signal that something has finished,
512for example, if you write a module that does asynchronous http requests, 527for example, if you write a module that does asynchronous http requests,
513then a condition variable would be the ideal candidate to signal the 528then a condition variable would be the ideal candidate to signal the
514availability of results. The user can either act when the callback is 529availability of results. The user can either act when the callback is
… …
782 797
783 AnyEvent::Impl::Glib based on Glib, slow but very stable. 798 AnyEvent::Impl::Glib based on Glib, slow but very stable.
784 AnyEvent::Impl::Tk based on Tk, very broken. 799 AnyEvent::Impl::Tk based on Tk, very broken.
785 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 800 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
786 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.
787 803
788=item Backends with special needs. 804=item Backends with special needs.
789 805
790Qt requires the Qt::Application to be instantiated first, but will 806Qt requires the Qt::Application to be instantiated first, but will
791otherwise be picked up automatically. As long as the main program 807otherwise be picked up automatically. As long as the main program
… …
865event module detection too early, for example, L<AnyEvent::AIO> creates 881event module detection too early, for example, L<AnyEvent::AIO> creates
866and 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
867avoid autodetecting the event module at load time. 883avoid autodetecting the event module at load time.
868 884
869If 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
870that 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
871L<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;
872 905
873=item @AnyEvent::post_detect 906=item @AnyEvent::post_detect
874 907
875If 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
876before or after loading AnyEvent), then they will called directly after 909before or after loading AnyEvent), then they will called directly after
… …
1053 1086
1054BEGIN { AnyEvent::common_sense } 1087BEGIN { AnyEvent::common_sense }
1055 1088
1056use Carp (); 1089use Carp ();
1057 1090
1058our $VERSION = 4.83; 1091our $VERSION = 4.88;
1059our $MODEL; 1092our $MODEL;
1060 1093
1061our $AUTOLOAD; 1094our $AUTOLOAD;
1062our @ISA; 1095our @ISA;
1063 1096
… …
1088 for reverse split /\s*,\s*/, 1121 for reverse split /\s*,\s*/,
1089 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1122 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1090} 1123}
1091 1124
1092my @models = ( 1125my @models = (
1093 [EV:: => AnyEvent::Impl::EV::], 1126 [EV:: => AnyEvent::Impl::EV:: , 1],
1094 [Event:: => AnyEvent::Impl::Event::], 1127 [Event:: => AnyEvent::Impl::Event::, 1],
1095 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1128 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1096 # everything below here will not be autoprobed 1129 # everything below here will not (normally) be autoprobed
1097 # as the pureperl backend should work everywhere 1130 # as the pureperl backend should work everywhere
1098 # and is usually faster 1131 # and is usually faster
1099 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1132 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1100 [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
1101 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1135 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1102 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1136 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1103 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1137 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1104 [Wx:: => AnyEvent::Impl::POE::], 1138 [Wx:: => AnyEvent::Impl::POE::],
1105 [Prima:: => AnyEvent::Impl::POE::], 1139 [Prima:: => AnyEvent::Impl::POE::],
1106 # 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
1107 # byzantine signal and broken child handling, among others. 1141 # byzantine signal and broken child handling, among others.
1108 # 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
1109 # obvious default class. 1143 # obvious default class.
1110# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1144# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1111# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1145# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1112# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1146# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1113); 1147);
1114 1148
1115our %method = map +($_ => 1), 1149our %method = map +($_ => 1),
1116 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);
1117 1151
… …
1121 my ($cb) = @_; 1155 my ($cb) = @_;
1122 1156
1123 if ($MODEL) { 1157 if ($MODEL) {
1124 $cb->(); 1158 $cb->();
1125 1159
1126 1 1160 undef
1127 } else { 1161 } else {
1128 push @post_detect, $cb; 1162 push @post_detect, $cb;
1129 1163
1130 defined wantarray 1164 defined wantarray
1131 ? bless \$cb, "AnyEvent::Util::postdetect" 1165 ? bless \$cb, "AnyEvent::Util::postdetect"
… …
1163 } 1197 }
1164 } 1198 }
1165 } 1199 }
1166 1200
1167 unless ($MODEL) { 1201 unless ($MODEL) {
1168 # try to load a model 1202 # try to autoload a model
1169
1170 for (@REGISTRY, @models) { 1203 for (@REGISTRY, @models) {
1171 my ($package, $model) = @$_; 1204 my ($package, $model, $autoload) = @$_;
1205 if (
1206 $autoload
1172 if (eval "require $package" 1207 and eval "require $package"
1173 and ${"$package\::VERSION"} > 0 1208 and ${"$package\::VERSION"} > 0
1174 and eval "require $model") { 1209 and eval "require $model"
1210 ) {
1175 $MODEL = $model; 1211 $MODEL = $model;
1176 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2; 1212 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1177 last; 1213 last;
1178 } 1214 }
1179 } 1215 }
1180 1216
1181 $MODEL 1217 $MODEL
… …
1270 $_->() for values %{ $SIG_CB{$_} || {} }; 1306 $_->() for values %{ $SIG_CB{$_} || {} };
1271 } 1307 }
1272 } 1308 }
1273} 1309}
1274 1310
1311# install a dumym wakeupw atcher to reduce signal catching latency
1312sub _sig_add() {
1313 unless ($SIG_COUNT++) {
1314 # try to align timer on a full-second boundary, if possible
1315 my $NOW = AnyEvent->now;
1316
1317 $SIG_TW = AnyEvent->timer (
1318 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1319 interval => $MAX_SIGNAL_LATENCY,
1320 cb => sub { }, # just for the PERL_ASYNC_CHECK
1321 );
1322 }
1323}
1324
1325sub _sig_del {
1326 undef $SIG_TW
1327 unless --$SIG_COUNT;
1328}
1329
1275sub _signal { 1330sub _signal {
1276 my (undef, %arg) = @_; 1331 my (undef, %arg) = @_;
1277 1332
1278 my $signal = uc $arg{signal} 1333 my $signal = uc $arg{signal}
1279 or Carp::croak "required option 'signal' is missing"; 1334 or Carp::croak "required option 'signal' is missing";
… …
1303 undef $SIG_EV{$signal}; 1358 undef $SIG_EV{$signal};
1304 }; 1359 };
1305 1360
1306 # can't do signal processing without introducing races in pure perl, 1361 # can't do signal processing without introducing races in pure perl,
1307 # so limit the signal latency. 1362 # so limit the signal latency.
1308 ++$SIG_COUNT; 1363 _sig_add;
1309 $SIG_TW ||= AnyEvent->timer (
1310 after => $MAX_SIGNAL_LATENCY,
1311 interval => $MAX_SIGNAL_LATENCY,
1312 cb => sub { }, # just for the PERL_ASYNC_CHECK
1313 );
1314 } 1364 }
1315 1365
1316 bless [$signal, $arg{cb}], "AnyEvent::Base::signal" 1366 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1317} 1367}
1318 1368
… …
1357} 1407}
1358 1408
1359sub AnyEvent::Base::signal::DESTROY { 1409sub AnyEvent::Base::signal::DESTROY {
1360 my ($signal, $cb) = @{$_[0]}; 1410 my ($signal, $cb) = @{$_[0]};
1361 1411
1362 undef $SIG_TW 1412 _sig_del;
1363 unless --$SIG_COUNT;
1364 1413
1365 delete $SIG_CB{$signal}{$cb}; 1414 delete $SIG_CB{$signal}{$cb};
1366 1415
1416 $HAVE_ASYNC_INTERRUPT
1417 ? delete $SIG_ASY{$signal}
1367 # delete doesn't work with older perls - they then 1418 : # delete doesn't work with older perls - they then
1368 # print weird messages, or just unconditionally exit 1419 # print weird messages, or just unconditionally exit
1369 # instead of getting the default action. 1420 # instead of getting the default action.
1370 undef $SIG{$signal} 1421 undef $SIG{$signal}
1371 unless keys %{ $SIG_CB{$signal} }; 1422 unless keys %{ $SIG_CB{$signal} };
1372} 1423}
1373 1424
1374# default implementation for ->child 1425# default implementation for ->child
1375 1426
1376our %PID_CB; 1427our %PID_CB;
1377our $CHLD_W; 1428our $CHLD_W;
1378our $CHLD_DELAY_W; 1429our $CHLD_DELAY_W;
1379our $WNOHANG; 1430our $WNOHANG;
1380 1431
1432sub _emit_childstatus($$) {
1433 my (undef, $rpid, $rstatus) = @_;
1434
1435 $_->($rpid, $rstatus)
1436 for values %{ $PID_CB{$rpid} || {} },
1437 values %{ $PID_CB{0} || {} };
1438}
1439
1381sub _sigchld { 1440sub _sigchld {
1441 my $pid;
1442
1443 AnyEvent->_emit_childstatus ($pid, $?)
1382 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1444 while ($pid = waitpid -1, $WNOHANG) > 0;
1383 $_->($pid, $?)
1384 for values %{ $PID_CB{$pid} || {} },
1385 values %{ $PID_CB{0} || {} };
1386 }
1387} 1445}
1388 1446
1389sub child { 1447sub child {
1390 my (undef, %arg) = @_; 1448 my (undef, %arg) = @_;
1391 1449
… …
2255 2313
2256This slightly arcane module is used to implement fast signal handling: To 2314This slightly arcane module is used to implement fast signal handling: To
2257my knowledge, there is no way to do completely race-free and quick 2315my knowledge, there is no way to do completely race-free and quick
2258signal handling in pure perl. To ensure that signals still get 2316signal handling in pure perl. To ensure that signals still get
2259delivered, AnyEvent will start an interval timer to wake up perl (and 2317delivered, AnyEvent will start an interval timer to wake up perl (and
2260catch the signals) with soemd elay (default is 10 seconds, look for 2318catch the signals) with some delay (default is 10 seconds, look for
2261C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2319C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2262 2320
2263If this module is available, then it will be used to implement signal 2321If this module is available, then it will be used to implement signal
2264catching, which means that signals will not be delayed, and the event loop 2322catching, which means that signals will not be delayed, and the event loop
2265will not be interrupted regularly, which is more efficient (And good for 2323will not be interrupted regularly, which is more efficient (And good for
2266battery life on laptops). 2324battery life on laptops).
2267 2325
2268This affects not just the pure-perl event loop, but also other event loops 2326This affects not just the pure-perl event loop, but also other event loops
2269that have no signal handling on their own (e.g. Glib, Tk, Qt). 2327that have no signal handling on their own (e.g. Glib, Tk, Qt).
2328
2329Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2330and either employ their own workarounds (POE) or use AnyEvent's workaround
2331(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2332does nothing for those backends.
2270 2333
2271=item L<EV> 2334=item L<EV>
2272 2335
2273This module isn't really "optional", as it is simply one of the backend 2336This module isn't really "optional", as it is simply one of the backend
2274event loops that AnyEvent can use. However, it is simply the best event 2337event loops that AnyEvent can use. However, it is simply the best event
… …
2288 2351
2289=item L<JSON> and L<JSON::XS> 2352=item L<JSON> and L<JSON::XS>
2290 2353
2291This module is required when you want to read or write JSON data via 2354This module is required when you want to read or write JSON data via
2292L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2355L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2293advantage of the ulta-high-speed L<JSON::XS> module when it is installed. 2356advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2294 2357
2295In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is 2358In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2296installed. 2359installed.
2297 2360
2298=item L<Net::SSLeay> 2361=item L<Net::SSLeay>
… …
2365L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2428L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2366 2429
2367Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2430Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2368L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2431L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2369L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2432L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2370L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>. 2433L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>.
2371 2434
2372Non-blocking file handles, sockets, TCP clients and 2435Non-blocking file handles, sockets, TCP clients and
2373servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2436servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2374 2437
2375Asynchronous DNS: L<AnyEvent::DNS>. 2438Asynchronous DNS: L<AnyEvent::DNS>.

Diff Legend

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