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.261 by root, Tue Jul 28 12:56:17 2009 UTC vs.
Revision 1.271 by root, Wed Aug 5 20:50:27 2009 UTC

… …
181my variables are only visible after the statement in which they are 181my variables are only visible after the statement in which they are
182declared. 182declared.
183 183
184=head2 I/O WATCHERS 184=head2 I/O WATCHERS
185 185
186 $w = AnyEvent->io (
187 fh => <filehandle_or_fileno>,
188 poll => <"r" or "w">,
189 cb => <callback>,
190 );
191
186You can create an I/O watcher by calling the C<< AnyEvent->io >> method 192You can create an I/O watcher by calling the C<< AnyEvent->io >> method
187with the following mandatory key-value pairs as arguments: 193with the following mandatory key-value pairs as arguments:
188 194
189C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch 195C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
190for events (AnyEvent might or might not keep a reference to this file 196for events (AnyEvent might or might not keep a reference to this file
… …
219 undef $w; 225 undef $w;
220 }); 226 });
221 227
222=head2 TIME WATCHERS 228=head2 TIME WATCHERS
223 229
230 $w = AnyEvent->timer (after => <seconds>, cb => <callback>);
231
232 $w = AnyEvent->timer (
233 after => <fractional_seconds>,
234 interval => <fractional_seconds>,
235 cb => <callback>,
236 );
237
224You can create a time watcher by calling the C<< AnyEvent->timer >> 238You can create a time watcher by calling the C<< AnyEvent->timer >>
225method with the following mandatory arguments: 239method with the following mandatory arguments:
226 240
227C<after> specifies after how many seconds (fractional values are 241C<after> specifies after how many seconds (fractional values are
228supported) the callback should be invoked. C<cb> is the callback to invoke 242supported) the callback should be invoked. C<cb> is the callback to invoke
… …
355 369
356=back 370=back
357 371
358=head2 SIGNAL WATCHERS 372=head2 SIGNAL WATCHERS
359 373
374 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
375
360You can watch for signals using a signal watcher, C<signal> is the signal 376You can watch for signals using a signal watcher, C<signal> is the signal
361I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl 377I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
362callback to be invoked whenever a signal occurs. 378callback to be invoked whenever a signal occurs.
363 379
364Although the callback might get passed parameters, their value and 380Although the callback might get passed parameters, their value and
… …
383 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 399 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
384 400
385=head3 Signal Races, Delays and Workarounds 401=head3 Signal Races, Delays and Workarounds
386 402
387Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 403Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
388callbacks to signals in a generic way, which is a pity, as you cannot do 404callbacks to signals in a generic way, which is a pity, as you cannot
389race-free signal handling in perl. AnyEvent will try to do it's best, but 405do race-free signal handling in perl, requiring C libraries for
406this. AnyEvent will try to do it's best, which means in some cases,
390in some cases, signals will be delayed. The maximum time a signal might 407signals will be delayed. The maximum time a signal might be delayed is
391be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 408specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This
392seconds). This variable can be changed only before the first signal 409variable can be changed only before the first signal watcher is created,
393watcher is created, and should be left alone otherwise. Higher values 410and should be left alone otherwise. This variable determines how often
411AnyEvent polls for signals (in case a wake-up was missed). Higher values
394will cause fewer spurious wake-ups, which is better for power and CPU 412will cause fewer spurious wake-ups, which is better for power and CPU
413saving.
414
395saving. All these problems can be avoided by installing the optional 415All these problems can be avoided by installing the optional
396L<Async::Interrupt> module. This will not work with inherently broken 416L<Async::Interrupt> module, which works with most event loops. It will not
397event loops such as L<Event> or L<Event::Lib> (and not with L<POE> 417work with inherently broken event loops such as L<Event> or L<Event::Lib>
398currently, as POE does it's own workaround with one-second latency). With 418(and not with L<POE> currently, as POE does it's own workaround with
399those, you just have to suffer the delays. 419one-second latency). For those, you just have to suffer the delays.
400 420
401=head2 CHILD PROCESS WATCHERS 421=head2 CHILD PROCESS WATCHERS
422
423 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
402 424
403You can also watch on a child process exit and catch its exit status. 425You can also watch on a child process exit and catch its exit status.
404 426
405The child process is specified by the C<pid> argument (one some backends, 427The child process is specified by the C<pid> argument (one some backends,
406using C<0> watches for any child process exit, on others this will 428using C<0> watches for any child process exit, on others this will
… …
455 # do something else, then wait for process exit 477 # do something else, then wait for process exit
456 $done->recv; 478 $done->recv;
457 479
458=head2 IDLE WATCHERS 480=head2 IDLE WATCHERS
459 481
482 $w = AnyEvent->idle (cb => <callback>);
483
460Sometimes there is a need to do something, but it is not so important 484Sometimes there is a need to do something, but it is not so important
461to do it instantly, but only when there is nothing better to do. This 485to do it instantly, but only when there is nothing better to do. This
462"nothing better to do" is usually defined to be "no other events need 486"nothing better to do" is usually defined to be "no other events need
463attention by the event loop". 487attention by the event loop".
464 488
… …
490 }); 514 });
491 }); 515 });
492 516
493=head2 CONDITION VARIABLES 517=head2 CONDITION VARIABLES
494 518
519 $cv = AnyEvent->condvar;
520
521 $cv->send (<list>);
522 my @res = $cv->recv;
523
495If you are familiar with some event loops you will know that all of them 524If you are familiar with some event loops you will know that all of them
496require you to run some blocking "loop", "run" or similar function that 525require you to run some blocking "loop", "run" or similar function that
497will actively watch for new events and call your callbacks. 526will actively watch for new events and call your callbacks.
498 527
499AnyEvent is slightly different: it expects somebody else to run the event 528AnyEvent is slightly different: it expects somebody else to run the event
… …
761=item $cb = $cv->cb ($cb->($cv)) 790=item $cb = $cv->cb ($cb->($cv))
762 791
763This is a mutator function that returns the callback set and optionally 792This is a mutator function that returns the callback set and optionally
764replaces it before doing so. 793replaces it before doing so.
765 794
766The callback will be called when the condition becomes "true", i.e. when 795The callback will be called when the condition becomes (or already was)
767C<send> or C<croak> are called, with the only argument being the condition 796"true", i.e. when C<send> or C<croak> are called (or were called), with
768variable itself. Calling C<recv> inside the callback or at any later time 797the only argument being the condition variable itself. Calling C<recv>
769is guaranteed not to block. 798inside the callback or at any later time is guaranteed not to block.
770 799
771=back 800=back
772 801
773=head1 SUPPORTED EVENT LOOPS/BACKENDS 802=head1 SUPPORTED EVENT LOOPS/BACKENDS
774 803
… …
1086 1115
1087BEGIN { AnyEvent::common_sense } 1116BEGIN { AnyEvent::common_sense }
1088 1117
1089use Carp (); 1118use Carp ();
1090 1119
1091our $VERSION = 4.881; 1120our $VERSION = 4.901;
1092our $MODEL; 1121our $MODEL;
1093 1122
1094our $AUTOLOAD; 1123our $AUTOLOAD;
1095our @ISA; 1124our @ISA;
1096 1125
… …
1289} 1318}
1290 1319
1291# default implementation for ->signal 1320# default implementation for ->signal
1292 1321
1293our $HAVE_ASYNC_INTERRUPT; 1322our $HAVE_ASYNC_INTERRUPT;
1323
1324sub _have_async_interrupt() {
1325 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT}
1326 && eval "use Async::Interrupt 1.0 (); 1")
1327 unless defined $HAVE_ASYNC_INTERRUPT;
1328
1329 $HAVE_ASYNC_INTERRUPT
1330}
1331
1294our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1332our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1295our (%SIG_ASY, %SIG_ASY_W); 1333our (%SIG_ASY, %SIG_ASY_W);
1296our ($SIG_COUNT, $SIG_TW); 1334our ($SIG_COUNT, $SIG_TW);
1297 1335
1298sub _signal_exec { 1336sub _signal_exec {
… …
1325sub _sig_del { 1363sub _sig_del {
1326 undef $SIG_TW 1364 undef $SIG_TW
1327 unless --$SIG_COUNT; 1365 unless --$SIG_COUNT;
1328} 1366}
1329 1367
1368our $_sig_name_init; $_sig_name_init = sub {
1369 eval q{ # poor man's autoloading
1370 undef $_sig_name_init;
1371
1372 if (_have_async_interrupt) {
1373 *sig2num = \&Async::Interrupt::sig2num;
1374 *sig2name = \&Async::Interrupt::sig2name;
1375 } else {
1376 require Config;
1377
1378 my %signame2num;
1379 @signame2num{ split ' ', $Config::Config{sig_name} }
1380 = split ' ', $Config::Config{sig_num};
1381
1382 my @signum2name;
1383 @signum2name[values %signame2num] = keys %signame2num;
1384
1385 *sig2num = sub($) {
1386 $_[0] > 0 ? shift : $signame2num{+shift}
1387 };
1388 *sig2name = sub ($) {
1389 $_[0] > 0 ? $signum2name[+shift] : shift
1390 };
1391 }
1392 };
1393 die if $@;
1394};
1395
1396sub sig2num ($) { &$_sig_name_init; &sig2num }
1397sub sig2name($) { &$_sig_name_init; &sig2name }
1398
1330sub _signal { 1399sub signal {
1400 eval q{ # poor man's autoloading {}
1401 # probe for availability of Async::Interrupt
1402 if (_have_async_interrupt) {
1403 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1404
1405 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1406 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1407
1408 } else {
1409 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1410
1411 require Fcntl;
1412
1413 if (AnyEvent::WIN32) {
1414 require AnyEvent::Util;
1415
1416 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1417 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
1418 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case
1419 } else {
1420 pipe $SIGPIPE_R, $SIGPIPE_W;
1421 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
1422 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
1423
1424 # not strictly required, as $^F is normally 2, but let's make sure...
1425 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1426 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1427 }
1428
1429 $SIGPIPE_R
1430 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1431
1432 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1433 }
1434
1435 *signal = sub {
1331 my (undef, %arg) = @_; 1436 my (undef, %arg) = @_;
1332 1437
1333 my $signal = uc $arg{signal} 1438 my $signal = uc $arg{signal}
1334 or Carp::croak "required option 'signal' is missing"; 1439 or Carp::croak "required option 'signal' is missing";
1335 1440
1336 if ($HAVE_ASYNC_INTERRUPT) { 1441 if ($HAVE_ASYNC_INTERRUPT) {
1337 # async::interrupt 1442 # async::interrupt
1338 1443
1339 $signal = Async::Interrupt::sig2num ($signal); 1444 $signal = sig2num $signal;
1340 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1445 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1341 1446
1342 $SIG_ASY{$signal} ||= do { 1447 $SIG_ASY{$signal} ||= new Async::Interrupt
1343 my $asy = new Async::Interrupt
1344 cb => sub { undef $SIG_EV{$signal} }, 1448 cb => sub { undef $SIG_EV{$signal} },
1345 signal => $signal, 1449 signal => $signal,
1346 pipe => [$SIGPIPE_R->filenos], 1450 pipe => [$SIGPIPE_R->filenos],
1451 pipe_autodrain => 0,
1452 ;
1453
1454 } else {
1455 # pure perl
1456
1457 # AE::Util has been loaded in signal
1458 $signal = sig2name $signal;
1459 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1460
1461 $SIG{$signal} ||= sub {
1462 local $!;
1463 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1464 undef $SIG_EV{$signal};
1465 };
1466
1467 # can't do signal processing without introducing races in pure perl,
1468 # so limit the signal latency.
1469 _sig_add;
1347 ; 1470 }
1348 $asy->pipe_autodrain (0);
1349 1471
1350 $asy 1472 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1351 }; 1473 };
1352 1474
1353 } else { 1475 *AnyEvent::Base::signal::DESTROY = sub {
1354 # pure perl 1476 my ($signal, $cb) = @{$_[0]};
1355 1477
1356 # AE::Util has been loaded in signal 1478 _sig_del;
1357 $signal = AnyEvent::Util::sig2name ($signal);
1358 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1359 1479
1360 $SIG{$signal} ||= sub { 1480 delete $SIG_CB{$signal}{$cb};
1361 local $!; 1481
1362 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1482 $HAVE_ASYNC_INTERRUPT
1483 ? delete $SIG_ASY{$signal}
1484 : # delete doesn't work with older perls - they then
1485 # print weird messages, or just unconditionally exit
1486 # instead of getting the default action.
1363 undef $SIG_EV{$signal}; 1487 undef $SIG{$signal}
1488 unless keys %{ $SIG_CB{$signal} };
1364 }; 1489 };
1365
1366 # can't do signal processing without introducing races in pure perl,
1367 # so limit the signal latency.
1368 _sig_add;
1369 } 1490 };
1370 1491 die if $@;
1371 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1372}
1373
1374sub signal {
1375 # probe for availability of Async::Interrupt
1376 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 1.0 (); 1") {
1377 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1378
1379 $HAVE_ASYNC_INTERRUPT = 1;
1380 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1381 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1382
1383 } else {
1384 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1385
1386 require Fcntl;
1387
1388 if (AnyEvent::WIN32) {
1389 require AnyEvent::Util;
1390
1391 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1392 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R) if $SIGPIPE_R;
1393 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case
1394 } else {
1395 pipe $SIGPIPE_R, $SIGPIPE_W;
1396 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
1397 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
1398
1399 # not strictly required, as $^F is normally 2, but let's make sure...
1400 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1401 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1402 }
1403
1404 $SIGPIPE_R
1405 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1406
1407 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1408 }
1409
1410 *signal = \&_signal;
1411 &signal 1492 &signal
1412}
1413
1414sub AnyEvent::Base::signal::DESTROY {
1415 my ($signal, $cb) = @{$_[0]};
1416
1417 _sig_del;
1418
1419 delete $SIG_CB{$signal}{$cb};
1420
1421 $HAVE_ASYNC_INTERRUPT
1422 ? delete $SIG_ASY{$signal}
1423 : # delete doesn't work with older perls - they then
1424 # print weird messages, or just unconditionally exit
1425 # instead of getting the default action.
1426 undef $SIG{$signal}
1427 unless keys %{ $SIG_CB{$signal} };
1428} 1493}
1429 1494
1430# default implementation for ->child 1495# default implementation for ->child
1431 1496
1432our %PID_CB; 1497our %PID_CB;
… …
1569 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak}; 1634 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak};
1570 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0] 1635 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0]
1571} 1636}
1572 1637
1573sub cb { 1638sub cb {
1574 $_[0]{_ae_cb} = $_[1] if @_ > 1; 1639 my $cv = shift;
1640
1641 @_
1642 and $cv->{_ae_cb} = shift
1643 and $cv->{_ae_sent}
1644 and (delete $cv->{_ae_cb})->($cv);
1645
1575 $_[0]{_ae_cb} 1646 $cv->{_ae_cb}
1576} 1647}
1577 1648
1578sub begin { 1649sub begin {
1579 ++$_[0]{_ae_counter}; 1650 ++$_[0]{_ae_counter};
1580 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 1651 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
… …
1586} 1657}
1587 1658
1588# undocumented/compatibility with pre-3.4 1659# undocumented/compatibility with pre-3.4
1589*broadcast = \&send; 1660*broadcast = \&send;
1590*wait = \&_wait; 1661*wait = \&_wait;
1662
1663#############################################################################
1664# "new" API, currently only emulation of it
1665#############################################################################
1666
1667package AE;
1668
1669sub io($$$) {
1670 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1671}
1672
1673sub timer($$$) {
1674 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]);
1675}
1676
1677sub signal($$) {
1678 AnyEvent->signal (signal => $_[0], cb => $_[1]);
1679}
1680
1681sub child($$) {
1682 AnyEvent->child (pid => $_[0], cb => $_[1]);
1683}
1684
1685sub idle($) {
1686 AnyEvent->idle (cb => $_[0]);
1687}
1688
1689sub cv() {
1690 AnyEvent->condvar
1691}
1692
1693sub now() {
1694 AnyEvent->now
1695}
1696
1697sub now_update() {
1698 AnyEvent->now_update
1699}
1700
1701sub time() {
1702 AnyEvent->time
1703}
1591 1704
1592=head1 ERROR AND EXCEPTION HANDLING 1705=head1 ERROR AND EXCEPTION HANDLING
1593 1706
1594In general, AnyEvent does not do any error handling - it relies on the 1707In general, AnyEvent does not do any error handling - it relies on the
1595caller to do that if required. The L<AnyEvent::Strict> module (see also 1708caller to do that if required. The L<AnyEvent::Strict> module (see also

Diff Legend

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