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.271 by root, Wed Aug 5 20:50:27 2009 UTC vs.
Revision 1.307 by root, Sun Dec 20 22:49:52 2009 UTC

363might affect timers and time-outs. 363might affect timers and time-outs.
364 364
365When this is the case, you can call this method, which will update the 365When this is the case, you can call this method, which will update the
366event loop's idea of "current time". 366event loop's idea of "current time".
367 367
368A typical example would be a script in a web server (e.g. C<mod_perl>) -
369when mod_perl executes the script, then the event loop will have the wrong
370idea about the "current time" (being potentially far in the past, when the
371script ran the last time). In that case you should arrange a call to C<<
372AnyEvent->now_update >> each time the web server process wakes up again
373(e.g. at the start of your script, or in a handler).
374
368Note that updating the time I<might> cause some events to be handled. 375Note that updating the time I<might> cause some events to be handled.
369 376
370=back 377=back
371 378
372=head2 SIGNAL WATCHERS 379=head2 SIGNAL WATCHERS
395correctly. 402correctly.
396 403
397Example: exit on SIGINT 404Example: exit on SIGINT
398 405
399 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 406 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
407
408=head3 Restart Behaviour
409
410While restart behaviour is up to the event loop implementation, most will
411not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's
412pure perl implementation).
413
414=head3 Safe/Unsafe Signals
415
416Perl signals can be either "safe" (synchronous to opcode handling) or
417"unsafe" (asynchronous) - the former might get delayed indefinitely, the
418latter might corrupt your memory.
419
420AnyEvent signal handlers are, in addition, synchronous to the event loop,
421i.e. they will not interrupt your running perl program but will only be
422called as part of the normal event handling (just like timer, I/O etc.
423callbacks, too).
400 424
401=head3 Signal Races, Delays and Workarounds 425=head3 Signal Races, Delays and Workarounds
402 426
403Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 427Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
404callbacks to signals in a generic way, which is a pity, as you cannot 428callbacks to signals in a generic way, which is a pity, as you cannot
592 after => 1, 616 after => 1,
593 cb => sub { $result_ready->send }, 617 cb => sub { $result_ready->send },
594 ); 618 );
595 619
596 # this "blocks" (while handling events) till the callback 620 # this "blocks" (while handling events) till the callback
597 # calls -<send 621 # calls ->send
598 $result_ready->recv; 622 $result_ready->recv;
599 623
600Example: wait for a timer, but take advantage of the fact that condition 624Example: wait for a timer, but take advantage of the fact that condition
601variables are also callable directly. 625variables are also callable directly.
602 626
666one. For example, a function that pings many hosts in parallel might want 690one. For example, a function that pings many hosts in parallel might want
667to use a condition variable for the whole process. 691to use a condition variable for the whole process.
668 692
669Every call to C<< ->begin >> will increment a counter, and every call to 693Every call to C<< ->begin >> will increment a counter, and every call to
670C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end 694C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
671>>, the (last) callback passed to C<begin> will be executed. That callback 695>>, the (last) callback passed to C<begin> will be executed, passing the
672is I<supposed> to call C<< ->send >>, but that is not required. If no 696condvar as first argument. That callback is I<supposed> to call C<< ->send
673callback was set, C<send> will be called without any arguments. 697>>, but that is not required. If no group callback was set, C<send> will
698be called without any arguments.
674 699
675You can think of C<< $cv->send >> giving you an OR condition (one call 700You can think of C<< $cv->send >> giving you an OR condition (one call
676sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND 701sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND
677condition (all C<begin> calls must be C<end>'ed before the condvar sends). 702condition (all C<begin> calls must be C<end>'ed before the condvar sends).
678 703
705begung can potentially be zero: 730begung can potentially be zero:
706 731
707 my $cv = AnyEvent->condvar; 732 my $cv = AnyEvent->condvar;
708 733
709 my %result; 734 my %result;
710 $cv->begin (sub { $cv->send (\%result) }); 735 $cv->begin (sub { shift->send (\%result) });
711 736
712 for my $host (@list_of_hosts) { 737 for my $host (@list_of_hosts) {
713 $cv->begin; 738 $cv->begin;
714 ping_host_then_call_callback $host, sub { 739 ping_host_then_call_callback $host, sub {
715 $result{$host} = ...; 740 $result{$host} = ...;
806=over 4 831=over 4
807 832
808=item Backends that are autoprobed when no other event loop can be found. 833=item Backends that are autoprobed when no other event loop can be found.
809 834
810EV is the preferred backend when no other event loop seems to be in 835EV is the preferred backend when no other event loop seems to be in
811use. If EV is not installed, then AnyEvent will try Event, and, failing 836use. If EV is not installed, then AnyEvent will fall back to its own
812that, will fall back to its own pure-perl implementation, which is 837pure-perl implementation, which is available everywhere as it comes with
813available everywhere as it comes with AnyEvent itself. 838AnyEvent itself.
814 839
815 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 840 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
816 AnyEvent::Impl::Event based on Event, very stable, few glitches.
817 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 841 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
818 842
819=item Backends that are transparently being picked up when they are used. 843=item Backends that are transparently being picked up when they are used.
820 844
821These will be used when they are currently loaded when the first watcher 845These will be used when they are currently loaded when the first watcher
822is created, in which case it is assumed that the application is using 846is created, in which case it is assumed that the application is using
823them. This means that AnyEvent will automatically pick the right backend 847them. This means that AnyEvent will automatically pick the right backend
824when the main program loads an event module before anything starts to 848when the main program loads an event module before anything starts to
825create watchers. Nothing special needs to be done by the main program. 849create watchers. Nothing special needs to be done by the main program.
826 850
851 AnyEvent::Impl::Event based on Event, very stable, few glitches.
827 AnyEvent::Impl::Glib based on Glib, slow but very stable. 852 AnyEvent::Impl::Glib based on Glib, slow but very stable.
828 AnyEvent::Impl::Tk based on Tk, very broken. 853 AnyEvent::Impl::Tk based on Tk, very broken.
829 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 854 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
830 AnyEvent::Impl::POE based on POE, very slow, some limitations. 855 AnyEvent::Impl::POE based on POE, very slow, some limitations.
831 AnyEvent::Impl::Irssi used when running within irssi. 856 AnyEvent::Impl::Irssi used when running within irssi.
941You should check C<$AnyEvent::MODEL> before adding to this array, though: 966You should check C<$AnyEvent::MODEL> before adding to this array, though:
942if it is defined then the event loop has already been detected, and the 967if it is defined then the event loop has already been detected, and the
943array will be ignored. 968array will be ignored.
944 969
945Best use C<AnyEvent::post_detect { BLOCK }> when your application allows 970Best use C<AnyEvent::post_detect { BLOCK }> when your application allows
946it,as it takes care of these details. 971it, as it takes care of these details.
947 972
948This variable is mainly useful for modules that can do something useful 973This variable is mainly useful for modules that can do something useful
949when AnyEvent is used and thus want to know when it is initialised, but do 974when AnyEvent is used and thus want to know when it is initialised, but do
950not need to even load it by default. This array provides the means to hook 975not need to even load it by default. This array provides the means to hook
951into AnyEvent passively, without loading it. 976into AnyEvent passively, without loading it.
977
978Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
979together, you could put this into Coro (this is the actual code used by
980Coro to accomplish this):
981
982 if (defined $AnyEvent::MODEL) {
983 # AnyEvent already initialised, so load Coro::AnyEvent
984 require Coro::AnyEvent;
985 } else {
986 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
987 # as soon as it is
988 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
989 }
952 990
953=back 991=back
954 992
955=head1 WHAT TO DO IN A MODULE 993=head1 WHAT TO DO IN A MODULE
956 994
1105 1143
1106package AnyEvent; 1144package AnyEvent;
1107 1145
1108# basically a tuned-down version of common::sense 1146# basically a tuned-down version of common::sense
1109sub common_sense { 1147sub common_sense {
1110 # no warnings 1148 # from common:.sense 1.0
1111 ${^WARNING_BITS} ^= ${^WARNING_BITS}; 1149 ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x00";
1112 # use strict vars subs 1150 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1113 $^H |= 0x00000600; 1151 $^H |= 0x00000600;
1114} 1152}
1115 1153
1116BEGIN { AnyEvent::common_sense } 1154BEGIN { AnyEvent::common_sense }
1117 1155
1118use Carp (); 1156use Carp ();
1119 1157
1120our $VERSION = 4.901; 1158our $VERSION = '5.23';
1121our $MODEL; 1159our $MODEL;
1122 1160
1123our $AUTOLOAD; 1161our $AUTOLOAD;
1124our @ISA; 1162our @ISA;
1125 1163
1126our @REGISTRY; 1164our @REGISTRY;
1127
1128our $WIN32;
1129 1165
1130our $VERBOSE; 1166our $VERBOSE;
1131 1167
1132BEGIN { 1168BEGIN {
1133 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1169 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
1151 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1187 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1152} 1188}
1153 1189
1154my @models = ( 1190my @models = (
1155 [EV:: => AnyEvent::Impl::EV:: , 1], 1191 [EV:: => AnyEvent::Impl::EV:: , 1],
1156 [Event:: => AnyEvent::Impl::Event::, 1],
1157 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1], 1192 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1158 # everything below here will not (normally) be autoprobed 1193 # everything below here will not (normally) be autoprobed
1159 # as the pureperl backend should work everywhere 1194 # as the pureperl backend should work everywhere
1160 # and is usually faster 1195 # and is usually faster
1196 [Event:: => AnyEvent::Impl::Event::, 1],
1161 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1197 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1162 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1198 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1163 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package 1199 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1164 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1200 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1165 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1201 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1168 [Prima:: => AnyEvent::Impl::POE::], 1204 [Prima:: => AnyEvent::Impl::POE::],
1169 # IO::Async is just too broken - we would need workarounds for its 1205 # IO::Async is just too broken - we would need workarounds for its
1170 # byzantine signal and broken child handling, among others. 1206 # byzantine signal and broken child handling, among others.
1171 # IO::Async is rather hard to detect, as it doesn't have any 1207 # IO::Async is rather hard to detect, as it doesn't have any
1172 # obvious default class. 1208 # obvious default class.
1173# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1209 [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1174# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1210 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1175# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1211 [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1212 [AnyEvent::Impl::IOAsync:: => AnyEvent::Impl::IOAsync::], # requires special main program
1176); 1213);
1177 1214
1178our %method = map +($_ => 1), 1215our %method = map +($_ => 1),
1179 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1216 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
1180 1217
1287 # we assume CLOEXEC is already set by perl in all important cases 1324 # we assume CLOEXEC is already set by perl in all important cases
1288 1325
1289 ($fh2, $rw) 1326 ($fh2, $rw)
1290} 1327}
1291 1328
1329=head1 SIMPLIFIED AE API
1330
1331Starting with version 5.0, AnyEvent officially supports a second, much
1332simpler, API that is designed to reduce the calling, typing and memory
1333overhead.
1334
1335See the L<AE> manpage for details.
1336
1337=cut
1338
1339package AE;
1340
1341our $VERSION = $AnyEvent::VERSION;
1342
1343sub io($$$) {
1344 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1345}
1346
1347sub timer($$$) {
1348 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1349}
1350
1351sub signal($$) {
1352 AnyEvent->signal (signal => $_[0], cb => $_[1])
1353}
1354
1355sub child($$) {
1356 AnyEvent->child (pid => $_[0], cb => $_[1])
1357}
1358
1359sub idle($) {
1360 AnyEvent->idle (cb => $_[0])
1361}
1362
1363sub cv(;&) {
1364 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1365}
1366
1367sub now() {
1368 AnyEvent->now
1369}
1370
1371sub now_update() {
1372 AnyEvent->now_update
1373}
1374
1375sub time() {
1376 AnyEvent->time
1377}
1378
1292package AnyEvent::Base; 1379package AnyEvent::Base;
1293 1380
1294# default implementations for many methods 1381# default implementations for many methods
1295 1382
1296sub _time { 1383sub _time() {
1297 # probe for availability of Time::HiRes 1384 # probe for availability of Time::HiRes
1298 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1385 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1299 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1386 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1300 *_time = \&Time::HiRes::time; 1387 *_time = \&Time::HiRes::time;
1301 # if (eval "use POSIX (); (POSIX::times())... 1388 # if (eval "use POSIX (); (POSIX::times())...
1321 1408
1322our $HAVE_ASYNC_INTERRUPT; 1409our $HAVE_ASYNC_INTERRUPT;
1323 1410
1324sub _have_async_interrupt() { 1411sub _have_async_interrupt() {
1325 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} 1412 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT}
1326 && eval "use Async::Interrupt 1.0 (); 1") 1413 && eval "use Async::Interrupt 1.02 (); 1")
1327 unless defined $HAVE_ASYNC_INTERRUPT; 1414 unless defined $HAVE_ASYNC_INTERRUPT;
1328 1415
1329 $HAVE_ASYNC_INTERRUPT 1416 $HAVE_ASYNC_INTERRUPT
1330} 1417}
1331 1418
1334our ($SIG_COUNT, $SIG_TW); 1421our ($SIG_COUNT, $SIG_TW);
1335 1422
1336sub _signal_exec { 1423sub _signal_exec {
1337 $HAVE_ASYNC_INTERRUPT 1424 $HAVE_ASYNC_INTERRUPT
1338 ? $SIGPIPE_R->drain 1425 ? $SIGPIPE_R->drain
1339 : sysread $SIGPIPE_R, my $dummy, 9; 1426 : sysread $SIGPIPE_R, (my $dummy), 9;
1340 1427
1341 while (%SIG_EV) { 1428 while (%SIG_EV) {
1342 for (keys %SIG_EV) { 1429 for (keys %SIG_EV) {
1343 delete $SIG_EV{$_}; 1430 delete $SIG_EV{$_};
1344 $_->() for values %{ $SIG_CB{$_} || {} }; 1431 $_->() for values %{ $SIG_CB{$_} || {} };
1348 1435
1349# install a dummy wakeup watcher to reduce signal catching latency 1436# install a dummy wakeup watcher to reduce signal catching latency
1350sub _sig_add() { 1437sub _sig_add() {
1351 unless ($SIG_COUNT++) { 1438 unless ($SIG_COUNT++) {
1352 # try to align timer on a full-second boundary, if possible 1439 # try to align timer on a full-second boundary, if possible
1353 my $NOW = AnyEvent->now; 1440 my $NOW = AE::now;
1354 1441
1355 $SIG_TW = AnyEvent->timer ( 1442 $SIG_TW = AE::timer
1356 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW), 1443 $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1357 interval => $MAX_SIGNAL_LATENCY, 1444 $MAX_SIGNAL_LATENCY,
1358 cb => sub { }, # just for the PERL_ASYNC_CHECK 1445 sub { } # just for the PERL_ASYNC_CHECK
1359 ); 1446 ;
1360 } 1447 }
1361} 1448}
1362 1449
1363sub _sig_del { 1450sub _sig_del {
1364 undef $SIG_TW 1451 undef $SIG_TW
1401 # probe for availability of Async::Interrupt 1488 # probe for availability of Async::Interrupt
1402 if (_have_async_interrupt) { 1489 if (_have_async_interrupt) {
1403 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1490 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1404 1491
1405 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1492 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1406 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec); 1493 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1407 1494
1408 } else { 1495 } else {
1409 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1496 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1410 1497
1411 require Fcntl; 1498 require Fcntl;
1427 } 1514 }
1428 1515
1429 $SIGPIPE_R 1516 $SIGPIPE_R
1430 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1517 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1431 1518
1432 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1519 $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;
1433 } 1520 }
1434 1521
1435 *signal = sub { 1522 *signal = sub {
1436 my (undef, %arg) = @_; 1523 my (undef, %arg) = @_;
1437 1524
1526 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/ 1613 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1527 ? 1 1614 ? 1
1528 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1615 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1529 1616
1530 unless ($CHLD_W) { 1617 unless ($CHLD_W) {
1531 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1618 $CHLD_W = AE::signal CHLD => \&_sigchld;
1532 # child could be a zombie already, so make at least one round 1619 # child could be a zombie already, so make at least one round
1533 &_sigchld; 1620 &_sigchld;
1534 } 1621 }
1535 1622
1536 bless [$pid, $arg{cb}], "AnyEvent::Base::child" 1623 bless [$pid, $arg{cb}], "AnyEvent::Base::child"
1562 # never use more then 50% of the time for the idle watcher, 1649 # never use more then 50% of the time for the idle watcher,
1563 # within some limits 1650 # within some limits
1564 $w = 0.0001 if $w < 0.0001; 1651 $w = 0.0001 if $w < 0.0001;
1565 $w = 5 if $w > 5; 1652 $w = 5 if $w > 5;
1566 1653
1567 $w = AnyEvent->timer (after => $w, cb => $rcb); 1654 $w = AE::timer $w, 0, $rcb;
1568 } else { 1655 } else {
1569 # clean up... 1656 # clean up...
1570 undef $w; 1657 undef $w;
1571 undef $rcb; 1658 undef $rcb;
1572 } 1659 }
1573 }; 1660 };
1574 1661
1575 $w = AnyEvent->timer (after => 0.05, cb => $rcb); 1662 $w = AE::timer 0.05, 0, $rcb;
1576 1663
1577 bless \\$cb, "AnyEvent::Base::idle" 1664 bless \\$cb, "AnyEvent::Base::idle"
1578} 1665}
1579 1666
1580sub AnyEvent::Base::idle::DESTROY { 1667sub AnyEvent::Base::idle::DESTROY {
1657} 1744}
1658 1745
1659# undocumented/compatibility with pre-3.4 1746# undocumented/compatibility with pre-3.4
1660*broadcast = \&send; 1747*broadcast = \&send;
1661*wait = \&_wait; 1748*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}
1704 1749
1705=head1 ERROR AND EXCEPTION HANDLING 1750=head1 ERROR AND EXCEPTION HANDLING
1706 1751
1707In general, AnyEvent does not do any error handling - it relies on the 1752In general, AnyEvent does not do any error handling - it relies on the
1708caller to do that if required. The L<AnyEvent::Strict> module (see also 1753caller to do that if required. The L<AnyEvent::Strict> module (see also
1902 warn "read: $input\n"; # output what has been read 1947 warn "read: $input\n"; # output what has been read
1903 $cv->send if $input =~ /^q/i; # quit program if /^q/i 1948 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1904 }, 1949 },
1905 ); 1950 );
1906 1951
1907 my $time_watcher; # can only be used once
1908
1909 sub new_timer {
1910 $timer = AnyEvent->timer (after => 1, cb => sub { 1952 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
1911 warn "timeout\n"; # print 'timeout' about every second 1953 warn "timeout\n"; # print 'timeout' at most every second
1912 &new_timer; # and restart the time
1913 }); 1954 });
1914 }
1915
1916 new_timer; # create first timer
1917 1955
1918 $cv->recv; # wait until user enters /^q/i 1956 $cv->recv; # wait until user enters /^q/i
1919 1957
1920=head1 REAL-WORLD EXAMPLE 1958=head1 REAL-WORLD EXAMPLE
1921 1959
2052through AnyEvent. The benchmark creates a lot of timers (with a zero 2090through AnyEvent. The benchmark creates a lot of timers (with a zero
2053timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 2091timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
2054which it is), lets them fire exactly once and destroys them again. 2092which it is), lets them fire exactly once and destroys them again.
2055 2093
2056Source code for this benchmark is found as F<eg/bench> in the AnyEvent 2094Source code for this benchmark is found as F<eg/bench> in the AnyEvent
2057distribution. 2095distribution. It uses the L<AE> interface, which makes a real difference
2096for the EV and Perl backends only.
2058 2097
2059=head3 Explanation of the columns 2098=head3 Explanation of the columns
2060 2099
2061I<watcher> is the number of event watchers created/destroyed. Since 2100I<watcher> is the number of event watchers created/destroyed. Since
2062different event models feature vastly different performances, each event 2101different event models feature vastly different performances, each event
2083watcher. 2122watcher.
2084 2123
2085=head3 Results 2124=head3 Results
2086 2125
2087 name watchers bytes create invoke destroy comment 2126 name watchers bytes create invoke destroy comment
2088 EV/EV 400000 224 0.47 0.35 0.27 EV native interface 2127 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
2089 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 2128 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
2090 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 2129 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
2091 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 2130 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
2092 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 2131 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
2093 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 2132 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
2094 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll 2133 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
2095 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll 2134 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
2096 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 2135 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
2097 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 2136 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
2098 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 2137 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
2099 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 2138 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
2100 2139
2101=head3 Discussion 2140=head3 Discussion
2102 2141
2103The benchmark does I<not> measure scalability of the event loop very 2142The benchmark does I<not> measure scalability of the event loop very
2104well. For example, a select-based event loop (such as the pure perl one) 2143well. For example, a select-based event loop (such as the pure perl one)
2116benchmark machine, handling an event takes roughly 1600 CPU cycles with 2155benchmark machine, handling an event takes roughly 1600 CPU cycles with
2117EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU 2156EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU
2118cycles with POE. 2157cycles with POE.
2119 2158
2120C<EV> is the sole leader regarding speed and memory use, which are both 2159C<EV> is the sole leader regarding speed and memory use, which are both
2121maximal/minimal, respectively. Even when going through AnyEvent, it uses 2160maximal/minimal, respectively. When using the L<AE> API there is zero
2161overhead (when going through the AnyEvent API create is about 5-6 times
2162slower, with other times being equal, so still uses far less memory than
2122far less memory than any other event loop and is still faster than Event 2163any other event loop and is still faster than Event natively).
2123natively.
2124 2164
2125The pure perl implementation is hit in a few sweet spots (both the 2165The pure perl implementation is hit in a few sweet spots (both the
2126constant timeout and the use of a single fd hit optimisations in the perl 2166constant timeout and the use of a single fd hit optimisations in the perl
2127interpreter and the backend itself). Nevertheless this shows that it 2167interpreter and the backend itself). Nevertheless this shows that it
2128adds very little overhead in itself. Like any select-based backend its 2168adds very little overhead in itself. Like any select-based backend its
2202In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100 2242In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
2203(1%) are active. This mirrors the activity of large servers with many 2243(1%) are active. This mirrors the activity of large servers with many
2204connections, most of which are idle at any one point in time. 2244connections, most of which are idle at any one point in time.
2205 2245
2206Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 2246Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
2207distribution. 2247distribution. It uses the L<AE> interface, which makes a real difference
2248for the EV and Perl backends only.
2208 2249
2209=head3 Explanation of the columns 2250=head3 Explanation of the columns
2210 2251
2211I<sockets> is the number of sockets, and twice the number of "servers" (as 2252I<sockets> is the number of sockets, and twice the number of "servers" (as
2212each server has a read and write socket end). 2253each server has a read and write socket end).
2220a new one that moves the timeout into the future. 2261a new one that moves the timeout into the future.
2221 2262
2222=head3 Results 2263=head3 Results
2223 2264
2224 name sockets create request 2265 name sockets create request
2225 EV 20000 69.01 11.16 2266 EV 20000 62.66 7.99
2226 Perl 20000 73.32 35.87 2267 Perl 20000 68.32 32.64
2227 IOAsync 20000 157.00 98.14 epoll 2268 IOAsync 20000 174.06 101.15 epoll
2228 IOAsync 20000 159.31 616.06 poll 2269 IOAsync 20000 174.67 610.84 poll
2229 Event 20000 212.62 257.32 2270 Event 20000 202.69 242.91
2230 Glib 20000 651.16 1896.30 2271 Glib 20000 557.01 1689.52
2231 POE 20000 349.67 12317.24 uses POE::Loop::Event 2272 POE 20000 341.54 12086.32 uses POE::Loop::Event
2232 2273
2233=head3 Discussion 2274=head3 Discussion
2234 2275
2235This benchmark I<does> measure scalability and overall performance of the 2276This benchmark I<does> measure scalability and overall performance of the
2236particular event loop. 2277particular event loop.
2362As you can see, the AnyEvent + EV combination even beats the 2403As you can see, the AnyEvent + EV combination even beats the
2363hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl 2404hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
2364backend easily beats IO::Lambda and POE. 2405backend easily beats IO::Lambda and POE.
2365 2406
2366And even the 100% non-blocking version written using the high-level (and 2407And even the 100% non-blocking version written using the high-level (and
2367slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a 2408slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda
2368large margin, even though it does all of DNS, tcp-connect and socket I/O 2409higher level ("unoptimised") abstractions by a large margin, even though
2369in a non-blocking way. 2410it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
2370 2411
2371The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and 2412The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
2372F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are 2413F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2373part of the IO::lambda distribution and were used without any changes. 2414part of the IO::Lambda distribution and were used without any changes.
2374 2415
2375 2416
2376=head1 SIGNALS 2417=head1 SIGNALS
2377 2418
2378AnyEvent currently installs handlers for these signals: 2419AnyEvent currently installs handlers for these signals:
2420it's built-in modules) are required to use it. 2461it's built-in modules) are required to use it.
2421 2462
2422That does not mean that AnyEvent won't take advantage of some additional 2463That does not mean that AnyEvent won't take advantage of some additional
2423modules if they are installed. 2464modules if they are installed.
2424 2465
2425This section epxlains which additional modules will be used, and how they 2466This section explains which additional modules will be used, and how they
2426affect AnyEvent's operetion. 2467affect AnyEvent's operation.
2427 2468
2428=over 4 2469=over 4
2429 2470
2430=item L<Async::Interrupt> 2471=item L<Async::Interrupt>
2431 2472
2436catch the signals) with some delay (default is 10 seconds, look for 2477catch the signals) with some delay (default is 10 seconds, look for
2437C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2478C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2438 2479
2439If this module is available, then it will be used to implement signal 2480If this module is available, then it will be used to implement signal
2440catching, which means that signals will not be delayed, and the event loop 2481catching, which means that signals will not be delayed, and the event loop
2441will not be interrupted regularly, which is more efficient (And good for 2482will not be interrupted regularly, which is more efficient (and good for
2442battery life on laptops). 2483battery life on laptops).
2443 2484
2444This affects not just the pure-perl event loop, but also other event loops 2485This affects not just the pure-perl event loop, but also other event loops
2445that have no signal handling on their own (e.g. Glib, Tk, Qt). 2486that have no signal handling on their own (e.g. Glib, Tk, Qt).
2446 2487
2467lot less memory), but otherwise doesn't affect guard operation much. It is 2508lot less memory), but otherwise doesn't affect guard operation much. It is
2468purely used for performance. 2509purely used for performance.
2469 2510
2470=item L<JSON> and L<JSON::XS> 2511=item L<JSON> and L<JSON::XS>
2471 2512
2472This module is required when you want to read or write JSON data via 2513One of these modules is required when you want to read or write JSON data
2473L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2514via L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2474advantage of the ultra-high-speed L<JSON::XS> module when it is installed. 2515advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2475 2516
2476In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is 2517In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2477installed. 2518installed.
2478 2519
2496 2537
2497Most event libraries are not fork-safe. The ones who are usually are 2538Most event libraries are not fork-safe. The ones who are usually are
2498because they rely on inefficient but fork-safe C<select> or C<poll> 2539because they rely on inefficient but fork-safe C<select> or C<poll>
2499calls. Only L<EV> is fully fork-aware. 2540calls. Only L<EV> is fully fork-aware.
2500 2541
2542This means that, in general, you cannot fork and do event processing
2543in the child if a watcher was created before the fork (which in turn
2544initialises the event library).
2545
2501If you have to fork, you must either do so I<before> creating your first 2546If you have to fork, you must either do so I<before> creating your first
2502watcher OR you must not use AnyEvent at all in the child OR you must do 2547watcher OR you must not use AnyEvent at all in the child OR you must do
2503something completely out of the scope of AnyEvent. 2548something completely out of the scope of AnyEvent.
2549
2550The problem of doing event processing in the parent I<and> the child
2551is much more complicated: even for backends that I<are> fork-aware or
2552fork-safe, their behaviour is not usually what you want: fork clones all
2553watchers, that means all timers, I/O watchers etc. are active in both
2554parent and child, which is almost never what you want.
2504 2555
2505 2556
2506=head1 SECURITY CONSIDERATIONS 2557=head1 SECURITY CONSIDERATIONS
2507 2558
2508AnyEvent can be forced to load any event model via 2559AnyEvent can be forced to load any event model via

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines