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.265 by root, Wed Jul 29 13:10:58 2009 UTC vs.
Revision 1.277 by root, Sun Aug 9 13:27:23 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
… …
777=over 4 806=over 4
778 807
779=item Backends that are autoprobed when no other event loop can be found. 808=item Backends that are autoprobed when no other event loop can be found.
780 809
781EV is the preferred backend when no other event loop seems to be in 810EV is the preferred backend when no other event loop seems to be in
782use. If EV is not installed, then AnyEvent will try Event, and, failing 811use. If EV is not installed, then AnyEvent will fall back to its own
783that, will fall back to its own pure-perl implementation, which is 812pure-perl implementation, which is available everywhere as it comes with
784available everywhere as it comes with AnyEvent itself. 813AnyEvent itself.
785 814
786 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 815 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
787 AnyEvent::Impl::Event based on Event, very stable, few glitches.
788 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 816 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
789 817
790=item Backends that are transparently being picked up when they are used. 818=item Backends that are transparently being picked up when they are used.
791 819
792These will be used when they are currently loaded when the first watcher 820These will be used when they are currently loaded when the first watcher
793is created, in which case it is assumed that the application is using 821is created, in which case it is assumed that the application is using
794them. This means that AnyEvent will automatically pick the right backend 822them. This means that AnyEvent will automatically pick the right backend
795when the main program loads an event module before anything starts to 823when the main program loads an event module before anything starts to
796create watchers. Nothing special needs to be done by the main program. 824create watchers. Nothing special needs to be done by the main program.
797 825
826 AnyEvent::Impl::Event based on Event, very stable, few glitches.
798 AnyEvent::Impl::Glib based on Glib, slow but very stable. 827 AnyEvent::Impl::Glib based on Glib, slow but very stable.
799 AnyEvent::Impl::Tk based on Tk, very broken. 828 AnyEvent::Impl::Tk based on Tk, very broken.
800 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 829 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
801 AnyEvent::Impl::POE based on POE, very slow, some limitations. 830 AnyEvent::Impl::POE based on POE, very slow, some limitations.
802 AnyEvent::Impl::Irssi used when running within irssi. 831 AnyEvent::Impl::Irssi used when running within irssi.
… …
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.92;
1092our $MODEL; 1121our $MODEL;
1093 1122
1094our $AUTOLOAD; 1123our $AUTOLOAD;
1095our @ISA; 1124our @ISA;
1096 1125
… …
1122 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1151 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1123} 1152}
1124 1153
1125my @models = ( 1154my @models = (
1126 [EV:: => AnyEvent::Impl::EV:: , 1], 1155 [EV:: => AnyEvent::Impl::EV:: , 1],
1127 [Event:: => AnyEvent::Impl::Event::, 1],
1128 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1], 1156 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1129 # everything below here will not (normally) be autoprobed 1157 # everything below here will not (normally) be autoprobed
1130 # as the pureperl backend should work everywhere 1158 # as the pureperl backend should work everywhere
1131 # and is usually faster 1159 # and is usually faster
1160 [Event:: => AnyEvent::Impl::Event::, 1],
1132 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1161 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1133 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1162 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1134 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package 1163 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1135 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1164 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1136 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1165 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
… …
1139 [Prima:: => AnyEvent::Impl::POE::], 1168 [Prima:: => AnyEvent::Impl::POE::],
1140 # IO::Async is just too broken - we would need workarounds for its 1169 # IO::Async is just too broken - we would need workarounds for its
1141 # byzantine signal and broken child handling, among others. 1170 # byzantine signal and broken child handling, among others.
1142 # IO::Async is rather hard to detect, as it doesn't have any 1171 # IO::Async is rather hard to detect, as it doesn't have any
1143 # obvious default class. 1172 # obvious default class.
1144# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1173 [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1145# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1174 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1146# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1175 [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1176 [AnyEvent::Impl::IOAsync:: => AnyEvent::Impl::IOAsync::], # requires special main program
1147); 1177);
1148 1178
1149our %method = map +($_ => 1), 1179our %method = map +($_ => 1),
1150 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1180 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
1151 1181
… …
1258 # we assume CLOEXEC is already set by perl in all important cases 1288 # we assume CLOEXEC is already set by perl in all important cases
1259 1289
1260 ($fh2, $rw) 1290 ($fh2, $rw)
1261} 1291}
1262 1292
1293#############################################################################
1294# "new" API, currently only emulation of it
1295#############################################################################
1296
1297package AE;
1298
1299our $VERSION = $AnyEvent::VERSION;
1300
1301sub io($$$) {
1302 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1303}
1304
1305sub timer($$$) {
1306 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1307}
1308
1309sub signal($$) {
1310 AnyEvent->signal (signal => $_[0], cb => $_[1])
1311}
1312
1313sub child($$) {
1314 AnyEvent->child (pid => $_[0], cb => $_[1])
1315}
1316
1317sub idle($) {
1318 AnyEvent->idle (cb => $_[0])
1319}
1320
1321sub cv(;&) {
1322 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1323}
1324
1325sub now() {
1326 AnyEvent->now
1327}
1328
1329sub now_update() {
1330 AnyEvent->now_update
1331}
1332
1333sub time() {
1334 AnyEvent->time
1335}
1336
1263package AnyEvent::Base; 1337package AnyEvent::Base;
1264 1338
1265# default implementations for many methods 1339# default implementations for many methods
1266 1340
1267sub _time { 1341sub _time {
… …
1319 1393
1320# install a dummy wakeup watcher to reduce signal catching latency 1394# install a dummy wakeup watcher to reduce signal catching latency
1321sub _sig_add() { 1395sub _sig_add() {
1322 unless ($SIG_COUNT++) { 1396 unless ($SIG_COUNT++) {
1323 # try to align timer on a full-second boundary, if possible 1397 # try to align timer on a full-second boundary, if possible
1324 my $NOW = AnyEvent->now; 1398 my $NOW = AE::now;
1325 1399
1326 $SIG_TW = AnyEvent->timer ( 1400 $SIG_TW = AE::timer
1327 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW), 1401 $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1328 interval => $MAX_SIGNAL_LATENCY, 1402 $MAX_SIGNAL_LATENCY,
1329 cb => sub { }, # just for the PERL_ASYNC_CHECK 1403 sub { } # just for the PERL_ASYNC_CHECK
1330 ); 1404 ;
1331 } 1405 }
1332} 1406}
1333 1407
1334sub _sig_del { 1408sub _sig_del {
1335 undef $SIG_TW 1409 undef $SIG_TW
… …
1372 # probe for availability of Async::Interrupt 1446 # probe for availability of Async::Interrupt
1373 if (_have_async_interrupt) { 1447 if (_have_async_interrupt) {
1374 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1448 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1375 1449
1376 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1450 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1377 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec); 1451 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1378 1452
1379 } else { 1453 } else {
1380 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1454 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1381 1455
1382 require Fcntl; 1456 require Fcntl;
… …
1398 } 1472 }
1399 1473
1400 $SIGPIPE_R 1474 $SIGPIPE_R
1401 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1475 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1402 1476
1403 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1477 $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;
1404 } 1478 }
1405 1479
1406 *signal = sub { 1480 *signal = sub {
1407 my (undef, %arg) = @_; 1481 my (undef, %arg) = @_;
1408 1482
… …
1497 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/ 1571 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1498 ? 1 1572 ? 1
1499 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1573 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1500 1574
1501 unless ($CHLD_W) { 1575 unless ($CHLD_W) {
1502 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1576 $CHLD_W = AE::signal CHLD => \&_sigchld;
1503 # child could be a zombie already, so make at least one round 1577 # child could be a zombie already, so make at least one round
1504 &_sigchld; 1578 &_sigchld;
1505 } 1579 }
1506 1580
1507 bless [$pid, $arg{cb}], "AnyEvent::Base::child" 1581 bless [$pid, $arg{cb}], "AnyEvent::Base::child"
… …
1533 # never use more then 50% of the time for the idle watcher, 1607 # never use more then 50% of the time for the idle watcher,
1534 # within some limits 1608 # within some limits
1535 $w = 0.0001 if $w < 0.0001; 1609 $w = 0.0001 if $w < 0.0001;
1536 $w = 5 if $w > 5; 1610 $w = 5 if $w > 5;
1537 1611
1538 $w = AnyEvent->timer (after => $w, cb => $rcb); 1612 $w = AE::timer $w, 0, $rcb;
1539 } else { 1613 } else {
1540 # clean up... 1614 # clean up...
1541 undef $w; 1615 undef $w;
1542 undef $rcb; 1616 undef $rcb;
1543 } 1617 }
1544 }; 1618 };
1545 1619
1546 $w = AnyEvent->timer (after => 0.05, cb => $rcb); 1620 $w = AE::timer 0.05, 0, $rcb;
1547 1621
1548 bless \\$cb, "AnyEvent::Base::idle" 1622 bless \\$cb, "AnyEvent::Base::idle"
1549} 1623}
1550 1624
1551sub AnyEvent::Base::idle::DESTROY { 1625sub AnyEvent::Base::idle::DESTROY {
… …
1605 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak}; 1679 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak};
1606 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0] 1680 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0]
1607} 1681}
1608 1682
1609sub cb { 1683sub cb {
1610 $_[0]{_ae_cb} = $_[1] if @_ > 1; 1684 my $cv = shift;
1685
1686 @_
1687 and $cv->{_ae_cb} = shift
1688 and $cv->{_ae_sent}
1689 and (delete $cv->{_ae_cb})->($cv);
1690
1611 $_[0]{_ae_cb} 1691 $cv->{_ae_cb}
1612} 1692}
1613 1693
1614sub begin { 1694sub begin {
1615 ++$_[0]{_ae_counter}; 1695 ++$_[0]{_ae_counter};
1616 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 1696 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;

Diff Legend

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