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.358 by root, Sat Aug 13 02:35:32 2011 UTC vs.
Revision 1.386 by root, Mon Sep 26 11:32:19 2011 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - the DBI of event loop programming 3AnyEvent - the DBI of event loop programming
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt 5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt,
6and POE are various supported event loops/environments. 6FLTK and POE are various supported event loops/environments.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
… …
878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
879 AnyEvent::Impl::POE based on POE, very slow, some limitations. 879 AnyEvent::Impl::POE based on POE, very slow, some limitations.
880 AnyEvent::Impl::Irssi used when running within irssi. 880 AnyEvent::Impl::Irssi used when running within irssi.
881 AnyEvent::Impl::IOAsync based on IO::Async. 881 AnyEvent::Impl::IOAsync based on IO::Async.
882 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 882 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
883 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 883 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
884 884
885=item Backends with special needs. 885=item Backends with special needs.
886 886
887Qt requires the Qt::Application to be instantiated first, but will 887Qt requires the Qt::Application to be instantiated first, but will
888otherwise be picked up automatically. As long as the main program 888otherwise be picked up automatically. As long as the main program
… …
933 933
934Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 934Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
935if necessary. You should only call this function right before you would 935if necessary. You should only call this function right before you would
936have created an AnyEvent watcher anyway, that is, as late as possible at 936have created an AnyEvent watcher anyway, that is, as late as possible at
937runtime, and not e.g. during initialisation of your module. 937runtime, and not e.g. during initialisation of your module.
938
939The effect of calling this function is as if a watcher had been created
940(specifically, actions that happen "when the first watcher is created"
941happen when calling detetc as well).
938 942
939If you need to do some initialisation before AnyEvent watchers are 943If you need to do some initialisation before AnyEvent watchers are
940created, use C<post_detect>. 944created, use C<post_detect>.
941 945
942=item $guard = AnyEvent::post_detect { BLOCK } 946=item $guard = AnyEvent::post_detect { BLOCK }
… …
1045It should use C<postpone>: 1049It should use C<postpone>:
1046 1050
1047 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later 1051 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1048 if $some_error_condition; 1052 if $some_error_condition;
1049 1053
1054=item AnyEvent::log $level, $msg[, @args]
1055
1056Log the given C<$msg> at the given C<$level>.
1057
1058If 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
1060load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1061the L<AnyEvent::Log> documentation for details.
1062
1063If the test fails it will simply return. Right now this happens when a
1064numerical loglevel is used and it is larger than the level specified via
1065C<$ENV{PERL_ANYEVENT_VERBOSE}>.
1066
1067If you want to sprinkle loads of logging calls around your code, consider
1068creating a logger callback with the C<AnyEvent::Log::logger> function,
1069which can reduce typing, codesize and can reduce the logging overhead
1070enourmously.
1071
1050=back 1072=back
1051 1073
1052=head1 WHAT TO DO IN A MODULE 1074=head1 WHAT TO DO IN A MODULE
1053 1075
1054As a module author, you should C<use AnyEvent> and call AnyEvent methods 1076As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
1110 1132
1111 1133
1112=head1 OTHER MODULES 1134=head1 OTHER MODULES
1113 1135
1114The following is a non-exhaustive list of additional modules that use 1136The following is a non-exhaustive list of additional modules that use
1115AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1137AnyEvent as a client and can therefore be mixed easily with other
1116modules and other event loops in the same program. Some of the modules 1138AnyEvent modules and other event loops in the same program. Some of the
1117come as part of AnyEvent, the others are available via CPAN. 1139modules come as part of AnyEvent, the others are available via CPAN (see
1140L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1141a longer non-exhaustive list), and the list is heavily biased towards
1142modules of the AnyEvent author himself :)
1118 1143
1119=over 4 1144=over 4
1120 1145
1121=item L<AnyEvent::Util> 1146=item L<AnyEvent::Util>
1122 1147
… …
1142=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP> 1167=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1143 1168
1144Implement event-based interfaces to the protocols of the same name (for 1169Implement event-based interfaces to the protocols of the same name (for
1145the curious, IGS is the International Go Server and FCP is the Freenet 1170the curious, IGS is the International Go Server and FCP is the Freenet
1146Client Protocol). 1171Client Protocol).
1147
1148=item L<AnyEvent::Handle::UDP>
1149
1150Here be danger!
1151
1152As Pauli would put it, "Not only is it not right, it's not even wrong!" -
1153there are so many things wrong with AnyEvent::Handle::UDP, most notably
1154its use of a stream-based API with a protocol that isn't streamable, that
1155the only way to improve it is to delete it.
1156
1157It features data corruption (but typically only under load) and general
1158confusion. On top, the author is not only clueless about UDP but also
1159fact-resistant - some gems of his understanding: "connect doesn't work
1160with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
1161packets", "I don't need to implement proper error checking as UDP doesn't
1162support error checking" and so on - he doesn't even understand what's
1163wrong with his module when it is explained to him.
1164
1165=item L<AnyEvent::DBI>
1166
1167Executes L<DBI> requests asynchronously in a proxy process for you,
1168notifying you in an event-based way when the operation is finished.
1169 1172
1170=item L<AnyEvent::AIO> 1173=item L<AnyEvent::AIO>
1171 1174
1172Truly asynchronous (as opposed to non-blocking) I/O, should be in the 1175Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1173toolbox of every event programmer. AnyEvent::AIO transparently fuses 1176toolbox of every event programmer. AnyEvent::AIO transparently fuses
1174L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1177L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1175file I/O, and much more. 1178file I/O, and much more.
1176 1179
1180=item L<AnyEvent::Filesys::Notify>
1181
1182AnyEvent is good for non-blocking stuff, but it can't detect file or
1183path changes (e.g. "watch this directory for new files", "watch this
1184file for changes"). The L<AnyEvent::Filesys::Notify> module promises to
1185do just that in a portbale fashion, supporting inotify on GNU/Linux and
1186some weird, without doubt broken, stuff on OS X to monitor files. It can
1187fall back to blocking scans at regular intervals transparently on other
1188platforms, so it's about as portable as it gets.
1189
1190(I haven't used it myself, but I haven't heard anybody complaining about
1191it yet).
1192
1193=item L<AnyEvent::DBI>
1194
1195Executes L<DBI> requests asynchronously in a proxy process for you,
1196notifying you in an event-based way when the operation is finished.
1197
1177=item L<AnyEvent::HTTPD> 1198=item L<AnyEvent::HTTPD>
1178 1199
1179A simple embedded webserver. 1200A simple embedded webserver.
1180 1201
1181=item L<AnyEvent::FastPing> 1202=item L<AnyEvent::FastPing>
1182 1203
1183The fastest ping in the west. 1204The fastest ping in the west.
1184 1205
1185=item L<Coro> 1206=item L<Coro>
1186 1207
1187Has special support for AnyEvent via L<Coro::AnyEvent>. 1208Has special support for AnyEvent via L<Coro::AnyEvent>, which allows you
1209to simply invert the flow control - don't call us, we will call you:
1210
1211 async {
1212 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1213 print "5 seconds later!\n";
1214
1215 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1216 my $line = <STDIN>; # works for ttys
1217
1218 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1219 my ($body, $hdr) = Coro::rouse_wait;
1220 };
1188 1221
1189=back 1222=back
1190 1223
1191=cut 1224=cut
1192 1225
… …
1202 1235
1203BEGIN { AnyEvent::common_sense } 1236BEGIN { AnyEvent::common_sense }
1204 1237
1205use Carp (); 1238use Carp ();
1206 1239
1207our $VERSION = '5.34'; 1240our $VERSION = '6.02';
1208our $MODEL; 1241our $MODEL;
1209
1210our @ISA; 1242our @ISA;
1211
1212our @REGISTRY; 1243our @REGISTRY;
1213
1214our $VERBOSE; 1244our $VERBOSE;
1245our $MAX_SIGNAL_LATENCY = 10;
1246our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1215 1247
1216BEGIN { 1248BEGIN {
1217 require "AnyEvent/constants.pl"; 1249 require "AnyEvent/constants.pl";
1218 1250
1219 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1251 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1220 1252
1221 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1253 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1222 if ${^TAINT}; 1254 if ${^TAINT};
1223 1255
1224 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1256 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1257 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1225 1258
1226} 1259 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1260 if ${^TAINT};
1227 1261
1228our $MAX_SIGNAL_LATENCY = 10; 1262 # $ENV{PERL_ANYEVENT_xxx} now valid
1229 1263
1230our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1264 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1231 1265
1232{
1233 my $idx; 1266 my $idx;
1234 $PROTOCOL{$_} = ++$idx 1267 $PROTOCOL{$_} = ++$idx
1235 for reverse split /\s*,\s*/, 1268 for reverse split /\s*,\s*/,
1236 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1269 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1237} 1270}
… …
1268 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec); 1301 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1269 1302
1270 () 1303 ()
1271} 1304}
1272 1305
1306sub log($$;@) {
1307 # only load the big bloated module when we actually are about to log something
1308 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1309 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1310 # AnyEvent::Log overwrites this function
1311 goto &log;
1312 }
1313
1314 0 # not logged
1315}
1316
1317sub logger($;$) {
1318 package AnyEvent::Log;
1319
1320 my ($level, $renabled) = @_;
1321
1322 $$renabled = $level <= $VERBOSE;
1323
1324 my $pkg = (caller)[0];
1325
1326 my $logger = [$pkg, $level, $renabled];
1327
1328 our %LOGGER;
1329 $LOGGER{$logger+0} = $logger;
1330
1331 require AnyEvent::Util;
1332 my $guard = AnyEvent::Util::guard (sub {
1333 # "clean up"
1334 delete $LOGGER{$logger+0};
1335 });
1336
1337 sub {
1338 return 0 unless $$renabled;
1339
1340 $guard if 0; # keep guard alive, but don't cause runtime overhead
1341 require AnyEvent::Log unless $AnyEvent::Log::VERSION;
1342 package AnyEvent::Log;
1343 _log ($logger->[0], $level, @_) # logger->[0] has been converted at load time
1344 }
1345}
1346
1347if (length $ENV{PERL_ANYEVENT_LOG}) {
1348 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1349}
1350
1273our @models = ( 1351our @models = (
1274 [EV:: => AnyEvent::Impl::EV:: , 1], 1352 [EV:: => AnyEvent::Impl::EV::],
1275 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1353 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1276 # everything below here will not (normally) be autoprobed 1354 # everything below here will not (normally) be autoprobed
1277 # as the pure perl backend should work everywhere 1355 # as the pure perl backend should work everywhere
1278 # and is usually faster 1356 # and is usually faster
1357 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package, so msut be near the top
1279 [Event:: => AnyEvent::Impl::Event::, 1], 1358 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1280 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1359 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1360 # everything below here should not be autoloaded
1281 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1361 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1282 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1283 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1362 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1284 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1363 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1285 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1364 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1286 [Wx:: => AnyEvent::Impl::POE::], 1365 [Wx:: => AnyEvent::Impl::POE::],
1287 [Prima:: => AnyEvent::Impl::POE::], 1366 [Prima:: => AnyEvent::Impl::POE::],
1288 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1367 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1289 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1368 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1290 [FLTK:: => AnyEvent::Impl::FLTK2::], 1369 [FLTK:: => AnyEvent::Impl::FLTK::],
1291); 1370);
1371
1372our @isa_hook;
1373
1374sub _isa_set {
1375 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1376
1377 @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1378 for 1 .. $#pkg;
1379
1380 grep $_ && $_->[1], @isa_hook
1381 and AE::_reset ();
1382}
1383
1384# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1385sub _isa_hook($$;$) {
1386 my ($i, $pkg, $reset_ae) = @_;
1387
1388 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1389
1390 _isa_set;
1391}
1292 1392
1293# all autoloaded methods reserve the complete glob, not just the method slot. 1393# all autoloaded methods reserve the complete glob, not just the method slot.
1294# due to bugs in perls method cache implementation. 1394# due to bugs in perls method cache implementation.
1295our @methods = qw(io timer time now now_update signal child idle condvar); 1395our @methods = qw(io timer time now now_update signal child idle condvar);
1296 1396
1297sub detect() { 1397sub detect() {
1398 return $MODEL if $MODEL; # some programs keep references to detect
1399
1400 # IO::Async::Loop::AnyEvent is extremely evil, refuse to work with it
1401 # the author knows about the problems and what it does to AnyEvent as a whole
1402 # (and the ability of others to use AnyEvent), but simply wants to abuse AnyEvent
1403 # anyway.
1404 AnyEvent::log fatal => "AnyEvent: IO::Async::Loop::AnyEvent detected - this module is broken by design,\n"
1405 . "abuses internals and breaks AnyEvent, will not continue."
1406 if exists $INC{"IO/Async/Loop/AnyEvent.pm"};
1407
1298 local $!; # for good measure 1408 local $!; # for good measure
1299 local $SIG{__DIE__}; # we use eval 1409 local $SIG{__DIE__}; # we use eval
1300 1410
1301 # free some memory 1411 # free some memory
1302 *detect = sub () { $MODEL }; 1412 *detect = sub () { $MODEL };
… …
1310 1420
1311 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1421 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1312 my $model = $1; 1422 my $model = $1;
1313 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1423 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1314 if (eval "require $model") { 1424 if (eval "require $model") {
1425 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1315 $MODEL = $model; 1426 $MODEL = $model;
1316 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1317 } else { 1427 } else {
1318 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1428 AnyEvent::log 4 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1319 } 1429 }
1320 } 1430 }
1321 1431
1322 # check for already loaded models 1432 # check for already loaded models
1323 unless ($MODEL) { 1433 unless ($MODEL) {
1324 for (@REGISTRY, @models) { 1434 for (@REGISTRY, @models) {
1325 my ($package, $model) = @$_; 1435 my ($package, $model) = @$_;
1326 if (${"$package\::VERSION"} > 0) { 1436 if (${"$package\::VERSION"} > 0) {
1327 if (eval "require $model") { 1437 if (eval "require $model") {
1438 AnyEvent::log 7 => "autodetected model '$model', using it.";
1328 $MODEL = $model; 1439 $MODEL = $model;
1329 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1330 last; 1440 last;
1331 } 1441 }
1332 } 1442 }
1333 } 1443 }
1334 1444
1335 unless ($MODEL) { 1445 unless ($MODEL) {
1336 # try to autoload a model 1446 # try to autoload a model
1337 for (@REGISTRY, @models) { 1447 for (@REGISTRY, @models) {
1338 my ($package, $model, $autoload) = @$_; 1448 my ($package, $model) = @$_;
1339 if ( 1449 if (
1340 $autoload
1341 and eval "require $package" 1450 eval "require $package"
1342 and ${"$package\::VERSION"} > 0 1451 and ${"$package\::VERSION"} > 0
1343 and eval "require $model" 1452 and eval "require $model"
1344 ) { 1453 ) {
1454 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1345 $MODEL = $model; 1455 $MODEL = $model;
1346 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1347 last; 1456 last;
1348 } 1457 }
1349 } 1458 }
1350 1459
1351 $MODEL 1460 $MODEL
1352 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?\n"; 1461 or AnyEvent::log fatal => "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1353 } 1462 }
1354 } 1463 }
1355 1464
1356 # free memory only needed for probing 1465 # free memory only needed for probing
1357 undef @models; 1466 undef @models;
1358 undef @REGISTRY; 1467 undef @REGISTRY;
1359 1468
1360 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1469 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1361 unshift @ISA, $MODEL;
1362 1470
1363 # now nuke some methods that are overridden by the backend. 1471 # now nuke some methods that are overridden by the backend.
1364 # SUPER usage is not allowed in these. 1472 # SUPER usage is not allowed in these.
1365 for (qw(time signal child idle)) { 1473 for (qw(time signal child idle)) {
1366 undef &{"AnyEvent::Base::$_"} 1474 undef &{"AnyEvent::Base::$_"}
1367 if defined &{"$MODEL\::$_"}; 1475 if defined &{"$MODEL\::$_"};
1368 } 1476 }
1369 1477
1478 _isa_set;
1479
1480 # we're officially open!
1481
1370 if ($ENV{PERL_ANYEVENT_STRICT}) { 1482 if ($ENV{PERL_ANYEVENT_STRICT}) {
1371 require AnyEvent::Strict; 1483 require AnyEvent::Strict;
1372 } 1484 }
1373 1485
1374 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1486 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1375 require AnyEvent::Debug; 1487 require AnyEvent::Debug;
1376 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1488 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1377 } 1489 }
1378 1490
1379 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1491 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1380 require AnyEvent::Socket; 1492 require AnyEvent::Socket;
1381 require AnyEvent::Debug; 1493 require AnyEvent::Debug;
1382 1494
1495 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1496 $shell =~ s/\$\$/$$/g;
1497
1383 my ($host, $service) = AnyEvent::Socket::parse_hostport ($ENV{PERL_ANYEVENT_DEBUG_SHELL}); 1498 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1384 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1499 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1385 } 1500 }
1501
1502 # now the anyevent environment is set up as the user told us to, so
1503 # call the actual user code - post detects
1386 1504
1387 (shift @post_detect)->() while @post_detect; 1505 (shift @post_detect)->() while @post_detect;
1388 undef @post_detect; 1506 undef @post_detect;
1389 1507
1390 *post_detect = sub(&) { 1508 *post_detect = sub(&) {
… …
1477 sub time() { 1595 sub time() {
1478 AnyEvent->time 1596 AnyEvent->time
1479 } 1597 }
1480 1598
1481 *postpone = \&AnyEvent::postpone; 1599 *postpone = \&AnyEvent::postpone;
1600 *log = \&AnyEvent::log;
1482 }; 1601 };
1483 die if $@; 1602 die if $@;
1484} 1603}
1485 1604
1486BEGIN { _reset } 1605BEGIN { _reset }
… …
1491 1610
1492sub time { 1611sub time {
1493 eval q{ # poor man's autoloading {} 1612 eval q{ # poor man's autoloading {}
1494 # probe for availability of Time::HiRes 1613 # probe for availability of Time::HiRes
1495 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1614 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1496 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1615 *time = sub { Time::HiRes::time () };
1497 *AE::time = \&Time::HiRes::time; 1616 *AE::time = \& Time::HiRes::time ;
1617 *now = \&time;
1618 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1498 # if (eval "use POSIX (); (POSIX::times())... 1619 # if (eval "use POSIX (); (POSIX::times())...
1499 } else { 1620 } else {
1621 *time = sub { CORE::time };
1622 *AE::time = sub (){ CORE::time };
1623 *now = \&time;
1500 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1624 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1501 *AE::time = sub (){ time }; # epic fail
1502 } 1625 }
1503
1504 *time = sub { AE::time }; # different prototypes
1505 }; 1626 };
1506 die if $@; 1627 die if $@;
1507 1628
1508 &time 1629 &time
1509} 1630}
1510 1631
1511*now = \&time; 1632*now = \&time;
1512
1513sub now_update { } 1633sub now_update { }
1514 1634
1515sub _poll { 1635sub _poll {
1516 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught"; 1636 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1517} 1637}
… …
1603 1723
1604sub signal { 1724sub signal {
1605 eval q{ # poor man's autoloading {} 1725 eval q{ # poor man's autoloading {}
1606 # probe for availability of Async::Interrupt 1726 # probe for availability of Async::Interrupt
1607 if (_have_async_interrupt) { 1727 if (_have_async_interrupt) {
1608 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1728 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1609 1729
1610 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1730 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1611 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1731 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1612 1732
1613 } else { 1733 } else {
1614 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1734 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1615 1735
1616 if (AnyEvent::WIN32) { 1736 if (AnyEvent::WIN32) {
1617 require AnyEvent::Util; 1737 require AnyEvent::Util;
1618 1738
1619 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1739 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1913$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2033$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1914so on. 2034so on.
1915 2035
1916=head1 ENVIRONMENT VARIABLES 2036=head1 ENVIRONMENT VARIABLES
1917 2037
1918The following environment variables are used by this module or its 2038AnyEvent supports a number of environment variables that tune the
1919submodules. 2039runtime behaviour. They are usually evaluated when AnyEvent is
2040loaded, initialised, or a submodule that uses them is loaded. Many of
2041them also cause AnyEvent to load additional modules - for example,
2042C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2043loaded.
1920 2044
1921Note that AnyEvent will remove I<all> environment variables starting with 2045All the environment variables documented here start with
1922C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2046C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1923enabled. 2047namespace. Other modules are encouraged (but by no means required) to use
2048C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2049namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2050be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2051variables starting with C<AE_>, see below).
2052
2053All variables can also be set via the C<AE_> prefix, that is, instead
2054of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2055case there is a clash btween anyevent and another program that uses
2056C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2057variable to the empty string, as those variables take precedence.
2058
2059When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2060to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2061exists. If taint mode is on, then AnyEvent will remove I<all> environment
2062variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2063with C<undef> or the empty string, if the corresaponding C<AE_> variable
2064is set).
2065
2066The exact algorithm is currently:
2067
2068 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2069 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2070 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2071
2072This ensures that child processes will not see the C<AE_> variables.
2073
2074The following environment variables are currently known to AnyEvent:
1924 2075
1925=over 4 2076=over 4
1926 2077
1927=item C<PERL_ANYEVENT_VERBOSE> 2078=item C<PERL_ANYEVENT_VERBOSE>
1928 2079
1929By default, AnyEvent will be completely silent except in fatal 2080By default, AnyEvent will only log messages with loglevel C<3>
1930conditions. You can set this environment variable to make AnyEvent more 2081(C<critical>) or higher (see L<AnyEvent::Log>). You can set this
2082environment variable to a numerical loglevel to make AnyEvent more (or
1931talkative. 2083less) talkative.
1932 2084
2085If you want to do more than just set the global logging level
2086you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2087complex specifications.
2088
2089When set to C<0> (C<off>), then no messages whatsoever will be logged with
2090the default logging settings.
2091
1933When set to C<1> or higher, causes AnyEvent to warn about unexpected 2092When set to C<5> or higher (C<warn>), causes AnyEvent to warn about
1934conditions, such as not being able to load the event model specified by 2093unexpected conditions, such as not being able to load the event model
1935C<PERL_ANYEVENT_MODEL>. 2094specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2095exception - this is the minimum recommended level.
1936 2096
1937When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2097When set to C<7> or higher (info), cause AnyEvent to report which event model it
1938model it chooses. 2098chooses.
1939 2099
1940When set to C<8> or higher, then AnyEvent will report extra information on 2100When set to C<8> or higher (debug), then AnyEvent will report extra information on
1941which optional modules it loads and how it implements certain features. 2101which optional modules it loads and how it implements certain features.
2102
2103=item C<PERL_ANYEVENT_LOG>
2104
2105Accepts rather complex logging specifications. For example, you could log
2106all C<debug> messages of some module to stderr, warnings and above to
2107stderr, and errors and above to syslog, with:
2108
2109 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2110
2111For the rather extensive details, see L<AnyEvent::Log>.
2112
2113This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2114so will take effect even before AnyEvent has initialised itself.
2115
2116Note that specifying this environment variable causes the L<AnyEvent::Log>
2117module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2118using the latter saves a few hundred kB of memory until the first message
2119is being logged.
1942 2120
1943=item C<PERL_ANYEVENT_STRICT> 2121=item C<PERL_ANYEVENT_STRICT>
1944 2122
1945AnyEvent does not do much argument checking by default, as thorough 2123AnyEvent does not do much argument checking by default, as thorough
1946argument checking is very costly. Setting this variable to a true value 2124argument checking is very costly. Setting this variable to a true value
… …
1955C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2133C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1956can be very useful, however. 2134can be very useful, however.
1957 2135
1958=item C<PERL_ANYEVENT_DEBUG_SHELL> 2136=item C<PERL_ANYEVENT_DEBUG_SHELL>
1959 2137
1960If this env variable is set, then its contents will be 2138If this env variable is nonempty, then its contents will be interpreted by
1961interpreted by C<AnyEvent::Socket::parse_hostport> and an 2139C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
1962C<AnyEvent::Debug::shell> is bound on that port. The shell object is saved 2140replacing every occurance of C<$$> by the process pid). The shell object
1963in C<$AnyEvent::Debug::SHELL>. 2141is saved in C<$AnyEvent::Debug::SHELL>.
2142
2143This happens when the first watcher is created.
1964 2144
1965For example, to bind a debug shell on a unix domain socket in 2145For example, to bind a debug shell on a unix domain socket in
1966F</tmp/debug.sock>, you could use this: 2146F<< /tmp/debug<pid>.sock >>, you could use this:
1967 2147
1968 PERL_ANYEVENT_DEBUG_SHELL=unix/:/tmp/debug.sock perlprog 2148 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2149 # connect with e.g.: socat readline /tmp/debug123.sock
2150
2151Or to bind to tcp port 4545 on localhost:
2152
2153 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
2154 # connect with e.g.: telnet localhost 4545
2155
2156Note that creating sockets in F</tmp> or on localhost is very unsafe on
2157multiuser systems.
1969 2158
1970=item C<PERL_ANYEVENT_DEBUG_WRAP> 2159=item C<PERL_ANYEVENT_DEBUG_WRAP>
1971 2160
1972Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for 2161Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
1973debugging purposes. See C<AnyEvent::Debug::wrap> for details. 2162debugging purposes. See C<AnyEvent::Debug::wrap> for details.
… …
2011but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2200but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2012- only support IPv4, never try to resolve or contact IPv6 2201- only support IPv4, never try to resolve or contact IPv6
2013addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2202addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2014IPv6, but prefer IPv6 over IPv4. 2203IPv6, but prefer IPv6 over IPv4.
2015 2204
2205=item C<PERL_ANYEVENT_HOSTS>
2206
2207This variable, if specified, overrides the F</etc/hosts> file used by
2208L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2209from that file instead.
2210
2016=item C<PERL_ANYEVENT_EDNS0> 2211=item C<PERL_ANYEVENT_EDNS0>
2017 2212
2018Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2213Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
2019for DNS. This extension is generally useful to reduce DNS traffic, but 2214DNS. This extension is generally useful to reduce DNS traffic, especially
2020some (broken) firewalls drop such DNS packets, which is why it is off by 2215when DNSSEC is involved, but some (broken) firewalls drop such DNS
2021default. 2216packets, which is why it is off by default.
2022 2217
2023Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2218Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2024EDNS0 in its DNS requests. 2219EDNS0 in its DNS requests.
2025 2220
2026=item C<PERL_ANYEVENT_MAX_FORKS> 2221=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2034resolver - this is the maximum number of parallel DNS requests that are 2229resolver - this is the maximum number of parallel DNS requests that are
2035sent to the DNS server. 2230sent to the DNS server.
2036 2231
2037=item C<PERL_ANYEVENT_RESOLV_CONF> 2232=item C<PERL_ANYEVENT_RESOLV_CONF>
2038 2233
2039The file to use instead of F</etc/resolv.conf> (or OS-specific 2234The absolute path to a F<resolv.conf>-style file to use instead of
2040configuration) in the default resolver. When set to the empty string, no 2235F</etc/resolv.conf> (or the OS-specific configuration) in the default
2041default config will be used. 2236resolver, or the empty string to select the default configuration.
2042 2237
2043=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2238=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2044 2239
2045When neither C<ca_file> nor C<ca_path> was specified during 2240When neither C<ca_file> nor C<ca_path> was specified during
2046L<AnyEvent::TLS> context creation, and either of these environment 2241L<AnyEvent::TLS> context creation, and either of these environment
2047variables exist, they will be used to specify CA certificate locations 2242variables are nonempty, they will be used to specify CA certificate
2048instead of a system-dependent default. 2243locations instead of a system-dependent default.
2049 2244
2050=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2245=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2051 2246
2052When these are set to C<1>, then the respective modules are not 2247When these are set to C<1>, then the respective modules are not
2053loaded. Mostly good for testing AnyEvent itself. 2248loaded. Mostly good for testing AnyEvent itself.
… …
2385(even when used without AnyEvent), but most event loops have acceptable 2580(even when used without AnyEvent), but most event loops have acceptable
2386performance with or without AnyEvent. 2581performance with or without AnyEvent.
2387 2582
2388=item * The overhead AnyEvent adds is usually much smaller than the overhead of 2583=item * The overhead AnyEvent adds is usually much smaller than the overhead of
2389the actual event loop, only with extremely fast event loops such as EV 2584the actual event loop, only with extremely fast event loops such as EV
2390adds AnyEvent significant overhead. 2585does AnyEvent add significant overhead.
2391 2586
2392=item * You should avoid POE like the plague if you want performance or 2587=item * You should avoid POE like the plague if you want performance or
2393reasonable memory usage. 2588reasonable memory usage.
2394 2589
2395=back 2590=back
… …
2770 2965
2771Tutorial/Introduction: L<AnyEvent::Intro>. 2966Tutorial/Introduction: L<AnyEvent::Intro>.
2772 2967
2773FAQ: L<AnyEvent::FAQ>. 2968FAQ: L<AnyEvent::FAQ>.
2774 2969
2775Utility functions: L<AnyEvent::Util>. 2970Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2971(simply logging).
2776 2972
2973Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2974L<AnyEvent::Debug> (interactive shell, watcher tracing).
2975
2777Event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>, L<Glib::EV>, 2976Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2778L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2977L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2978L<Qt>, L<POE>, L<FLTK>.
2779 2979
2780Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2980Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2781L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2981L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2782L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2982L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2783L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 2983L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
2984L<AnyEvent::Impl::FLTK>.
2784 2985
2785Non-blocking file handles, sockets, TCP clients and 2986Non-blocking handles, pipes, stream sockets, TCP clients and
2786servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2987servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2787 2988
2788Asynchronous DNS: L<AnyEvent::DNS>. 2989Asynchronous DNS: L<AnyEvent::DNS>.
2789 2990
2790Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 2991Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.

Diff Legend

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