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.379 by root, Fri Aug 26 18:09:04 2011 UTC vs.
Revision 1.414 by root, Wed Aug 21 08:40:28 2013 UTC

271 271
272Example 2: fire an event after 0.5 seconds, then roughly every second. 272Example 2: fire an event after 0.5 seconds, then roughly every second.
273 273
274 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub { 274 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
275 warn "timeout\n"; 275 warn "timeout\n";
276 }; 276 });
277 277
278=head3 TIMING ISSUES 278=head3 TIMING ISSUES
279 279
280There are two ways to handle timers: based on real time (relative, "fire 280There are two ways to handle timers: based on real time (relative, "fire
281in 10 seconds") and based on wallclock time (absolute, "fire at 12 281in 10 seconds") and based on wallclock time (absolute, "fire at 12
415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's 415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's
416pure perl implementation). 416pure perl implementation).
417 417
418=head3 Safe/Unsafe Signals 418=head3 Safe/Unsafe Signals
419 419
420Perl signals can be either "safe" (synchronous to opcode handling) or 420Perl signals can be either "safe" (synchronous to opcode handling)
421"unsafe" (asynchronous) - the former might get delayed indefinitely, the 421or "unsafe" (asynchronous) - the former might delay signal delivery
422latter might corrupt your memory. 422indefinitely, the latter might corrupt your memory.
423 423
424AnyEvent signal handlers are, in addition, synchronous to the event loop, 424AnyEvent signal handlers are, in addition, synchronous to the event loop,
425i.e. they will not interrupt your running perl program but will only be 425i.e. they will not interrupt your running perl program but will only be
426called as part of the normal event handling (just like timer, I/O etc. 426called as part of the normal event handling (just like timer, I/O etc.
427callbacks, too). 427callbacks, too).
428 428
429=head3 Signal Races, Delays and Workarounds 429=head3 Signal Races, Delays and Workarounds
430 430
431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support
432callbacks to signals in a generic way, which is a pity, as you cannot 432attaching callbacks to signals in a generic way, which is a pity,
433do race-free signal handling in perl, requiring C libraries for 433as you cannot do race-free signal handling in perl, requiring
434this. AnyEvent will try to do its best, which means in some cases, 434C libraries for this. AnyEvent will try to do its best, which
435signals will be delayed. The maximum time a signal might be delayed is 435means in some cases, signals will be delayed. The maximum time
436specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This 436a signal might be delayed is 10 seconds by default, but can
437variable can be changed only before the first signal watcher is created, 437be overriden via C<$ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY}> or
438and should be left alone otherwise. This variable determines how often 438C<$AnyEvent::MAX_SIGNAL_LATENCY> - see the L<ENVIRONMENT VARIABLES>
439AnyEvent polls for signals (in case a wake-up was missed). Higher values 439section for details.
440will cause fewer spurious wake-ups, which is better for power and CPU
441saving.
442 440
443All these problems can be avoided by installing the optional 441All these problems can be avoided by installing the optional
444L<Async::Interrupt> module, which works with most event loops. It will not 442L<Async::Interrupt> module, which works with most event loops. It will not
445work with inherently broken event loops such as L<Event> or L<Event::Lib> 443work with inherently broken event loops such as L<Event> or L<Event::Lib>
446(and not with L<POE> currently, as POE does its own workaround with 444(and not with L<POE> currently). For those, you just have to suffer the
447one-second latency). For those, you just have to suffer the delays. 445delays.
448 446
449=head2 CHILD PROCESS WATCHERS 447=head2 CHILD PROCESS WATCHERS
450 448
451 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 449 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
452 450
765 }; 763 };
766 } 764 }
767 765
768 $cv->end; 766 $cv->end;
769 767
768 ...
769
770 my $results = $cv->recv;
771
770This code fragment supposedly pings a number of hosts and calls 772This code fragment supposedly pings a number of hosts and calls
771C<send> after results for all then have have been gathered - in any 773C<send> after results for all then have have been gathered - in any
772order. To achieve this, the code issues a call to C<begin> when it starts 774order. To achieve this, the code issues a call to C<begin> when it starts
773each ping request and calls C<end> when it has received some result for 775each ping request and calls C<end> when it has received some result for
774it. Since C<begin> and C<end> only maintain a counter, the order in which 776it. Since C<begin> and C<end> only maintain a counter, the order in which
809 811
810In list context, all parameters passed to C<send> will be returned, 812In list context, all parameters passed to C<send> will be returned,
811in scalar context only the first one will be returned. 813in scalar context only the first one will be returned.
812 814
813Note that doing a blocking wait in a callback is not supported by any 815Note that doing a blocking wait in a callback is not supported by any
814event loop, that is, recursive invocation of a blocking C<< ->recv 816event loop, that is, recursive invocation of a blocking C<< ->recv >> is
815>> is not allowed, and the C<recv> call will C<croak> if such a 817not allowed and the C<recv> call will C<croak> if such a condition is
816condition is detected. This condition can be slightly loosened by using 818detected. This requirement can be dropped by relying on L<Coro::AnyEvent>
817L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from 819, which allows you to do a blocking C<< ->recv >> from any thread
818any thread that doesn't run the event loop itself. 820that doesn't run the event loop itself. L<Coro::AnyEvent> is loaded
821automatically when L<Coro> is used with L<AnyEvent>, so code does not need
822to do anything special to take advantage of that: any code that would
823normally block your program because it calls C<recv>, be executed in an
824C<async> thread instead without blocking other threads.
819 825
820Not all event models support a blocking wait - some die in that case 826Not all event models support a blocking wait - some die in that case
821(programs might want to do that to stay interactive), so I<if you are 827(programs might want to do that to stay interactive), so I<if you are
822using this from a module, never require a blocking wait>. Instead, let the 828using this from a module, never require a blocking wait>. Instead, let the
823caller decide whether the call will block or not (for example, by coupling 829caller decide whether the call will block or not (for example, by coupling
1058If L<AnyEvent::Log> is not loaded then this function makes a simple test 1064If L<AnyEvent::Log> is not loaded then this function makes a simple test
1059to see whether the message will be logged. If the test succeeds it will 1065to see whether the message will be logged. If the test succeeds it will
1060load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at 1066load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1061the L<AnyEvent::Log> documentation for details. 1067the L<AnyEvent::Log> documentation for details.
1062 1068
1063If the test fails it will simply return. 1069If the test fails it will simply return. Right now this happens when a
1070numerical loglevel is used and it is larger than the level specified via
1071C<$ENV{PERL_ANYEVENT_VERBOSE}>.
1064 1072
1065If you want to sprinkle loads of logging calls around your code, consider 1073If you want to sprinkle loads of logging calls around your code, consider
1066creating a logger callback with the C<AnyEvent::Log::logger> function, 1074creating a logger callback with the C<AnyEvent::Log::logger> function,
1067which can reduce typing, codesize and can reduce the logging overhead 1075which can reduce typing, codesize and can reduce the logging overhead
1068enourmously. 1076enourmously.
1139a longer non-exhaustive list), and the list is heavily biased towards 1147a longer non-exhaustive list), and the list is heavily biased towards
1140modules of the AnyEvent author himself :) 1148modules of the AnyEvent author himself :)
1141 1149
1142=over 4 1150=over 4
1143 1151
1144=item L<AnyEvent::Util> 1152=item L<AnyEvent::Util> (part of the AnyEvent distribution)
1145 1153
1146Contains various utility functions that replace often-used blocking 1154Contains various utility functions that replace often-used blocking
1147functions such as C<inet_aton> with event/callback-based versions. 1155functions such as C<inet_aton> with event/callback-based versions.
1148 1156
1149=item L<AnyEvent::Socket> 1157=item L<AnyEvent::Socket> (part of the AnyEvent distribution)
1150 1158
1151Provides various utility functions for (internet protocol) sockets, 1159Provides various utility functions for (internet protocol) sockets,
1152addresses and name resolution. Also functions to create non-blocking tcp 1160addresses and name resolution. Also functions to create non-blocking tcp
1153connections or tcp servers, with IPv6 and SRV record support and more. 1161connections or tcp servers, with IPv6 and SRV record support and more.
1154 1162
1155=item L<AnyEvent::Handle> 1163=item L<AnyEvent::Handle> (part of the AnyEvent distribution)
1156 1164
1157Provide read and write buffers, manages watchers for reads and writes, 1165Provide read and write buffers, manages watchers for reads and writes,
1158supports raw and formatted I/O, I/O queued and fully transparent and 1166supports raw and formatted I/O, I/O queued and fully transparent and
1159non-blocking SSL/TLS (via L<AnyEvent::TLS>). 1167non-blocking SSL/TLS (via L<AnyEvent::TLS>).
1160 1168
1161=item L<AnyEvent::DNS> 1169=item L<AnyEvent::DNS> (part of the AnyEvent distribution)
1162 1170
1163Provides rich asynchronous DNS resolver capabilities. 1171Provides rich asynchronous DNS resolver capabilities.
1164 1172
1165=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP> 1173=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1166 1174
1167Implement event-based interfaces to the protocols of the same name (for 1175Implement event-based interfaces to the protocols of the same name (for
1168the curious, IGS is the International Go Server and FCP is the Freenet 1176the curious, IGS is the International Go Server and FCP is the Freenet
1169Client Protocol). 1177Client Protocol).
1170 1178
1171=item L<AnyEvent::AIO> 1179=item L<AnyEvent::AIO> (part of the AnyEvent distribution)
1172 1180
1173Truly asynchronous (as opposed to non-blocking) I/O, should be in the 1181Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1174toolbox of every event programmer. AnyEvent::AIO transparently fuses 1182toolbox of every event programmer. AnyEvent::AIO transparently fuses
1175L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1183L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1176file I/O, and much more. 1184file I/O, and much more.
1221 1229
1222=cut 1230=cut
1223 1231
1224package AnyEvent; 1232package AnyEvent;
1225 1233
1226# basically a tuned-down version of common::sense
1227sub common_sense {
1228 # from common:.sense 3.4
1229 ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "\x3c\x3f\x33\x00\x0f\xf0\x0f\xc0\xf0\xfc\x33\x00";
1230 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1231 $^H |= 0x00000600;
1232}
1233
1234BEGIN { AnyEvent::common_sense }
1235
1236use Carp ();
1237
1238our $VERSION = '6.02';
1239our $MODEL;
1240
1241our @ISA;
1242
1243our @REGISTRY;
1244
1245our $VERBOSE;
1246
1247BEGIN { 1234BEGIN {
1248 require "AnyEvent/constants.pl"; 1235 require "AnyEvent/constants.pl";
1236 &AnyEvent::common_sense;
1237}
1249 1238
1239use Carp ();
1240
1241our $VERSION = '7.05';
1242our $MODEL;
1243our @ISA;
1244our @REGISTRY;
1245our $VERBOSE;
1246our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1247our $MAX_SIGNAL_LATENCY = $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} || 10; # executes after the BEGIN block below (tainting!)
1248
1249BEGIN {
1250 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1250 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1251 1251
1252 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1252 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1253 if ${^TAINT}; 1253 if ${^TAINT};
1254 1254
1256 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV; 1256 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1257 1257
1258 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = () 1258 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1259 if ${^TAINT}; 1259 if ${^TAINT};
1260 1260
1261 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1261 # $ENV{PERL_ANYEVENT_xxx} now valid
1262}
1263 1262
1264our $MAX_SIGNAL_LATENCY = 10; 1263 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1265 1264
1266our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1267
1268{
1269 my $idx; 1265 my $idx;
1270 $PROTOCOL{$_} = ++$idx 1266 $PROTOCOL{$_} = ++$idx
1271 for reverse split /\s*,\s*/, 1267 for reverse split /\s*,\s*/,
1272 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1268 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1273} 1269}
1306 () 1302 ()
1307} 1303}
1308 1304
1309sub log($$;@) { 1305sub log($$;@) {
1310 # only load the big bloated module when we actually are about to log something 1306 # only load the big bloated module when we actually are about to log something
1311 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!) 1307 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1312 require AnyEvent::Log; 1308 local ($!, $@);
1309 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1313 # AnyEvent::Log overwrites this function 1310 # AnyEvent::Log overwrites this function
1314 goto &log; 1311 goto &log;
1315 } 1312 }
1316 1313
1317 0 # not logged 1314 0 # not logged
1318} 1315}
1319 1316
1317sub _logger($;$) {
1318 my ($level, $renabled) = @_;
1319
1320 $$renabled = $level <= $VERBOSE;
1321
1322 my $logger = [(caller)[0], $level, $renabled];
1323
1324 $AnyEvent::Log::LOGGER{$logger+0} = $logger;
1325
1326# return unless defined wantarray;
1327#
1328# require AnyEvent::Util;
1329# my $guard = AnyEvent::Util::guard (sub {
1330# # "clean up"
1331# delete $LOGGER{$logger+0};
1332# });
1333#
1334# sub {
1335# return 0 unless $$renabled;
1336#
1337# $guard if 0; # keep guard alive, but don't cause runtime overhead
1338# require AnyEvent::Log unless $AnyEvent::Log::VERSION;
1339# package AnyEvent::Log;
1340# _log ($logger->[0], $level, @_) # logger->[0] has been converted at load time
1341# }
1342}
1343
1320if (length $ENV{PERL_ANYEVENT_LOG}) { 1344if (length $ENV{PERL_ANYEVENT_LOG}) {
1321 require AnyEvent::Log; # AnyEvent::Log does the thing for us 1345 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1322} 1346}
1323 1347
1324our @models = ( 1348our @models = (
1325 [EV:: => AnyEvent::Impl::EV:: , 1], 1349 [EV:: => AnyEvent::Impl::EV::],
1326 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1350 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1327 # everything below here will not (normally) be autoprobed 1351 # everything below here will not (normally) be autoprobed
1328 # as the pure perl backend should work everywhere 1352 # as the pure perl backend should work everywhere
1329 # and is usually faster 1353 # and is usually faster
1354 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package, so msut be near the top
1330 [Event:: => AnyEvent::Impl::Event::, 1], 1355 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1331 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1356 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1357 # everything below here should not be autoloaded
1332 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1358 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1333 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1334 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1359 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1335 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1360 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1336 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1361 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1337 [Wx:: => AnyEvent::Impl::POE::], 1362 [Wx:: => AnyEvent::Impl::POE::],
1338 [Prima:: => AnyEvent::Impl::POE::], 1363 [Prima:: => AnyEvent::Impl::POE::],
1367our @methods = qw(io timer time now now_update signal child idle condvar); 1392our @methods = qw(io timer time now now_update signal child idle condvar);
1368 1393
1369sub detect() { 1394sub detect() {
1370 return $MODEL if $MODEL; # some programs keep references to detect 1395 return $MODEL if $MODEL; # some programs keep references to detect
1371 1396
1397 # IO::Async::Loop::AnyEvent is extremely evil, refuse to work with it
1398 # the author knows about the problems and what it does to AnyEvent as a whole
1399 # (and the ability of others to use AnyEvent), but simply wants to abuse AnyEvent
1400 # anyway.
1401 AnyEvent::log fatal => "IO::Async::Loop::AnyEvent detected - that module is broken by\n"
1402 . "design, abuses internals and breaks AnyEvent - will not continue."
1403 if exists $INC{"IO/Async/Loop/AnyEvent.pm"};
1404
1372 local $!; # for good measure 1405 local $!; # for good measure
1373 local $SIG{__DIE__}; # we use eval 1406 local $SIG{__DIE__}; # we use eval
1374 1407
1375 # free some memory 1408 # free some memory
1376 *detect = sub () { $MODEL }; 1409 *detect = sub () { $MODEL };
1384 1417
1385 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1418 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1386 my $model = $1; 1419 my $model = $1;
1387 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1420 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1388 if (eval "require $model") { 1421 if (eval "require $model") {
1389 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."; 1422 AnyEvent::log 7 => "Loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1390 $MODEL = $model; 1423 $MODEL = $model;
1391 } else { 1424 } else {
1392 AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@"; 1425 AnyEvent::log 4 => "Unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1393 } 1426 }
1394 } 1427 }
1395 1428
1396 # check for already loaded models 1429 # check for already loaded models
1397 unless ($MODEL) { 1430 unless ($MODEL) {
1398 for (@REGISTRY, @models) { 1431 for (@REGISTRY, @models) {
1399 my ($package, $model) = @$_; 1432 my ($package, $model) = @$_;
1400 if (${"$package\::VERSION"} > 0) { 1433 if (${"$package\::VERSION"} > 0) {
1401 if (eval "require $model") { 1434 if (eval "require $model") {
1402 AnyEvent::log 7 => "autodetected model '$model', using it."; 1435 AnyEvent::log 7 => "Autodetected model '$model', using it.";
1436 $MODEL = $model;
1437 last;
1438 } else {
1439 AnyEvent::log 8 => "Detected event loop $package, but cannot load '$model', skipping: $@";
1440 }
1441 }
1442 }
1443
1444 unless ($MODEL) {
1445 # try to autoload a model
1446 for (@REGISTRY, @models) {
1447 my ($package, $model) = @$_;
1448 if (
1449 eval "require $package"
1450 and ${"$package\::VERSION"} > 0
1451 and eval "require $model"
1452 ) {
1453 AnyEvent::log 7 => "Autoloaded model '$model', using it.";
1403 $MODEL = $model; 1454 $MODEL = $model;
1404 last; 1455 last;
1405 } 1456 }
1406 } 1457 }
1407 }
1408
1409 unless ($MODEL) {
1410 # try to autoload a model
1411 for (@REGISTRY, @models) {
1412 my ($package, $model, $autoload) = @$_;
1413 if (
1414 $autoload
1415 and eval "require $package"
1416 and ${"$package\::VERSION"} > 0
1417 and eval "require $model"
1418 ) {
1419 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1420 $MODEL = $model;
1421 last;
1422 }
1423 }
1424 1458
1425 $MODEL 1459 $MODEL
1426 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?"; 1460 or AnyEvent::log fatal => "Backend autodetection failed - did you properly install AnyEvent?";
1427 } 1461 }
1428 } 1462 }
1429 1463
1430 # free memory only needed for probing 1464 # free memory only needed for probing
1431 undef @models; 1465 undef @models;
1578 # probe for availability of Time::HiRes 1612 # probe for availability of Time::HiRes
1579 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1613 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1580 *time = sub { Time::HiRes::time () }; 1614 *time = sub { Time::HiRes::time () };
1581 *AE::time = \& Time::HiRes::time ; 1615 *AE::time = \& Time::HiRes::time ;
1582 *now = \&time; 1616 *now = \&time;
1583 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy."; 1617 AnyEvent::log 8 => "using Time::HiRes for sub-second timing accuracy.";
1584 # if (eval "use POSIX (); (POSIX::times())... 1618 # if (eval "use POSIX (); (POSIX::times())...
1585 } else { 1619 } else {
1586 *time = sub { CORE::time }; 1620 *time = sub { CORE::time };
1587 *AE::time = sub (){ CORE::time }; 1621 *AE::time = sub (){ CORE::time };
1588 *now = \&time; 1622 *now = \&time;
1589 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!"; 1623 AnyEvent::log 3 => "Using built-in time(), no sub-second resolution!";
1590 } 1624 }
1591 }; 1625 };
1592 die if $@; 1626 die if $@;
1593 1627
1594 &time 1628 &time
1688 1722
1689sub signal { 1723sub signal {
1690 eval q{ # poor man's autoloading {} 1724 eval q{ # poor man's autoloading {}
1691 # probe for availability of Async::Interrupt 1725 # probe for availability of Async::Interrupt
1692 if (_have_async_interrupt) { 1726 if (_have_async_interrupt) {
1693 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling."; 1727 AnyEvent::log 8 => "Using Async::Interrupt for race-free signal handling.";
1694 1728
1695 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1729 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1696 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1730 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1697 1731
1698 } else { 1732 } else {
1699 AnyEvent::log 8 => "using emulated perl signal handling with latency timer."; 1733 AnyEvent::log 8 => "Using emulated perl signal handling with latency timer.";
1700 1734
1701 if (AnyEvent::WIN32) { 1735 if (AnyEvent::WIN32) {
1702 require AnyEvent::Util; 1736 require AnyEvent::Util;
1703 1737
1704 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1738 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
2040 2074
2041=over 4 2075=over 4
2042 2076
2043=item C<PERL_ANYEVENT_VERBOSE> 2077=item C<PERL_ANYEVENT_VERBOSE>
2044 2078
2045By default, AnyEvent will be completely silent except in fatal 2079By default, AnyEvent will log messages with loglevel C<4> (C<error>) or
2046conditions. You can set this environment variable to make AnyEvent more 2080higher (see L<AnyEvent::Log>). You can set this environment variable to a
2081numerical loglevel to make AnyEvent more (or less) talkative.
2082
2047talkative. If you want to do more than just set the global logging level 2083If you want to do more than just set the global logging level
2048you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more 2084you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2049complex specifications. 2085complex specifications.
2050 2086
2087When set to C<0> (C<off>), then no messages whatsoever will be logged with
2088everything else at defaults.
2089
2051When set to C<5> or higher (warn), causes AnyEvent to warn about unexpected 2090When set to C<5> or higher (C<warn>), AnyEvent warns about unexpected
2052conditions, such as not being able to load the event model specified by 2091conditions, such as not being able to load the event model specified by
2053C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this 2092C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
2054is the minimum recommended level. 2093is the minimum recommended level for use during development.
2055 2094
2056When set to C<7> or higher (info), cause AnyEvent to report which event model it 2095When set to C<7> or higher (info), AnyEvent reports which event model it
2057chooses. 2096chooses.
2058 2097
2059When set to C<8> or higher (debug), then AnyEvent will report extra information on 2098When set to C<8> or higher (debug), then AnyEvent will report extra
2060which optional modules it loads and how it implements certain features. 2099information on which optional modules it loads and how it implements
2100certain features.
2061 2101
2062=item C<PERL_ANYEVENT_LOG> 2102=item C<PERL_ANYEVENT_LOG>
2063 2103
2064Accepts rather complex logging specifications. For example, you could log 2104Accepts rather complex logging specifications. For example, you could log
2065all C<debug> messages of some module to stderr, warnings and above to 2105all C<debug> messages of some module to stderr, warnings and above to
2072This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded, 2112This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2073so will take effect even before AnyEvent has initialised itself. 2113so will take effect even before AnyEvent has initialised itself.
2074 2114
2075Note that specifying this environment variable causes the L<AnyEvent::Log> 2115Note that specifying this environment variable causes the L<AnyEvent::Log>
2076module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only 2116module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2077using the latter saves a few hundred kB of memory until the first message 2117using the latter saves a few hundred kB of memory unless a module
2078is being logged. 2118explicitly needs the extra features of AnyEvent::Log.
2079 2119
2080=item C<PERL_ANYEVENT_STRICT> 2120=item C<PERL_ANYEVENT_STRICT>
2081 2121
2082AnyEvent does not do much argument checking by default, as thorough 2122AnyEvent does not do much argument checking by default, as thorough
2083argument checking is very costly. Setting this variable to a true value 2123argument checking is very costly. Setting this variable to a true value
2092C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2132C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
2093can be very useful, however. 2133can be very useful, however.
2094 2134
2095=item C<PERL_ANYEVENT_DEBUG_SHELL> 2135=item C<PERL_ANYEVENT_DEBUG_SHELL>
2096 2136
2097If this env variable is set, then its contents will be interpreted by 2137If this env variable is nonempty, then its contents will be interpreted by
2098C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2138C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
2099C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on 2139replacing every occurance of C<$$> by the process pid). The shell object
2100that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2140is saved in C<$AnyEvent::Debug::SHELL>.
2101 2141
2102This happens when the first watcher is created. 2142This happens when the first watcher is created.
2103 2143
2104For example, to bind a debug shell on a unix domain socket in 2144For example, to bind a debug shell on a unix domain socket in
2105F<< /tmp/debug<pid>.sock >>, you could use this: 2145F<< /tmp/debug<pid>.sock >>, you could use this:
2106 2146
2107 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 2147 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2148 # connect with e.g.: socat readline /tmp/debug123.sock
2108 2149
2150Or to bind to tcp port 4545 on localhost:
2151
2152 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
2153 # connect with e.g.: telnet localhost 4545
2154
2109Note that creating sockets in F</tmp> is very unsafe on multiuser 2155Note that creating sockets in F</tmp> or on localhost is very unsafe on
2110systems. 2156multiuser systems.
2111 2157
2112=item C<PERL_ANYEVENT_DEBUG_WRAP> 2158=item C<PERL_ANYEVENT_DEBUG_WRAP>
2113 2159
2114Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for 2160Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2115debugging purposes. See C<AnyEvent::Debug::wrap> for details. 2161debugging purposes. See C<AnyEvent::Debug::wrap> for details.
2132For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you 2178For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
2133could start your program like this: 2179could start your program like this:
2134 2180
2135 PERL_ANYEVENT_MODEL=Perl perl ... 2181 PERL_ANYEVENT_MODEL=Perl perl ...
2136 2182
2183=item C<PERL_ANYEVENT_IO_MODEL>
2184
2185The current file I/O model - see L<AnyEvent::IO> for more info.
2186
2187At the moment, only C<Perl> (small, pure-perl, synchronous) and
2188C<IOAIO> (truly asynchronous) are supported. The default is C<IOAIO> if
2189L<AnyEvent::AIO> can be loaded, otherwise it is C<Perl>.
2190
2137=item C<PERL_ANYEVENT_PROTOCOLS> 2191=item C<PERL_ANYEVENT_PROTOCOLS>
2138 2192
2139Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences 2193Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
2140for IPv4 or IPv6. The default is unspecified (and might change, or be the result 2194for IPv4 or IPv6. The default is unspecified (and might change, or be the result
2141of auto probing). 2195of auto probing).
2179=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS> 2233=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
2180 2234
2181The default value for the C<max_outstanding> parameter for the default DNS 2235The default value for the C<max_outstanding> parameter for the default DNS
2182resolver - this is the maximum number of parallel DNS requests that are 2236resolver - this is the maximum number of parallel DNS requests that are
2183sent to the DNS server. 2237sent to the DNS server.
2238
2239=item C<PERL_ANYEVENT_MAX_SIGNAL_LATENCY>
2240
2241Perl has inherently racy signal handling (you can basically choose between
2242losing signals and memory corruption) - pure perl event loops (including
2243C<AnyEvent::Loop>, when C<Async::Interrupt> isn't available) therefore
2244have to poll regularly to avoid losing signals.
2245
2246Some event loops are racy, but don't poll regularly, and some event loops
2247are written in C but are still racy. For those event loops, AnyEvent
2248installs a timer that regularly wakes up the event loop.
2249
2250By default, the interval for this timer is C<10> seconds, but you can
2251override this delay with this environment variable (or by setting
2252the C<$AnyEvent::MAX_SIGNAL_LATENCY> variable before creating signal
2253watchers).
2254
2255Lower values increase CPU (and energy) usage, higher values can introduce
2256long delays when reaping children or waiting for signals.
2257
2258The L<AnyEvent::Async> module, if available, will be used to avoid this
2259polling (with most event loops).
2184 2260
2185=item C<PERL_ANYEVENT_RESOLV_CONF> 2261=item C<PERL_ANYEVENT_RESOLV_CONF>
2186 2262
2187The absolute path to a F<resolv.conf>-style file to use instead of 2263The absolute path to a F<resolv.conf>-style file to use instead of
2188F</etc/resolv.conf> (or the OS-specific configuration) in the default 2264F</etc/resolv.conf> (or the OS-specific configuration) in the default
2845This module is part of perl since release 5.008. It will be used when the 2921This module is part of perl since release 5.008. It will be used when the
2846chosen event library does not come with a timing source of its own. The 2922chosen event library does not come with a timing source of its own. The
2847pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to 2923pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to
2848try to use a monotonic clock for timing stability. 2924try to use a monotonic clock for timing stability.
2849 2925
2926=item L<AnyEvent::AIO> (and L<IO::AIO>)
2927
2928The default implementation of L<AnyEvent::IO> is to do I/O synchronously,
2929stopping programs while they access the disk, which is fine for a lot of
2930programs.
2931
2932Installing AnyEvent::AIO (and its IO::AIO dependency) makes it switch to
2933a true asynchronous implementation, so event processing can continue even
2934while waiting for disk I/O.
2935
2850=back 2936=back
2851 2937
2852 2938
2853=head1 FORK 2939=head1 FORK
2854 2940
2937L<AnyEvent::Impl::FLTK>. 3023L<AnyEvent::Impl::FLTK>.
2938 3024
2939Non-blocking handles, pipes, stream sockets, TCP clients and 3025Non-blocking handles, pipes, stream sockets, TCP clients and
2940servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 3026servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2941 3027
3028Asynchronous File I/O: L<AnyEvent::IO>.
3029
2942Asynchronous DNS: L<AnyEvent::DNS>. 3030Asynchronous DNS: L<AnyEvent::DNS>.
2943 3031
2944Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 3032Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
2945 3033
2946Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::IRC>, 3034Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::IRC>,
2948 3036
2949 3037
2950=head1 AUTHOR 3038=head1 AUTHOR
2951 3039
2952 Marc Lehmann <schmorp@schmorp.de> 3040 Marc Lehmann <schmorp@schmorp.de>
2953 http://home.schmorp.de/ 3041 http://anyevent.schmorp.de
2954 3042
2955=cut 3043=cut
2956 3044
29571 30451
2958 3046

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines