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.268 by root, Thu Jul 30 16:39:19 2009 UTC vs.
Revision 1.302 by root, Fri Dec 4 16:31:57 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} = ...;
790=item $cb = $cv->cb ($cb->($cv)) 815=item $cb = $cv->cb ($cb->($cv))
791 816
792This is a mutator function that returns the callback set and optionally 817This is a mutator function that returns the callback set and optionally
793replaces it before doing so. 818replaces it before doing so.
794 819
795The callback will be called when the condition becomes "true", i.e. when 820The callback will be called when the condition becomes (or already was)
796C<send> or C<croak> are called, with the only argument being the condition 821"true", i.e. when C<send> or C<croak> are called (or were called), with
797variable itself. Calling C<recv> inside the callback or at any later time 822the only argument being the condition variable itself. Calling C<recv>
798is guaranteed not to block. 823inside the callback or at any later time is guaranteed not to block.
799 824
800=back 825=back
801 826
802=head1 SUPPORTED EVENT LOOPS/BACKENDS 827=head1 SUPPORTED EVENT LOOPS/BACKENDS
803 828
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.
1105 1130
1106package AnyEvent; 1131package AnyEvent;
1107 1132
1108# basically a tuned-down version of common::sense 1133# basically a tuned-down version of common::sense
1109sub common_sense { 1134sub common_sense {
1110 # no warnings 1135 # from common:.sense 1.0
1111 ${^WARNING_BITS} ^= ${^WARNING_BITS}; 1136 ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x03";
1112 # use strict vars subs 1137 # use strict vars subs
1113 $^H |= 0x00000600; 1138 $^H |= 0x00000600;
1114} 1139}
1115 1140
1116BEGIN { AnyEvent::common_sense } 1141BEGIN { AnyEvent::common_sense }
1117 1142
1118use Carp (); 1143use Carp ();
1119 1144
1120our $VERSION = 4.9; 1145our $VERSION = '5.21';
1121our $MODEL; 1146our $MODEL;
1122 1147
1123our $AUTOLOAD; 1148our $AUTOLOAD;
1124our @ISA; 1149our @ISA;
1125 1150
1126our @REGISTRY; 1151our @REGISTRY;
1127
1128our $WIN32;
1129 1152
1130our $VERBOSE; 1153our $VERBOSE;
1131 1154
1132BEGIN { 1155BEGIN {
1133 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1156 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
1151 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1174 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1152} 1175}
1153 1176
1154my @models = ( 1177my @models = (
1155 [EV:: => AnyEvent::Impl::EV:: , 1], 1178 [EV:: => AnyEvent::Impl::EV:: , 1],
1156 [Event:: => AnyEvent::Impl::Event::, 1],
1157 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1], 1179 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1158 # everything below here will not (normally) be autoprobed 1180 # everything below here will not (normally) be autoprobed
1159 # as the pureperl backend should work everywhere 1181 # as the pureperl backend should work everywhere
1160 # and is usually faster 1182 # and is usually faster
1183 [Event:: => AnyEvent::Impl::Event::, 1],
1161 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1184 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1162 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1185 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1163 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package 1186 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1164 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1187 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1165 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1188 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1168 [Prima:: => AnyEvent::Impl::POE::], 1191 [Prima:: => AnyEvent::Impl::POE::],
1169 # IO::Async is just too broken - we would need workarounds for its 1192 # IO::Async is just too broken - we would need workarounds for its
1170 # byzantine signal and broken child handling, among others. 1193 # byzantine signal and broken child handling, among others.
1171 # IO::Async is rather hard to detect, as it doesn't have any 1194 # IO::Async is rather hard to detect, as it doesn't have any
1172 # obvious default class. 1195 # obvious default class.
1173# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1196 [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1174# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1197 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1175# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1198 [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1199 [AnyEvent::Impl::IOAsync:: => AnyEvent::Impl::IOAsync::], # requires special main program
1176); 1200);
1177 1201
1178our %method = map +($_ => 1), 1202our %method = map +($_ => 1),
1179 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1203 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
1180 1204
1287 # we assume CLOEXEC is already set by perl in all important cases 1311 # we assume CLOEXEC is already set by perl in all important cases
1288 1312
1289 ($fh2, $rw) 1313 ($fh2, $rw)
1290} 1314}
1291 1315
1316=head1 SIMPLIFIED AE API
1317
1318Starting with version 5.0, AnyEvent officially supports a second, much
1319simpler, API that is designed to reduce the calling, typing and memory
1320overhead.
1321
1322See the L<AE> manpage for details.
1323
1324=cut
1325
1326package AE;
1327
1328our $VERSION = $AnyEvent::VERSION;
1329
1330sub io($$$) {
1331 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1332}
1333
1334sub timer($$$) {
1335 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1336}
1337
1338sub signal($$) {
1339 AnyEvent->signal (signal => $_[0], cb => $_[1])
1340}
1341
1342sub child($$) {
1343 AnyEvent->child (pid => $_[0], cb => $_[1])
1344}
1345
1346sub idle($) {
1347 AnyEvent->idle (cb => $_[0])
1348}
1349
1350sub cv(;&) {
1351 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1352}
1353
1354sub now() {
1355 AnyEvent->now
1356}
1357
1358sub now_update() {
1359 AnyEvent->now_update
1360}
1361
1362sub time() {
1363 AnyEvent->time
1364}
1365
1292package AnyEvent::Base; 1366package AnyEvent::Base;
1293 1367
1294# default implementations for many methods 1368# default implementations for many methods
1295 1369
1296sub _time { 1370sub _time() {
1297 # probe for availability of Time::HiRes 1371 # probe for availability of Time::HiRes
1298 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1372 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1299 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1373 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1300 *_time = \&Time::HiRes::time; 1374 *_time = \&Time::HiRes::time;
1301 # if (eval "use POSIX (); (POSIX::times())... 1375 # if (eval "use POSIX (); (POSIX::times())...
1321 1395
1322our $HAVE_ASYNC_INTERRUPT; 1396our $HAVE_ASYNC_INTERRUPT;
1323 1397
1324sub _have_async_interrupt() { 1398sub _have_async_interrupt() {
1325 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} 1399 $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT}
1326 && eval "use Async::Interrupt 1.0 (); 1") 1400 && eval "use Async::Interrupt 1.02 (); 1")
1327 unless defined $HAVE_ASYNC_INTERRUPT; 1401 unless defined $HAVE_ASYNC_INTERRUPT;
1328 1402
1329 $HAVE_ASYNC_INTERRUPT 1403 $HAVE_ASYNC_INTERRUPT
1330} 1404}
1331 1405
1334our ($SIG_COUNT, $SIG_TW); 1408our ($SIG_COUNT, $SIG_TW);
1335 1409
1336sub _signal_exec { 1410sub _signal_exec {
1337 $HAVE_ASYNC_INTERRUPT 1411 $HAVE_ASYNC_INTERRUPT
1338 ? $SIGPIPE_R->drain 1412 ? $SIGPIPE_R->drain
1339 : sysread $SIGPIPE_R, my $dummy, 9; 1413 : sysread $SIGPIPE_R, (my $dummy), 9;
1340 1414
1341 while (%SIG_EV) { 1415 while (%SIG_EV) {
1342 for (keys %SIG_EV) { 1416 for (keys %SIG_EV) {
1343 delete $SIG_EV{$_}; 1417 delete $SIG_EV{$_};
1344 $_->() for values %{ $SIG_CB{$_} || {} }; 1418 $_->() for values %{ $SIG_CB{$_} || {} };
1348 1422
1349# install a dummy wakeup watcher to reduce signal catching latency 1423# install a dummy wakeup watcher to reduce signal catching latency
1350sub _sig_add() { 1424sub _sig_add() {
1351 unless ($SIG_COUNT++) { 1425 unless ($SIG_COUNT++) {
1352 # try to align timer on a full-second boundary, if possible 1426 # try to align timer on a full-second boundary, if possible
1353 my $NOW = AnyEvent->now; 1427 my $NOW = AE::now;
1354 1428
1355 $SIG_TW = AnyEvent->timer ( 1429 $SIG_TW = AE::timer
1356 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW), 1430 $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1357 interval => $MAX_SIGNAL_LATENCY, 1431 $MAX_SIGNAL_LATENCY,
1358 cb => sub { }, # just for the PERL_ASYNC_CHECK 1432 sub { } # just for the PERL_ASYNC_CHECK
1359 ); 1433 ;
1360 } 1434 }
1361} 1435}
1362 1436
1363sub _sig_del { 1437sub _sig_del {
1364 undef $SIG_TW 1438 undef $SIG_TW
1401 # probe for availability of Async::Interrupt 1475 # probe for availability of Async::Interrupt
1402 if (_have_async_interrupt) { 1476 if (_have_async_interrupt) {
1403 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1477 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1404 1478
1405 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1479 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1406 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec); 1480 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1407 1481
1408 } else { 1482 } else {
1409 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1483 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1410 1484
1411 require Fcntl; 1485 require Fcntl;
1427 } 1501 }
1428 1502
1429 $SIGPIPE_R 1503 $SIGPIPE_R
1430 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1504 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1431 1505
1432 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1506 $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec;
1433 } 1507 }
1434 1508
1435 *signal = sub { 1509 *signal = sub {
1436 my (undef, %arg) = @_; 1510 my (undef, %arg) = @_;
1437 1511
1526 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/ 1600 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1527 ? 1 1601 ? 1
1528 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1602 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1529 1603
1530 unless ($CHLD_W) { 1604 unless ($CHLD_W) {
1531 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1605 $CHLD_W = AE::signal CHLD => \&_sigchld;
1532 # child could be a zombie already, so make at least one round 1606 # child could be a zombie already, so make at least one round
1533 &_sigchld; 1607 &_sigchld;
1534 } 1608 }
1535 1609
1536 bless [$pid, $arg{cb}], "AnyEvent::Base::child" 1610 bless [$pid, $arg{cb}], "AnyEvent::Base::child"
1562 # never use more then 50% of the time for the idle watcher, 1636 # never use more then 50% of the time for the idle watcher,
1563 # within some limits 1637 # within some limits
1564 $w = 0.0001 if $w < 0.0001; 1638 $w = 0.0001 if $w < 0.0001;
1565 $w = 5 if $w > 5; 1639 $w = 5 if $w > 5;
1566 1640
1567 $w = AnyEvent->timer (after => $w, cb => $rcb); 1641 $w = AE::timer $w, 0, $rcb;
1568 } else { 1642 } else {
1569 # clean up... 1643 # clean up...
1570 undef $w; 1644 undef $w;
1571 undef $rcb; 1645 undef $rcb;
1572 } 1646 }
1573 }; 1647 };
1574 1648
1575 $w = AnyEvent->timer (after => 0.05, cb => $rcb); 1649 $w = AE::timer 0.05, 0, $rcb;
1576 1650
1577 bless \\$cb, "AnyEvent::Base::idle" 1651 bless \\$cb, "AnyEvent::Base::idle"
1578} 1652}
1579 1653
1580sub AnyEvent::Base::idle::DESTROY { 1654sub AnyEvent::Base::idle::DESTROY {
1634 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak}; 1708 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak};
1635 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0] 1709 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0]
1636} 1710}
1637 1711
1638sub cb { 1712sub cb {
1639 $_[0]{_ae_cb} = $_[1] if @_ > 1; 1713 my $cv = shift;
1714
1715 @_
1716 and $cv->{_ae_cb} = shift
1717 and $cv->{_ae_sent}
1718 and (delete $cv->{_ae_cb})->($cv);
1719
1640 $_[0]{_ae_cb} 1720 $cv->{_ae_cb}
1641} 1721}
1642 1722
1643sub begin { 1723sub begin {
1644 ++$_[0]{_ae_counter}; 1724 ++$_[0]{_ae_counter};
1645 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 1725 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
1651} 1731}
1652 1732
1653# undocumented/compatibility with pre-3.4 1733# undocumented/compatibility with pre-3.4
1654*broadcast = \&send; 1734*broadcast = \&send;
1655*wait = \&_wait; 1735*wait = \&_wait;
1656
1657#############################################################################
1658# "new" API, currently only emulation of it
1659#############################################################################
1660
1661package AE;
1662
1663sub io($$$) {
1664 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1665}
1666
1667sub timer($$$) {
1668 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]);
1669}
1670
1671sub signal($$) {
1672 AnyEvent->signal (signal => $_[0], cb => $_[1]);
1673}
1674
1675sub child($$) {
1676 AnyEvent->child (pid => $_[0], cb => $_[1]);
1677}
1678
1679sub idle($) {
1680 AnyEvent->idle (cb => $_[0]);
1681}
1682
1683sub cv() {
1684 AnyEvent->condvar
1685}
1686
1687sub now() {
1688 AnyEvent->now
1689}
1690
1691sub now_update() {
1692 AnyEvent->now_update
1693}
1694
1695sub time() {
1696 AnyEvent->time
1697}
1698 1736
1699=head1 ERROR AND EXCEPTION HANDLING 1737=head1 ERROR AND EXCEPTION HANDLING
1700 1738
1701In general, AnyEvent does not do any error handling - it relies on the 1739In general, AnyEvent does not do any error handling - it relies on the
1702caller to do that if required. The L<AnyEvent::Strict> module (see also 1740caller to do that if required. The L<AnyEvent::Strict> module (see also
1896 warn "read: $input\n"; # output what has been read 1934 warn "read: $input\n"; # output what has been read
1897 $cv->send if $input =~ /^q/i; # quit program if /^q/i 1935 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1898 }, 1936 },
1899 ); 1937 );
1900 1938
1901 my $time_watcher; # can only be used once
1902
1903 sub new_timer {
1904 $timer = AnyEvent->timer (after => 1, cb => sub { 1939 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
1905 warn "timeout\n"; # print 'timeout' about every second 1940 warn "timeout\n"; # print 'timeout' at most every second
1906 &new_timer; # and restart the time
1907 }); 1941 });
1908 }
1909
1910 new_timer; # create first timer
1911 1942
1912 $cv->recv; # wait until user enters /^q/i 1943 $cv->recv; # wait until user enters /^q/i
1913 1944
1914=head1 REAL-WORLD EXAMPLE 1945=head1 REAL-WORLD EXAMPLE
1915 1946
2046through AnyEvent. The benchmark creates a lot of timers (with a zero 2077through AnyEvent. The benchmark creates a lot of timers (with a zero
2047timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 2078timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
2048which it is), lets them fire exactly once and destroys them again. 2079which it is), lets them fire exactly once and destroys them again.
2049 2080
2050Source code for this benchmark is found as F<eg/bench> in the AnyEvent 2081Source code for this benchmark is found as F<eg/bench> in the AnyEvent
2051distribution. 2082distribution. It uses the L<AE> interface, which makes a real difference
2083for the EV and Perl backends only.
2052 2084
2053=head3 Explanation of the columns 2085=head3 Explanation of the columns
2054 2086
2055I<watcher> is the number of event watchers created/destroyed. Since 2087I<watcher> is the number of event watchers created/destroyed. Since
2056different event models feature vastly different performances, each event 2088different event models feature vastly different performances, each event
2077watcher. 2109watcher.
2078 2110
2079=head3 Results 2111=head3 Results
2080 2112
2081 name watchers bytes create invoke destroy comment 2113 name watchers bytes create invoke destroy comment
2082 EV/EV 400000 224 0.47 0.35 0.27 EV native interface 2114 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
2083 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 2115 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
2084 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 2116 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
2085 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 2117 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
2086 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 2118 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
2087 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 2119 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
2088 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll 2120 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
2089 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll 2121 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
2090 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 2122 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
2091 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 2123 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
2092 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 2124 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
2093 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 2125 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
2094 2126
2095=head3 Discussion 2127=head3 Discussion
2096 2128
2097The benchmark does I<not> measure scalability of the event loop very 2129The benchmark does I<not> measure scalability of the event loop very
2098well. For example, a select-based event loop (such as the pure perl one) 2130well. For example, a select-based event loop (such as the pure perl one)
2110benchmark machine, handling an event takes roughly 1600 CPU cycles with 2142benchmark machine, handling an event takes roughly 1600 CPU cycles with
2111EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU 2143EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU
2112cycles with POE. 2144cycles with POE.
2113 2145
2114C<EV> is the sole leader regarding speed and memory use, which are both 2146C<EV> is the sole leader regarding speed and memory use, which are both
2115maximal/minimal, respectively. Even when going through AnyEvent, it uses 2147maximal/minimal, respectively. When using the L<AE> API there is zero
2148overhead (when going through the AnyEvent API create is about 5-6 times
2149slower, with other times being equal, so still uses far less memory than
2116far less memory than any other event loop and is still faster than Event 2150any other event loop and is still faster than Event natively).
2117natively.
2118 2151
2119The pure perl implementation is hit in a few sweet spots (both the 2152The pure perl implementation is hit in a few sweet spots (both the
2120constant timeout and the use of a single fd hit optimisations in the perl 2153constant timeout and the use of a single fd hit optimisations in the perl
2121interpreter and the backend itself). Nevertheless this shows that it 2154interpreter and the backend itself). Nevertheless this shows that it
2122adds very little overhead in itself. Like any select-based backend its 2155adds very little overhead in itself. Like any select-based backend its
2196In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100 2229In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
2197(1%) are active. This mirrors the activity of large servers with many 2230(1%) are active. This mirrors the activity of large servers with many
2198connections, most of which are idle at any one point in time. 2231connections, most of which are idle at any one point in time.
2199 2232
2200Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 2233Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
2201distribution. 2234distribution. It uses the L<AE> interface, which makes a real difference
2235for the EV and Perl backends only.
2202 2236
2203=head3 Explanation of the columns 2237=head3 Explanation of the columns
2204 2238
2205I<sockets> is the number of sockets, and twice the number of "servers" (as 2239I<sockets> is the number of sockets, and twice the number of "servers" (as
2206each server has a read and write socket end). 2240each server has a read and write socket end).
2214a new one that moves the timeout into the future. 2248a new one that moves the timeout into the future.
2215 2249
2216=head3 Results 2250=head3 Results
2217 2251
2218 name sockets create request 2252 name sockets create request
2219 EV 20000 69.01 11.16 2253 EV 20000 62.66 7.99
2220 Perl 20000 73.32 35.87 2254 Perl 20000 68.32 32.64
2221 IOAsync 20000 157.00 98.14 epoll 2255 IOAsync 20000 174.06 101.15 epoll
2222 IOAsync 20000 159.31 616.06 poll 2256 IOAsync 20000 174.67 610.84 poll
2223 Event 20000 212.62 257.32 2257 Event 20000 202.69 242.91
2224 Glib 20000 651.16 1896.30 2258 Glib 20000 557.01 1689.52
2225 POE 20000 349.67 12317.24 uses POE::Loop::Event 2259 POE 20000 341.54 12086.32 uses POE::Loop::Event
2226 2260
2227=head3 Discussion 2261=head3 Discussion
2228 2262
2229This benchmark I<does> measure scalability and overall performance of the 2263This benchmark I<does> measure scalability and overall performance of the
2230particular event loop. 2264particular event loop.
2356As you can see, the AnyEvent + EV combination even beats the 2390As you can see, the AnyEvent + EV combination even beats the
2357hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl 2391hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
2358backend easily beats IO::Lambda and POE. 2392backend easily beats IO::Lambda and POE.
2359 2393
2360And even the 100% non-blocking version written using the high-level (and 2394And even the 100% non-blocking version written using the high-level (and
2361slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a 2395slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda
2362large margin, even though it does all of DNS, tcp-connect and socket I/O 2396higher level ("unoptimised") abstractions by a large margin, even though
2363in a non-blocking way. 2397it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
2364 2398
2365The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and 2399The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
2366F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are 2400F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2367part of the IO::lambda distribution and were used without any changes. 2401part of the IO::Lambda distribution and were used without any changes.
2368 2402
2369 2403
2370=head1 SIGNALS 2404=head1 SIGNALS
2371 2405
2372AnyEvent currently installs handlers for these signals: 2406AnyEvent currently installs handlers for these signals:
2414it's built-in modules) are required to use it. 2448it's built-in modules) are required to use it.
2415 2449
2416That does not mean that AnyEvent won't take advantage of some additional 2450That does not mean that AnyEvent won't take advantage of some additional
2417modules if they are installed. 2451modules if they are installed.
2418 2452
2419This section epxlains which additional modules will be used, and how they 2453This section explains which additional modules will be used, and how they
2420affect AnyEvent's operetion. 2454affect AnyEvent's operation.
2421 2455
2422=over 4 2456=over 4
2423 2457
2424=item L<Async::Interrupt> 2458=item L<Async::Interrupt>
2425 2459
2430catch the signals) with some delay (default is 10 seconds, look for 2464catch the signals) with some delay (default is 10 seconds, look for
2431C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2465C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2432 2466
2433If this module is available, then it will be used to implement signal 2467If this module is available, then it will be used to implement signal
2434catching, which means that signals will not be delayed, and the event loop 2468catching, which means that signals will not be delayed, and the event loop
2435will not be interrupted regularly, which is more efficient (And good for 2469will not be interrupted regularly, which is more efficient (and good for
2436battery life on laptops). 2470battery life on laptops).
2437 2471
2438This affects not just the pure-perl event loop, but also other event loops 2472This affects not just the pure-perl event loop, but also other event loops
2439that have no signal handling on their own (e.g. Glib, Tk, Qt). 2473that have no signal handling on their own (e.g. Glib, Tk, Qt).
2440 2474
2461lot less memory), but otherwise doesn't affect guard operation much. It is 2495lot less memory), but otherwise doesn't affect guard operation much. It is
2462purely used for performance. 2496purely used for performance.
2463 2497
2464=item L<JSON> and L<JSON::XS> 2498=item L<JSON> and L<JSON::XS>
2465 2499
2466This module is required when you want to read or write JSON data via 2500One of these modules is required when you want to read or write JSON data
2467L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2501via L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2468advantage of the ultra-high-speed L<JSON::XS> module when it is installed. 2502advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2469 2503
2470In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is 2504In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2471installed. 2505installed.
2472 2506
2490 2524
2491Most event libraries are not fork-safe. The ones who are usually are 2525Most event libraries are not fork-safe. The ones who are usually are
2492because they rely on inefficient but fork-safe C<select> or C<poll> 2526because they rely on inefficient but fork-safe C<select> or C<poll>
2493calls. Only L<EV> is fully fork-aware. 2527calls. Only L<EV> is fully fork-aware.
2494 2528
2529This means that, in general, you cannot fork and do event processing
2530in the child if a watcher was created before the fork (which in turn
2531initialises the event library).
2532
2495If you have to fork, you must either do so I<before> creating your first 2533If you have to fork, you must either do so I<before> creating your first
2496watcher OR you must not use AnyEvent at all in the child OR you must do 2534watcher OR you must not use AnyEvent at all in the child OR you must do
2497something completely out of the scope of AnyEvent. 2535something completely out of the scope of AnyEvent.
2536
2537The problem of doing event processing in the parent I<and> the child
2538is much more complicated: even for backends that I<are> fork-aware or
2539fork-safe, their behaviour is not usually what you want: fork clones all
2540watchers, that means all timers, I/O watchers etc. are active in both
2541parent and child, which is almost never what you want.
2498 2542
2499 2543
2500=head1 SECURITY CONSIDERATIONS 2544=head1 SECURITY CONSIDERATIONS
2501 2545
2502AnyEvent can be forced to load any event model via 2546AnyEvent can be forced to load any event model via

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines