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.243 by root, Fri Jul 17 23:12:20 2009 UTC vs.
Revision 1.247 by root, Sat Jul 18 22:24:17 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
… …
1053 1058
1054BEGIN { AnyEvent::common_sense } 1059BEGIN { AnyEvent::common_sense }
1055 1060
1056use Carp (); 1061use Carp ();
1057 1062
1058our $VERSION = 4.83; 1063our $VERSION = 4.85;
1059our $MODEL; 1064our $MODEL;
1060 1065
1061our $AUTOLOAD; 1066our $AUTOLOAD;
1062our @ISA; 1067our @ISA;
1063 1068
… …
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
1385 $HAVE_ASYNC_INTERRUPT
1386 ? delete $SIG_ASY{$signal}
1367 # delete doesn't work with older perls - they then 1387 : # delete doesn't work with older perls - they then
1368 # print weird messages, or just unconditionally exit 1388 # print weird messages, or just unconditionally exit
1369 # instead of getting the default action. 1389 # instead of getting the default action.
1370 undef $SIG{$signal} 1390 undef $SIG{$signal}
1371 unless keys %{ $SIG_CB{$signal} }; 1391 unless keys %{ $SIG_CB{$signal} };
1372} 1392}
1373 1393
1374# default implementation for ->child 1394# default implementation for ->child
1375 1395
… …
1566C<PERL_ANYEVENT_MODEL>. 1586C<PERL_ANYEVENT_MODEL>.
1567 1587
1568When set to C<2> or higher, cause AnyEvent to report to STDERR which event 1588When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1569model it chooses. 1589model it chooses.
1570 1590
1591When set to C<8> or higher, then AnyEvent will report extra information on
1592which optional modules it loads and how it implements certain features.
1593
1571=item C<PERL_ANYEVENT_STRICT> 1594=item C<PERL_ANYEVENT_STRICT>
1572 1595
1573AnyEvent does not do much argument checking by default, as thorough 1596AnyEvent does not do much argument checking by default, as thorough
1574argument checking is very costly. Setting this variable to a true value 1597argument checking is very costly. Setting this variable to a true value
1575will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly 1598will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
… …
1651 1674
1652When neither C<ca_file> nor C<ca_path> was specified during 1675When neither C<ca_file> nor C<ca_path> was specified during
1653L<AnyEvent::TLS> context creation, and either of these environment 1676L<AnyEvent::TLS> context creation, and either of these environment
1654variables exist, they will be used to specify CA certificate locations 1677variables exist, they will be used to specify CA certificate locations
1655instead of a system-dependent default. 1678instead of a system-dependent default.
1679
1680=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1681
1682When these are set to C<1>, then the respective modules are not
1683loaded. Mostly good for testing AnyEvent itself.
1656 1684
1657=back 1685=back
1658 1686
1659=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1687=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1660 1688
… …
2247 2275
2248This slightly arcane module is used to implement fast signal handling: To 2276This slightly arcane module is used to implement fast signal handling: To
2249my 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
2250signal handling in pure perl. To ensure that signals still get 2278signal handling in pure perl. To ensure that signals still get
2251delivered, AnyEvent will start an interval timer to wake up perl (and 2279delivered, AnyEvent will start an interval timer to wake up perl (and
2252catch the signals) with soemd elay (default is 10 seconds, look for 2280catch the signals) with some delay (default is 10 seconds, look for
2253C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2281C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2254 2282
2255If 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
2256catching, 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
2257will not be interrupted regularly, which is more efficient (And good for 2285will not be interrupted regularly, which is more efficient (And good for
2258battery life on laptops). 2286battery life on laptops).
2259 2287
2260This 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
2261that 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.
2262 2295
2263=item L<EV> 2296=item L<EV>
2264 2297
2265This 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
2266event 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

Diff Legend

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