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.245 by root, Sat Jul 18 05:19:09 2009 UTC vs.
Revision 1.248 by root, Sat Jul 18 22:27:10 2009 UTC

… …
368 368
369This watcher might use C<%SIG> (depending on the event loop used), 369This watcher might use C<%SIG> (depending on the event loop used),
370so programs overwriting those signals directly will likely not work 370so programs overwriting those signals directly will likely not work
371correctly. 371correctly.
372 372
373Example: exit on SIGINT
374
375 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
376
377=head3 Signal Races, Delays and Workarounds
378
373Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not 379Many 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 380callbacks 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 381race-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 382in some cases, signals will be delayed. The maximum time a signal might
377be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 383be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
378seconds). This variable can be changed only before the first signal 384seconds). This variable can be changed only before the first signal
379watcher is created, and should be left alone otherwise. Higher values 385watcher is created, and should be left alone otherwise. Higher values
380will cause fewer spurious wake-ups, which is better for power and CPU 386will cause fewer spurious wake-ups, which is better for power and CPU
381saving. All these problems can be avoided by installing the optional 387saving. All these problems can be avoided by installing the optional
382L<Async::Interrupt> module. 388L<Async::Interrupt> module. This will not work with inherently broken
383 389event loops such as L<Event> or L<Event::Lib> (and not with L<POE>
384Example: exit on SIGINT 390currently, as POE does it's own workaround with one-second latency). With
385 391those, you just have to suffer the delays.
386 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
387 392
388=head2 CHILD PROCESS WATCHERS 393=head2 CHILD PROCESS WATCHERS
389 394
390You can also watch on a child process exit and catch its exit status. 395You can also watch on a child process exit and catch its exit status.
391 396
… …
1270 $_->() for values %{ $SIG_CB{$_} || {} }; 1275 $_->() for values %{ $SIG_CB{$_} || {} };
1271 } 1276 }
1272 } 1277 }
1273} 1278}
1274 1279
1280# install a dumym wakeupw atcher to reduce signal catching latency
1281sub _sig_add() {
1282 unless ($SIG_COUNT++) {
1283 # try to align timer on a full-second boundary, if possible
1284 my $NOW = AnyEvent->now;
1285
1286 $SIG_TW = AnyEvent->timer (
1287 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1288 interval => $MAX_SIGNAL_LATENCY,
1289 cb => sub { }, # just for the PERL_ASYNC_CHECK
1290 );
1291 }
1292}
1293
1294sub _sig_del {
1295 undef $SIG_TW
1296 unless --$SIG_COUNT;
1297}
1298
1275sub _signal { 1299sub _signal {
1276 my (undef, %arg) = @_; 1300 my (undef, %arg) = @_;
1277 1301
1278 my $signal = uc $arg{signal} 1302 my $signal = uc $arg{signal}
1279 or Carp::croak "required option 'signal' is missing"; 1303 or Carp::croak "required option 'signal' is missing";
… …
1303 undef $SIG_EV{$signal}; 1327 undef $SIG_EV{$signal};
1304 }; 1328 };
1305 1329
1306 # can't do signal processing without introducing races in pure perl, 1330 # can't do signal processing without introducing races in pure perl,
1307 # so limit the signal latency. 1331 # so limit the signal latency.
1308 ++$SIG_COUNT; 1332 _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 } 1333 }
1315 1334
1316 bless [$signal, $arg{cb}], "AnyEvent::Base::signal" 1335 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1317} 1336}
1318 1337
… …
1357} 1376}
1358 1377
1359sub AnyEvent::Base::signal::DESTROY { 1378sub AnyEvent::Base::signal::DESTROY {
1360 my ($signal, $cb) = @{$_[0]}; 1379 my ($signal, $cb) = @{$_[0]};
1361 1380
1362 undef $SIG_TW 1381 _sig_del;
1363 unless --$SIG_COUNT;
1364 1382
1365 delete $SIG_CB{$signal}{$cb}; 1383 delete $SIG_CB{$signal}{$cb};
1366 1384
1367 $HAVE_ASYNC_INTERRUPT 1385 $HAVE_ASYNC_INTERRUPT
1368 ? delete $SIG_ASY{$signal} 1386 ? delete $SIG_ASY{$signal}
… …
2257 2275
2258This slightly arcane module is used to implement fast signal handling: To 2276This slightly arcane module is used to implement fast signal handling: To
2259my knowledge, there is no way to do completely race-free and quick 2277my knowledge, there is no way to do completely race-free and quick
2260signal handling in pure perl. To ensure that signals still get 2278signal handling in pure perl. To ensure that signals still get
2261delivered, AnyEvent will start an interval timer to wake up perl (and 2279delivered, AnyEvent will start an interval timer to wake up perl (and
2262catch the signals) with soemd elay (default is 10 seconds, look for 2280catch the signals) with some delay (default is 10 seconds, look for
2263C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2281C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2264 2282
2265If this module is available, then it will be used to implement signal 2283If this module is available, then it will be used to implement signal
2266catching, which means that signals will not be delayed, and the event loop 2284catching, which means that signals will not be delayed, and the event loop
2267will not be interrupted regularly, which is more efficient (And good for 2285will not be interrupted regularly, which is more efficient (And good for
2268battery life on laptops). 2286battery life on laptops).
2269 2287
2270This affects not just the pure-perl event loop, but also other event loops 2288This affects not just the pure-perl event loop, but also other event loops
2271that have no signal handling on their own (e.g. Glib, Tk, Qt). 2289that have no signal handling on their own (e.g. Glib, Tk, Qt).
2290
2291Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2292and either employ their own workarounds (POE) or use AnyEvent's workaround
2293(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2294does nothing for those backends.
2272 2295
2273=item L<EV> 2296=item L<EV>
2274 2297
2275This module isn't really "optional", as it is simply one of the backend 2298This module isn't really "optional", as it is simply one of the backend
2276event loops that AnyEvent can use. However, it is simply the best event 2299event loops that AnyEvent can use. However, it is simply the best event
… …
2290 2313
2291=item L<JSON> and L<JSON::XS> 2314=item L<JSON> and L<JSON::XS>
2292 2315
2293This module is required when you want to read or write JSON data via 2316This module is required when you want to read or write JSON data via
2294L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2317L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2295advantage of the ulta-high-speed L<JSON::XS> module when it is installed. 2318advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2296 2319
2297In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is 2320In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2298installed. 2321installed.
2299 2322
2300=item L<Net::SSLeay> 2323=item L<Net::SSLeay>

Diff Legend

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