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.379 by root, Fri Aug 26 18:09:04 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.
1064
1065If you want to sprinkle loads of logging calls around your code, consider
1066creating a logger callback with the C<AnyEvent::Log::logger> function,
1067which can reduce typing, codesize and can reduce the logging overhead
1068enourmously.
1069
1050=back 1070=back
1051 1071
1052=head1 WHAT TO DO IN A MODULE 1072=head1 WHAT TO DO IN A MODULE
1053 1073
1054As a module author, you should C<use AnyEvent> and call AnyEvent methods 1074As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
1110 1130
1111 1131
1112=head1 OTHER MODULES 1132=head1 OTHER MODULES
1113 1133
1114The following is a non-exhaustive list of additional modules that use 1134The following is a non-exhaustive list of additional modules that use
1115AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1135AnyEvent as a client and can therefore be mixed easily with other
1116modules and other event loops in the same program. Some of the modules 1136AnyEvent modules and other event loops in the same program. Some of the
1117come as part of AnyEvent, the others are available via CPAN. 1137modules come as part of AnyEvent, the others are available via CPAN (see
1138L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1139a longer non-exhaustive list), and the list is heavily biased towards
1140modules of the AnyEvent author himself :)
1118 1141
1119=over 4 1142=over 4
1120 1143
1121=item L<AnyEvent::Util> 1144=item L<AnyEvent::Util>
1122 1145
… …
1142=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP> 1165=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1143 1166
1144Implement event-based interfaces to the protocols of the same name (for 1167Implement event-based interfaces to the protocols of the same name (for
1145the curious, IGS is the International Go Server and FCP is the Freenet 1168the curious, IGS is the International Go Server and FCP is the Freenet
1146Client Protocol). 1169Client 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 1170
1170=item L<AnyEvent::AIO> 1171=item L<AnyEvent::AIO>
1171 1172
1172Truly asynchronous (as opposed to non-blocking) I/O, should be in the 1173Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1173toolbox of every event programmer. AnyEvent::AIO transparently fuses 1174toolbox of every event programmer. AnyEvent::AIO transparently fuses
1174L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1175L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1175file I/O, and much more. 1176file I/O, and much more.
1176 1177
1178=item L<AnyEvent::Filesys::Notify>
1179
1180AnyEvent is good for non-blocking stuff, but it can't detect file or
1181path changes (e.g. "watch this directory for new files", "watch this
1182file for changes"). The L<AnyEvent::Filesys::Notify> module promises to
1183do just that in a portbale fashion, supporting inotify on GNU/Linux and
1184some weird, without doubt broken, stuff on OS X to monitor files. It can
1185fall back to blocking scans at regular intervals transparently on other
1186platforms, so it's about as portable as it gets.
1187
1188(I haven't used it myself, but I haven't heard anybody complaining about
1189it yet).
1190
1191=item L<AnyEvent::DBI>
1192
1193Executes L<DBI> requests asynchronously in a proxy process for you,
1194notifying you in an event-based way when the operation is finished.
1195
1177=item L<AnyEvent::HTTPD> 1196=item L<AnyEvent::HTTPD>
1178 1197
1179A simple embedded webserver. 1198A simple embedded webserver.
1180 1199
1181=item L<AnyEvent::FastPing> 1200=item L<AnyEvent::FastPing>
1182 1201
1183The fastest ping in the west. 1202The fastest ping in the west.
1184 1203
1185=item L<Coro> 1204=item L<Coro>
1186 1205
1187Has special support for AnyEvent via L<Coro::AnyEvent>. 1206Has special support for AnyEvent via L<Coro::AnyEvent>, which allows you
1207to simply invert the flow control - don't call us, we will call you:
1208
1209 async {
1210 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1211 print "5 seconds later!\n";
1212
1213 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1214 my $line = <STDIN>; # works for ttys
1215
1216 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1217 my ($body, $hdr) = Coro::rouse_wait;
1218 };
1188 1219
1189=back 1220=back
1190 1221
1191=cut 1222=cut
1192 1223
… …
1202 1233
1203BEGIN { AnyEvent::common_sense } 1234BEGIN { AnyEvent::common_sense }
1204 1235
1205use Carp (); 1236use Carp ();
1206 1237
1207our $VERSION = '5.34'; 1238our $VERSION = '6.02';
1208our $MODEL; 1239our $MODEL;
1209 1240
1210our @ISA; 1241our @ISA;
1211 1242
1212our @REGISTRY; 1243our @REGISTRY;
… …
1219 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1250 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1220 1251
1221 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1252 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1222 if ${^TAINT}; 1253 if ${^TAINT};
1223 1254
1255 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1256 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1257
1258 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1259 if ${^TAINT};
1260
1224 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1261 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1225
1226} 1262}
1227 1263
1228our $MAX_SIGNAL_LATENCY = 10; 1264our $MAX_SIGNAL_LATENCY = 10;
1229 1265
1230our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1266our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
… …
1266 push @POSTPONE, shift; 1302 push @POSTPONE, shift;
1267 1303
1268 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec); 1304 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1269 1305
1270 () 1306 ()
1307}
1308
1309sub log($$;@) {
1310 # only load the big bloated module when we actually are about to log something
1311 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!)
1312 require AnyEvent::Log;
1313 # AnyEvent::Log overwrites this function
1314 goto &log;
1315 }
1316
1317 0 # not logged
1318}
1319
1320if (length $ENV{PERL_ANYEVENT_LOG}) {
1321 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1271} 1322}
1272 1323
1273our @models = ( 1324our @models = (
1274 [EV:: => AnyEvent::Impl::EV:: , 1], 1325 [EV:: => AnyEvent::Impl::EV:: , 1],
1275 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1326 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
… …
1285 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1336 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1286 [Wx:: => AnyEvent::Impl::POE::], 1337 [Wx:: => AnyEvent::Impl::POE::],
1287 [Prima:: => AnyEvent::Impl::POE::], 1338 [Prima:: => AnyEvent::Impl::POE::],
1288 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1339 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1289 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1340 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1290 [FLTK:: => AnyEvent::Impl::FLTK2::], 1341 [FLTK:: => AnyEvent::Impl::FLTK::],
1291); 1342);
1343
1344our @isa_hook;
1345
1346sub _isa_set {
1347 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1348
1349 @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1350 for 1 .. $#pkg;
1351
1352 grep $_ && $_->[1], @isa_hook
1353 and AE::_reset ();
1354}
1355
1356# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1357sub _isa_hook($$;$) {
1358 my ($i, $pkg, $reset_ae) = @_;
1359
1360 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1361
1362 _isa_set;
1363}
1292 1364
1293# all autoloaded methods reserve the complete glob, not just the method slot. 1365# all autoloaded methods reserve the complete glob, not just the method slot.
1294# due to bugs in perls method cache implementation. 1366# due to bugs in perls method cache implementation.
1295our @methods = qw(io timer time now now_update signal child idle condvar); 1367our @methods = qw(io timer time now now_update signal child idle condvar);
1296 1368
1297sub detect() { 1369sub detect() {
1370 return $MODEL if $MODEL; # some programs keep references to detect
1371
1298 local $!; # for good measure 1372 local $!; # for good measure
1299 local $SIG{__DIE__}; # we use eval 1373 local $SIG{__DIE__}; # we use eval
1300 1374
1301 # free some memory 1375 # free some memory
1302 *detect = sub () { $MODEL }; 1376 *detect = sub () { $MODEL };
… …
1310 1384
1311 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1385 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1312 my $model = $1; 1386 my $model = $1;
1313 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1387 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1314 if (eval "require $model") { 1388 if (eval "require $model") {
1389 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1315 $MODEL = $model; 1390 $MODEL = $model;
1316 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1317 } else { 1391 } else {
1318 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1392 AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1319 } 1393 }
1320 } 1394 }
1321 1395
1322 # check for already loaded models 1396 # check for already loaded models
1323 unless ($MODEL) { 1397 unless ($MODEL) {
1324 for (@REGISTRY, @models) { 1398 for (@REGISTRY, @models) {
1325 my ($package, $model) = @$_; 1399 my ($package, $model) = @$_;
1326 if (${"$package\::VERSION"} > 0) { 1400 if (${"$package\::VERSION"} > 0) {
1327 if (eval "require $model") { 1401 if (eval "require $model") {
1402 AnyEvent::log 7 => "autodetected model '$model', using it.";
1328 $MODEL = $model; 1403 $MODEL = $model;
1329 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1330 last; 1404 last;
1331 } 1405 }
1332 } 1406 }
1333 } 1407 }
1334 1408
… …
1340 $autoload 1414 $autoload
1341 and eval "require $package" 1415 and eval "require $package"
1342 and ${"$package\::VERSION"} > 0 1416 and ${"$package\::VERSION"} > 0
1343 and eval "require $model" 1417 and eval "require $model"
1344 ) { 1418 ) {
1419 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1345 $MODEL = $model; 1420 $MODEL = $model;
1346 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1347 last; 1421 last;
1348 } 1422 }
1349 } 1423 }
1350 1424
1351 $MODEL 1425 $MODEL
1352 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?\n"; 1426 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1353 } 1427 }
1354 } 1428 }
1355 1429
1356 # free memory only needed for probing 1430 # free memory only needed for probing
1357 undef @models; 1431 undef @models;
1358 undef @REGISTRY; 1432 undef @REGISTRY;
1359 1433
1360 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1434 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1361 unshift @ISA, $MODEL;
1362 1435
1363 # now nuke some methods that are overridden by the backend. 1436 # now nuke some methods that are overridden by the backend.
1364 # SUPER usage is not allowed in these. 1437 # SUPER usage is not allowed in these.
1365 for (qw(time signal child idle)) { 1438 for (qw(time signal child idle)) {
1366 undef &{"AnyEvent::Base::$_"} 1439 undef &{"AnyEvent::Base::$_"}
1367 if defined &{"$MODEL\::$_"}; 1440 if defined &{"$MODEL\::$_"};
1368 } 1441 }
1369 1442
1443 _isa_set;
1444
1445 # we're officially open!
1446
1370 if ($ENV{PERL_ANYEVENT_STRICT}) { 1447 if ($ENV{PERL_ANYEVENT_STRICT}) {
1371 require AnyEvent::Strict; 1448 require AnyEvent::Strict;
1372 } 1449 }
1373 1450
1374 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1451 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1375 require AnyEvent::Debug; 1452 require AnyEvent::Debug;
1376 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1453 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1377 } 1454 }
1378 1455
1379 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1456 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1380 require AnyEvent::Socket; 1457 require AnyEvent::Socket;
1381 require AnyEvent::Debug; 1458 require AnyEvent::Debug;
1382 1459
1460 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1461 $shell =~ s/\$\$/$$/g;
1462
1383 my ($host, $service) = AnyEvent::Socket::parse_hostport ($ENV{PERL_ANYEVENT_DEBUG_SHELL}); 1463 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1384 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1464 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1385 } 1465 }
1466
1467 # now the anyevent environment is set up as the user told us to, so
1468 # call the actual user code - post detects
1386 1469
1387 (shift @post_detect)->() while @post_detect; 1470 (shift @post_detect)->() while @post_detect;
1388 undef @post_detect; 1471 undef @post_detect;
1389 1472
1390 *post_detect = sub(&) { 1473 *post_detect = sub(&) {
… …
1477 sub time() { 1560 sub time() {
1478 AnyEvent->time 1561 AnyEvent->time
1479 } 1562 }
1480 1563
1481 *postpone = \&AnyEvent::postpone; 1564 *postpone = \&AnyEvent::postpone;
1565 *log = \&AnyEvent::log;
1482 }; 1566 };
1483 die if $@; 1567 die if $@;
1484} 1568}
1485 1569
1486BEGIN { _reset } 1570BEGIN { _reset }
… …
1491 1575
1492sub time { 1576sub time {
1493 eval q{ # poor man's autoloading {} 1577 eval q{ # poor man's autoloading {}
1494 # probe for availability of Time::HiRes 1578 # probe for availability of Time::HiRes
1495 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1579 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1496 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1580 *time = sub { Time::HiRes::time () };
1497 *AE::time = \&Time::HiRes::time; 1581 *AE::time = \& Time::HiRes::time ;
1582 *now = \&time;
1583 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1498 # if (eval "use POSIX (); (POSIX::times())... 1584 # if (eval "use POSIX (); (POSIX::times())...
1499 } else { 1585 } else {
1586 *time = sub { CORE::time };
1587 *AE::time = sub (){ CORE::time };
1588 *now = \&time;
1500 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1589 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1501 *AE::time = sub (){ time }; # epic fail
1502 } 1590 }
1503
1504 *time = sub { AE::time }; # different prototypes
1505 }; 1591 };
1506 die if $@; 1592 die if $@;
1507 1593
1508 &time 1594 &time
1509} 1595}
1510 1596
1511*now = \&time; 1597*now = \&time;
1512
1513sub now_update { } 1598sub now_update { }
1514 1599
1515sub _poll { 1600sub _poll {
1516 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught"; 1601 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1517} 1602}
… …
1603 1688
1604sub signal { 1689sub signal {
1605 eval q{ # poor man's autoloading {} 1690 eval q{ # poor man's autoloading {}
1606 # probe for availability of Async::Interrupt 1691 # probe for availability of Async::Interrupt
1607 if (_have_async_interrupt) { 1692 if (_have_async_interrupt) {
1608 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1693 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1609 1694
1610 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1695 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1611 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1696 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1612 1697
1613 } else { 1698 } else {
1614 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1699 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1615 1700
1616 if (AnyEvent::WIN32) { 1701 if (AnyEvent::WIN32) {
1617 require AnyEvent::Util; 1702 require AnyEvent::Util;
1618 1703
1619 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1704 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1913$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 1998$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1914so on. 1999so on.
1915 2000
1916=head1 ENVIRONMENT VARIABLES 2001=head1 ENVIRONMENT VARIABLES
1917 2002
1918The following environment variables are used by this module or its 2003AnyEvent supports a number of environment variables that tune the
1919submodules. 2004runtime behaviour. They are usually evaluated when AnyEvent is
2005loaded, initialised, or a submodule that uses them is loaded. Many of
2006them also cause AnyEvent to load additional modules - for example,
2007C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2008loaded.
1920 2009
1921Note that AnyEvent will remove I<all> environment variables starting with 2010All the environment variables documented here start with
1922C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2011C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1923enabled. 2012namespace. Other modules are encouraged (but by no means required) to use
2013C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2014namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2015be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2016variables starting with C<AE_>, see below).
2017
2018All variables can also be set via the C<AE_> prefix, that is, instead
2019of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2020case there is a clash btween anyevent and another program that uses
2021C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2022variable to the empty string, as those variables take precedence.
2023
2024When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2025to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2026exists. If taint mode is on, then AnyEvent will remove I<all> environment
2027variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2028with C<undef> or the empty string, if the corresaponding C<AE_> variable
2029is set).
2030
2031The exact algorithm is currently:
2032
2033 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2034 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2035 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2036
2037This ensures that child processes will not see the C<AE_> variables.
2038
2039The following environment variables are currently known to AnyEvent:
1924 2040
1925=over 4 2041=over 4
1926 2042
1927=item C<PERL_ANYEVENT_VERBOSE> 2043=item C<PERL_ANYEVENT_VERBOSE>
1928 2044
1929By default, AnyEvent will be completely silent except in fatal 2045By default, AnyEvent will be completely silent except in fatal
1930conditions. You can set this environment variable to make AnyEvent more 2046conditions. You can set this environment variable to make AnyEvent more
1931talkative. 2047talkative. If 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
2049complex specifications.
1932 2050
1933When set to C<1> or higher, causes AnyEvent to warn about unexpected 2051When set to C<5> or higher (warn), causes AnyEvent to warn about unexpected
1934conditions, such as not being able to load the event model specified by 2052conditions, such as not being able to load the event model specified by
1935C<PERL_ANYEVENT_MODEL>. 2053C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
2054is the minimum recommended level.
1936 2055
1937When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2056When set to C<7> or higher (info), cause AnyEvent to report which event model it
1938model it chooses. 2057chooses.
1939 2058
1940When set to C<8> or higher, then AnyEvent will report extra information on 2059When 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. 2060which optional modules it loads and how it implements certain features.
2061
2062=item C<PERL_ANYEVENT_LOG>
2063
2064Accepts rather complex logging specifications. For example, you could log
2065all C<debug> messages of some module to stderr, warnings and above to
2066stderr, and errors and above to syslog, with:
2067
2068 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2069
2070For the rather extensive details, see L<AnyEvent::Log>.
2071
2072This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2073so will take effect even before AnyEvent has initialised itself.
2074
2075Note that specifying this environment variable causes the L<AnyEvent::Log>
2076module 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
2078is being logged.
1942 2079
1943=item C<PERL_ANYEVENT_STRICT> 2080=item C<PERL_ANYEVENT_STRICT>
1944 2081
1945AnyEvent does not do much argument checking by default, as thorough 2082AnyEvent does not do much argument checking by default, as thorough
1946argument checking is very costly. Setting this variable to a true value 2083argument checking is very costly. Setting this variable to a true value
… …
1955C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2092C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1956can be very useful, however. 2093can be very useful, however.
1957 2094
1958=item C<PERL_ANYEVENT_DEBUG_SHELL> 2095=item C<PERL_ANYEVENT_DEBUG_SHELL>
1959 2096
1960If this env variable is set, then its contents will be 2097If this env variable is set, then its contents will be interpreted by
1961interpreted by C<AnyEvent::Socket::parse_hostport> and an 2098C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
1962C<AnyEvent::Debug::shell> is bound on that port. The shell object is saved 2099C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
1963in C<$AnyEvent::Debug::SHELL>. 2100that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
2101
2102This happens when the first watcher is created.
1964 2103
1965For example, to bind a debug shell on a unix domain socket in 2104For example, to bind a debug shell on a unix domain socket in
1966F</tmp/debug.sock>, you could use this: 2105F<< /tmp/debug<pid>.sock >>, you could use this:
1967 2106
1968 PERL_ANYEVENT_DEBUG_SHELL=unix/:/tmp/debug.sock perlprog 2107 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2108
2109Note that creating sockets in F</tmp> is very unsafe on multiuser
2110systems.
1969 2111
1970=item C<PERL_ANYEVENT_DEBUG_WRAP> 2112=item C<PERL_ANYEVENT_DEBUG_WRAP>
1971 2113
1972Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for 2114Can 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. 2115debugging purposes. See C<AnyEvent::Debug::wrap> for details.
… …
2011but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2153but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2012- only support IPv4, never try to resolve or contact IPv6 2154- only support IPv4, never try to resolve or contact IPv6
2013addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2155addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2014IPv6, but prefer IPv6 over IPv4. 2156IPv6, but prefer IPv6 over IPv4.
2015 2157
2158=item C<PERL_ANYEVENT_HOSTS>
2159
2160This variable, if specified, overrides the F</etc/hosts> file used by
2161L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2162from that file instead.
2163
2016=item C<PERL_ANYEVENT_EDNS0> 2164=item C<PERL_ANYEVENT_EDNS0>
2017 2165
2018Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2166Used 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 2167DNS. This extension is generally useful to reduce DNS traffic, especially
2020some (broken) firewalls drop such DNS packets, which is why it is off by 2168when DNSSEC is involved, but some (broken) firewalls drop such DNS
2021default. 2169packets, which is why it is off by default.
2022 2170
2023Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2171Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2024EDNS0 in its DNS requests. 2172EDNS0 in its DNS requests.
2025 2173
2026=item C<PERL_ANYEVENT_MAX_FORKS> 2174=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2034resolver - this is the maximum number of parallel DNS requests that are 2182resolver - this is the maximum number of parallel DNS requests that are
2035sent to the DNS server. 2183sent to the DNS server.
2036 2184
2037=item C<PERL_ANYEVENT_RESOLV_CONF> 2185=item C<PERL_ANYEVENT_RESOLV_CONF>
2038 2186
2039The file to use instead of F</etc/resolv.conf> (or OS-specific 2187The 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 2188F</etc/resolv.conf> (or the OS-specific configuration) in the default
2041default config will be used. 2189resolver, or the empty string to select the default configuration.
2042 2190
2043=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2191=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2044 2192
2045When neither C<ca_file> nor C<ca_path> was specified during 2193When neither C<ca_file> nor C<ca_path> was specified during
2046L<AnyEvent::TLS> context creation, and either of these environment 2194L<AnyEvent::TLS> context creation, and either of these environment
2047variables exist, they will be used to specify CA certificate locations 2195variables are nonempty, they will be used to specify CA certificate
2048instead of a system-dependent default. 2196locations instead of a system-dependent default.
2049 2197
2050=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2198=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2051 2199
2052When these are set to C<1>, then the respective modules are not 2200When these are set to C<1>, then the respective modules are not
2053loaded. Mostly good for testing AnyEvent itself. 2201loaded. Mostly good for testing AnyEvent itself.
… …
2385(even when used without AnyEvent), but most event loops have acceptable 2533(even when used without AnyEvent), but most event loops have acceptable
2386performance with or without AnyEvent. 2534performance with or without AnyEvent.
2387 2535
2388=item * The overhead AnyEvent adds is usually much smaller than the overhead of 2536=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 2537the actual event loop, only with extremely fast event loops such as EV
2390adds AnyEvent significant overhead. 2538does AnyEvent add significant overhead.
2391 2539
2392=item * You should avoid POE like the plague if you want performance or 2540=item * You should avoid POE like the plague if you want performance or
2393reasonable memory usage. 2541reasonable memory usage.
2394 2542
2395=back 2543=back
… …
2770 2918
2771Tutorial/Introduction: L<AnyEvent::Intro>. 2919Tutorial/Introduction: L<AnyEvent::Intro>.
2772 2920
2773FAQ: L<AnyEvent::FAQ>. 2921FAQ: L<AnyEvent::FAQ>.
2774 2922
2775Utility functions: L<AnyEvent::Util>. 2923Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2924(simply logging).
2776 2925
2926Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2927L<AnyEvent::Debug> (interactive shell, watcher tracing).
2928
2777Event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>, L<Glib::EV>, 2929Supported 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>. 2930L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2931L<Qt>, L<POE>, L<FLTK>.
2779 2932
2780Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2933Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2781L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2934L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2782L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2935L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2783L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 2936L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
2937L<AnyEvent::Impl::FLTK>.
2784 2938
2785Non-blocking file handles, sockets, TCP clients and 2939Non-blocking handles, pipes, stream sockets, TCP clients and
2786servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2940servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2787 2941
2788Asynchronous DNS: L<AnyEvent::DNS>. 2942Asynchronous DNS: L<AnyEvent::DNS>.
2789 2943
2790Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 2944Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.

Diff Legend

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