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.269 by root, Fri Jul 31 20:16:29 2009 UTC vs.
Revision 1.306 by root, Tue Dec 15 05:49:13 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.9; 1158our $VERSION = '5.22';
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 {
1640 1727
1641 @_ 1728 @_
1642 and $cv->{_ae_cb} = shift 1729 and $cv->{_ae_cb} = shift
1643 and $cv->{_ae_sent} 1730 and $cv->{_ae_sent}
1644 and (delete $cv->{_ae_cb})->($cv); 1731 and (delete $cv->{_ae_cb})->($cv);
1732
1645 $cv->{_ae_cb} 1733 $cv->{_ae_cb}
1646} 1734}
1647 1735
1648sub begin { 1736sub begin {
1649 ++$_[0]{_ae_counter}; 1737 ++$_[0]{_ae_counter};
1656} 1744}
1657 1745
1658# undocumented/compatibility with pre-3.4 1746# undocumented/compatibility with pre-3.4
1659*broadcast = \&send; 1747*broadcast = \&send;
1660*wait = \&_wait; 1748*wait = \&_wait;
1661
1662#############################################################################
1663# "new" API, currently only emulation of it
1664#############################################################################
1665
1666package AE;
1667
1668sub io($$$) {
1669 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1670}
1671
1672sub timer($$$) {
1673 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]);
1674}
1675
1676sub signal($$) {
1677 AnyEvent->signal (signal => $_[0], cb => $_[1]);
1678}
1679
1680sub child($$) {
1681 AnyEvent->child (pid => $_[0], cb => $_[1]);
1682}
1683
1684sub idle($) {
1685 AnyEvent->idle (cb => $_[0]);
1686}
1687
1688sub cv() {
1689 AnyEvent->condvar
1690}
1691
1692sub now() {
1693 AnyEvent->now
1694}
1695
1696sub now_update() {
1697 AnyEvent->now_update
1698}
1699
1700sub time() {
1701 AnyEvent->time
1702}
1703 1749
1704=head1 ERROR AND EXCEPTION HANDLING 1750=head1 ERROR AND EXCEPTION HANDLING
1705 1751
1706In 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
1707caller 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
1901 warn "read: $input\n"; # output what has been read 1947 warn "read: $input\n"; # output what has been read
1902 $cv->send if $input =~ /^q/i; # quit program if /^q/i 1948 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1903 }, 1949 },
1904 ); 1950 );
1905 1951
1906 my $time_watcher; # can only be used once
1907
1908 sub new_timer {
1909 $timer = AnyEvent->timer (after => 1, cb => sub { 1952 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
1910 warn "timeout\n"; # print 'timeout' about every second 1953 warn "timeout\n"; # print 'timeout' at most every second
1911 &new_timer; # and restart the time
1912 }); 1954 });
1913 }
1914
1915 new_timer; # create first timer
1916 1955
1917 $cv->recv; # wait until user enters /^q/i 1956 $cv->recv; # wait until user enters /^q/i
1918 1957
1919=head1 REAL-WORLD EXAMPLE 1958=head1 REAL-WORLD EXAMPLE
1920 1959
2051through AnyEvent. The benchmark creates a lot of timers (with a zero 2090through AnyEvent. The benchmark creates a lot of timers (with a zero
2052timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 2091timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
2053which it is), lets them fire exactly once and destroys them again. 2092which it is), lets them fire exactly once and destroys them again.
2054 2093
2055Source 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
2056distribution. 2095distribution. It uses the L<AE> interface, which makes a real difference
2096for the EV and Perl backends only.
2057 2097
2058=head3 Explanation of the columns 2098=head3 Explanation of the columns
2059 2099
2060I<watcher> is the number of event watchers created/destroyed. Since 2100I<watcher> is the number of event watchers created/destroyed. Since
2061different event models feature vastly different performances, each event 2101different event models feature vastly different performances, each event
2082watcher. 2122watcher.
2083 2123
2084=head3 Results 2124=head3 Results
2085 2125
2086 name watchers bytes create invoke destroy comment 2126 name watchers bytes create invoke destroy comment
2087 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
2088 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
2089 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
2090 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
2091 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
2092 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
2093 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
2094 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
2095 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
2096 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
2097 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
2098 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
2099 2139
2100=head3 Discussion 2140=head3 Discussion
2101 2141
2102The benchmark does I<not> measure scalability of the event loop very 2142The benchmark does I<not> measure scalability of the event loop very
2103well. 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)
2115benchmark machine, handling an event takes roughly 1600 CPU cycles with 2155benchmark machine, handling an event takes roughly 1600 CPU cycles with
2116EV, 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
2117cycles with POE. 2157cycles with POE.
2118 2158
2119C<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
2120maximal/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
2121far less memory than any other event loop and is still faster than Event 2163any other event loop and is still faster than Event natively).
2122natively.
2123 2164
2124The 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
2125constant 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
2126interpreter and the backend itself). Nevertheless this shows that it 2167interpreter and the backend itself). Nevertheless this shows that it
2127adds very little overhead in itself. Like any select-based backend its 2168adds very little overhead in itself. Like any select-based backend its
2201In 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
2202(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
2203connections, most of which are idle at any one point in time. 2244connections, most of which are idle at any one point in time.
2204 2245
2205Source 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
2206distribution. 2247distribution. It uses the L<AE> interface, which makes a real difference
2248for the EV and Perl backends only.
2207 2249
2208=head3 Explanation of the columns 2250=head3 Explanation of the columns
2209 2251
2210I<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
2211each server has a read and write socket end). 2253each server has a read and write socket end).
2219a new one that moves the timeout into the future. 2261a new one that moves the timeout into the future.
2220 2262
2221=head3 Results 2263=head3 Results
2222 2264
2223 name sockets create request 2265 name sockets create request
2224 EV 20000 69.01 11.16 2266 EV 20000 62.66 7.99
2225 Perl 20000 73.32 35.87 2267 Perl 20000 68.32 32.64
2226 IOAsync 20000 157.00 98.14 epoll 2268 IOAsync 20000 174.06 101.15 epoll
2227 IOAsync 20000 159.31 616.06 poll 2269 IOAsync 20000 174.67 610.84 poll
2228 Event 20000 212.62 257.32 2270 Event 20000 202.69 242.91
2229 Glib 20000 651.16 1896.30 2271 Glib 20000 557.01 1689.52
2230 POE 20000 349.67 12317.24 uses POE::Loop::Event 2272 POE 20000 341.54 12086.32 uses POE::Loop::Event
2231 2273
2232=head3 Discussion 2274=head3 Discussion
2233 2275
2234This benchmark I<does> measure scalability and overall performance of the 2276This benchmark I<does> measure scalability and overall performance of the
2235particular event loop. 2277particular event loop.
2361As you can see, the AnyEvent + EV combination even beats the 2403As you can see, the AnyEvent + EV combination even beats the
2362hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl 2404hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
2363backend easily beats IO::Lambda and POE. 2405backend easily beats IO::Lambda and POE.
2364 2406
2365And 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
2366slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a 2408slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda
2367large margin, even though it does all of DNS, tcp-connect and socket I/O 2409higher level ("unoptimised") abstractions by a large margin, even though
2368in a non-blocking way. 2410it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
2369 2411
2370The 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
2371F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are 2413F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2372part of the IO::lambda distribution and were used without any changes. 2414part of the IO::Lambda distribution and were used without any changes.
2373 2415
2374 2416
2375=head1 SIGNALS 2417=head1 SIGNALS
2376 2418
2377AnyEvent currently installs handlers for these signals: 2419AnyEvent currently installs handlers for these signals:
2419it's built-in modules) are required to use it. 2461it's built-in modules) are required to use it.
2420 2462
2421That 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
2422modules if they are installed. 2464modules if they are installed.
2423 2465
2424This section epxlains which additional modules will be used, and how they 2466This section explains which additional modules will be used, and how they
2425affect AnyEvent's operetion. 2467affect AnyEvent's operation.
2426 2468
2427=over 4 2469=over 4
2428 2470
2429=item L<Async::Interrupt> 2471=item L<Async::Interrupt>
2430 2472
2435catch the signals) with some delay (default is 10 seconds, look for 2477catch the signals) with some delay (default is 10 seconds, look for
2436C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2478C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2437 2479
2438If 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
2439catching, 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
2440will not be interrupted regularly, which is more efficient (And good for 2482will not be interrupted regularly, which is more efficient (and good for
2441battery life on laptops). 2483battery life on laptops).
2442 2484
2443This 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
2444that 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).
2445 2487
2466lot 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
2467purely used for performance. 2509purely used for performance.
2468 2510
2469=item L<JSON> and L<JSON::XS> 2511=item L<JSON> and L<JSON::XS>
2470 2512
2471This 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
2472L<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
2473advantage 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.
2474 2516
2475In 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
2476installed. 2518installed.
2477 2519
2495 2537
2496Most 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
2497because 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>
2498calls. Only L<EV> is fully fork-aware. 2540calls. Only L<EV> is fully fork-aware.
2499 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
2500If 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
2501watcher 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
2502something 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.
2503 2555
2504 2556
2505=head1 SECURITY CONSIDERATIONS 2557=head1 SECURITY CONSIDERATIONS
2506 2558
2507AnyEvent 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