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.354 by root, Thu Aug 11 21:26:39 2011 UTC vs.
Revision 1.381 by root, Thu Sep 1 22:09:25 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::FLTK based on FLTK. 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 1242
1210our $AUTOLOAD;
1211our @ISA; 1243our @ISA;
1212 1244
1213our @REGISTRY; 1245our @REGISTRY;
1214 1246
1215our $VERBOSE; 1247our $VERBOSE;
1220 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1252 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1221 1253
1222 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1254 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1223 if ${^TAINT}; 1255 if ${^TAINT};
1224 1256
1225 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1257 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1258 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1226 1259
1260 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1261 if ${^TAINT};
1262
1263 # $ENV{PERL_ANYEVENT_xxx} now valid
1264
1265 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 3;
1227} 1266}
1228 1267
1229our $MAX_SIGNAL_LATENCY = 10; 1268our $MAX_SIGNAL_LATENCY = 10;
1230 1269
1231our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1270our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1235 $PROTOCOL{$_} = ++$idx 1274 $PROTOCOL{$_} = ++$idx
1236 for reverse split /\s*,\s*/, 1275 for reverse split /\s*,\s*/,
1237 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1276 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1238} 1277}
1239 1278
1279our @post_detect;
1280
1281sub post_detect(&) {
1282 my ($cb) = @_;
1283
1284 push @post_detect, $cb;
1285
1286 defined wantarray
1287 ? bless \$cb, "AnyEvent::Util::postdetect"
1288 : ()
1289}
1290
1291sub AnyEvent::Util::postdetect::DESTROY {
1292 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1293}
1294
1295our $POSTPONE_W;
1296our @POSTPONE;
1297
1298sub _postpone_exec {
1299 undef $POSTPONE_W;
1300
1301 &{ shift @POSTPONE }
1302 while @POSTPONE;
1303}
1304
1305sub postpone(&) {
1306 push @POSTPONE, shift;
1307
1308 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1309
1310 ()
1311}
1312
1313sub log($$;@) {
1314 # only load the big bloated module when we actually are about to log something
1315 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!)
1316 require AnyEvent::Log;
1317 # AnyEvent::Log overwrites this function
1318 goto &log;
1319 }
1320
1321 0 # not logged
1322}
1323
1324if (length $ENV{PERL_ANYEVENT_LOG}) {
1325 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1326}
1327
1240my @models = ( 1328our @models = (
1241 [EV:: => AnyEvent::Impl::EV:: , 1], 1329 [EV:: => AnyEvent::Impl::EV:: , 1],
1242 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1330 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
1243 # everything below here will not (normally) be autoprobed 1331 # everything below here will not (normally) be autoprobed
1244 # as the pure perl backend should work everywhere 1332 # as the pure perl backend should work everywhere
1245 # and is usually faster 1333 # and is usually faster
1250 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1338 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1251 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1339 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1252 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1340 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1253 [Wx:: => AnyEvent::Impl::POE::], 1341 [Wx:: => AnyEvent::Impl::POE::],
1254 [Prima:: => AnyEvent::Impl::POE::], 1342 [Prima:: => AnyEvent::Impl::POE::],
1255 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], 1343 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1256 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1344 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1257 [FLTK:: => AnyEvent::Impl::FLTK::], 1345 [FLTK:: => AnyEvent::Impl::FLTK::],
1258); 1346);
1259 1347
1260our %method = map +($_ => 1), 1348our @isa_hook;
1349
1350sub _isa_set {
1351 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1352
1353 @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1354 for 1 .. $#pkg;
1355
1356 grep $_ && $_->[1], @isa_hook
1357 and AE::_reset ();
1358}
1359
1360# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1361sub _isa_hook($$;$) {
1362 my ($i, $pkg, $reset_ae) = @_;
1363
1364 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1365
1366 _isa_set;
1367}
1368
1369# all autoloaded methods reserve the complete glob, not just the method slot.
1370# due to bugs in perls method cache implementation.
1261 qw(io timer time now now_update signal child idle condvar DESTROY); 1371our @methods = qw(io timer time now now_update signal child idle condvar);
1262
1263our @post_detect;
1264
1265sub post_detect(&) {
1266 my ($cb) = @_;
1267
1268 push @post_detect, $cb;
1269
1270 defined wantarray
1271 ? bless \$cb, "AnyEvent::Util::postdetect"
1272 : ()
1273}
1274
1275sub AnyEvent::Util::postdetect::DESTROY {
1276 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1277}
1278 1372
1279sub detect() { 1373sub detect() {
1374 return $MODEL if $MODEL; # some programs keep references to detect
1375
1376 local $!; # for good measure
1377 local $SIG{__DIE__}; # we use eval
1378
1280 # free some memory 1379 # free some memory
1281 *detect = sub () { $MODEL }; 1380 *detect = sub () { $MODEL };
1381 # undef &func doesn't correctly update the method cache. grmbl.
1382 # so we delete the whole glob. grmbl.
1383 # otoh, perl doesn't let me undef an active usb, but it lets me free
1384 # a glob with an active sub. hrm. i hope it works, but perl is
1385 # usually buggy in this department. sigh.
1386 delete @{"AnyEvent::"}{@methods};
1387 undef @methods;
1282 1388
1283 local $!; # for good measure
1284 local $SIG{__DIE__};
1285
1286 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1389 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1287 my $model = "AnyEvent::Impl::$1"; 1390 my $model = $1;
1391 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1288 if (eval "require $model") { 1392 if (eval "require $model") {
1393 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1289 $MODEL = $model; 1394 $MODEL = $model;
1290 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1291 } else { 1395 } else {
1292 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1396 AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1293 } 1397 }
1294 } 1398 }
1295 1399
1296 # check for already loaded models 1400 # check for already loaded models
1297 unless ($MODEL) { 1401 unless ($MODEL) {
1298 for (@REGISTRY, @models) { 1402 for (@REGISTRY, @models) {
1299 my ($package, $model) = @$_; 1403 my ($package, $model) = @$_;
1300 if (${"$package\::VERSION"} > 0) { 1404 if (${"$package\::VERSION"} > 0) {
1301 if (eval "require $model") { 1405 if (eval "require $model") {
1406 AnyEvent::log 7 => "autodetected model '$model', using it.";
1302 $MODEL = $model; 1407 $MODEL = $model;
1303 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1304 last; 1408 last;
1305 } 1409 }
1306 } 1410 }
1307 } 1411 }
1308 1412
1314 $autoload 1418 $autoload
1315 and eval "require $package" 1419 and eval "require $package"
1316 and ${"$package\::VERSION"} > 0 1420 and ${"$package\::VERSION"} > 0
1317 and eval "require $model" 1421 and eval "require $model"
1318 ) { 1422 ) {
1423 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1319 $MODEL = $model; 1424 $MODEL = $model;
1320 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1321 last; 1425 last;
1322 } 1426 }
1323 } 1427 }
1324 1428
1325 $MODEL 1429 $MODEL
1326 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?\n"; 1430 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1327 } 1431 }
1328 } 1432 }
1329 1433
1330 @models = (); # free probe data 1434 # free memory only needed for probing
1435 undef @models;
1436 undef @REGISTRY;
1331 1437
1332 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1438 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1333 unshift @ISA, $MODEL;
1334 1439
1335 # now nuke some methods that are overridden by the backend. 1440 # now nuke some methods that are overridden by the backend.
1336 # SUPER is not allowed. 1441 # SUPER usage is not allowed in these.
1337 for (qw(time signal child idle)) { 1442 for (qw(time signal child idle)) {
1338 undef &{"AnyEvent::Base::$_"} 1443 undef &{"AnyEvent::Base::$_"}
1339 if defined &{"$MODEL\::$_"}; 1444 if defined &{"$MODEL\::$_"};
1340 } 1445 }
1341 1446
1447 _isa_set;
1448
1449 # we're officially open!
1450
1342 if ($ENV{PERL_ANYEVENT_STRICT}) { 1451 if ($ENV{PERL_ANYEVENT_STRICT}) {
1343 eval { require AnyEvent::Strict }; 1452 require AnyEvent::Strict;
1344 warn "AnyEvent: cannot load AnyEvent::Strict: $@"
1345 if $@ && $VERBOSE;
1346 } 1453 }
1347 1454
1455 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1456 require AnyEvent::Debug;
1457 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1458 }
1459
1460 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1461 require AnyEvent::Socket;
1462 require AnyEvent::Debug;
1463
1464 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1465 $shell =~ s/\$\$/$$/g;
1466
1467 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1468 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1469 }
1470
1471 # now the anyevent environment is set up as the user told us to, so
1472 # call the actual user code - post detects
1473
1348 (shift @post_detect)->() while @post_detect; 1474 (shift @post_detect)->() while @post_detect;
1475 undef @post_detect;
1349 1476
1350 *post_detect = sub(&) { 1477 *post_detect = sub(&) {
1351 shift->(); 1478 shift->();
1352 1479
1353 undef 1480 undef
1354 }; 1481 };
1355 1482
1356 $MODEL 1483 $MODEL
1357} 1484}
1358 1485
1359sub AUTOLOAD { 1486for my $name (@methods) {
1360 (my $func = $AUTOLOAD) =~ s/.*://; 1487 *$name = sub {
1361
1362 $method{$func}
1363 or Carp::croak "$func: not a valid AnyEvent class method";
1364
1365 detect; 1488 detect;
1366 1489 # we use goto because
1367 my $class = shift; 1490 # a) it makes the thunk more transparent
1368 $class->$func (@_); 1491 # b) it allows us to delete the thunk later
1369} 1492 goto &{ UNIVERSAL::can AnyEvent => "SUPER::$name" }
1370 1493 };
1371our $POSTPONE_W;
1372our @POSTPONE;
1373
1374sub _postpone_exec {
1375 undef $POSTPONE_W;
1376 (pop @POSTPONE)->()
1377 while @POSTPONE;
1378}
1379
1380sub postpone(&) {
1381 push @POSTPONE, shift;
1382
1383 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1384
1385 ()
1386} 1494}
1387 1495
1388# utility function to dup a filehandle. this is used by many backends 1496# utility function to dup a filehandle. this is used by many backends
1389# to support binding more than one watcher per filehandle (they usually 1497# to support binding more than one watcher per filehandle (they usually
1390# allow only one watcher per fd, so we dup it to get a different one). 1498# allow only one watcher per fd, so we dup it to get a different one).
1414 1522
1415package AE; 1523package AE;
1416 1524
1417our $VERSION = $AnyEvent::VERSION; 1525our $VERSION = $AnyEvent::VERSION;
1418 1526
1527sub _reset() {
1528 eval q{
1419# fall back to the main API by default - backends and AnyEvent::Base 1529 # fall back to the main API by default - backends and AnyEvent::Base
1420# implementations can overwrite these. 1530 # implementations can overwrite these.
1421 1531
1422sub io($$$) { 1532 sub io($$$) {
1423 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2]) 1533 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1424} 1534 }
1425 1535
1426sub timer($$$) { 1536 sub timer($$$) {
1427 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]) 1537 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1428} 1538 }
1429 1539
1430sub signal($$) { 1540 sub signal($$) {
1431 AnyEvent->signal (signal => $_[0], cb => $_[1]) 1541 AnyEvent->signal (signal => $_[0], cb => $_[1])
1432} 1542 }
1433 1543
1434sub child($$) { 1544 sub child($$) {
1435 AnyEvent->child (pid => $_[0], cb => $_[1]) 1545 AnyEvent->child (pid => $_[0], cb => $_[1])
1436} 1546 }
1437 1547
1438sub idle($) { 1548 sub idle($) {
1439 AnyEvent->idle (cb => $_[0]) 1549 AnyEvent->idle (cb => $_[0]);
1440} 1550 }
1441 1551
1442sub cv(;&) { 1552 sub cv(;&) {
1443 AnyEvent->condvar (@_ ? (cb => $_[0]) : ()) 1553 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1444} 1554 }
1445 1555
1446sub now() { 1556 sub now() {
1447 AnyEvent->now 1557 AnyEvent->now
1448} 1558 }
1449 1559
1450sub now_update() { 1560 sub now_update() {
1451 AnyEvent->now_update 1561 AnyEvent->now_update
1452} 1562 }
1453 1563
1454sub time() { 1564 sub time() {
1455 AnyEvent->time 1565 AnyEvent->time
1456} 1566 }
1457 1567
1458*postpone = \&AnyEvent::postpone; 1568 *postpone = \&AnyEvent::postpone;
1569 *log = \&AnyEvent::log;
1570 };
1571 die if $@;
1572}
1573
1574BEGIN { _reset }
1459 1575
1460package AnyEvent::Base; 1576package AnyEvent::Base;
1461 1577
1462# default implementations for many methods 1578# default implementations for many methods
1463 1579
1464sub time { 1580sub time {
1465 eval q{ # poor man's autoloading {} 1581 eval q{ # poor man's autoloading {}
1466 # probe for availability of Time::HiRes 1582 # probe for availability of Time::HiRes
1467 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1583 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1468 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1584 *time = sub { Time::HiRes::time () };
1469 *AE::time = \&Time::HiRes::time; 1585 *AE::time = \& Time::HiRes::time ;
1586 *now = \&time;
1587 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1470 # if (eval "use POSIX (); (POSIX::times())... 1588 # if (eval "use POSIX (); (POSIX::times())...
1471 } else { 1589 } else {
1590 *time = sub { CORE::time };
1591 *AE::time = sub (){ CORE::time };
1592 *now = \&time;
1472 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1593 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1473 *AE::time = sub (){ time }; # epic fail
1474 } 1594 }
1475
1476 *time = sub { AE::time }; # different prototypes
1477 }; 1595 };
1478 die if $@; 1596 die if $@;
1479 1597
1480 &time 1598 &time
1481} 1599}
1482 1600
1483*now = \&time; 1601*now = \&time;
1484
1485sub now_update { } 1602sub now_update { }
1486 1603
1487sub _poll { 1604sub _poll {
1488 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught"; 1605 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1489} 1606}
1575 1692
1576sub signal { 1693sub signal {
1577 eval q{ # poor man's autoloading {} 1694 eval q{ # poor man's autoloading {}
1578 # probe for availability of Async::Interrupt 1695 # probe for availability of Async::Interrupt
1579 if (_have_async_interrupt) { 1696 if (_have_async_interrupt) {
1580 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1697 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1581 1698
1582 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1699 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1583 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1700 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1584 1701
1585 } else { 1702 } else {
1586 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1703 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1587 1704
1588 if (AnyEvent::WIN32) { 1705 if (AnyEvent::WIN32) {
1589 require AnyEvent::Util; 1706 require AnyEvent::Util;
1590 1707
1591 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1708 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1667 : sysread $SIGPIPE_R, (my $dummy), 9; 1784 : sysread $SIGPIPE_R, (my $dummy), 9;
1668 1785
1669 while (%SIG_EV) { 1786 while (%SIG_EV) {
1670 for (keys %SIG_EV) { 1787 for (keys %SIG_EV) {
1671 delete $SIG_EV{$_}; 1788 delete $SIG_EV{$_};
1672 $_->() for values %{ $SIG_CB{$_} || {} }; 1789 &$_ for values %{ $SIG_CB{$_} || {} };
1673 } 1790 }
1674 } 1791 }
1675 }; 1792 };
1676 }; 1793 };
1677 die if $@; 1794 die if $@;
1744 1861
1745 my ($cb, $w, $rcb) = $arg{cb}; 1862 my ($cb, $w, $rcb) = $arg{cb};
1746 1863
1747 $rcb = sub { 1864 $rcb = sub {
1748 if ($cb) { 1865 if ($cb) {
1749 $w = _time; 1866 $w = AE::time;
1750 &$cb; 1867 &$cb;
1751 $w = _time - $w; 1868 $w = AE::time - $w;
1752 1869
1753 # never use more then 50% of the time for the idle watcher, 1870 # never use more then 50% of the time for the idle watcher,
1754 # within some limits 1871 # within some limits
1755 $w = 0.0001 if $w < 0.0001; 1872 $w = 0.0001 if $w < 0.0001;
1756 $w = 5 if $w > 5; 1873 $w = 5 if $w > 5;
1885$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2002$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1886so on. 2003so on.
1887 2004
1888=head1 ENVIRONMENT VARIABLES 2005=head1 ENVIRONMENT VARIABLES
1889 2006
1890The following environment variables are used by this module or its 2007AnyEvent supports a number of environment variables that tune the
1891submodules. 2008runtime behaviour. They are usually evaluated when AnyEvent is
2009loaded, initialised, or a submodule that uses them is loaded. Many of
2010them also cause AnyEvent to load additional modules - for example,
2011C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2012loaded.
1892 2013
1893Note that AnyEvent will remove I<all> environment variables starting with 2014All the environment variables documented here start with
1894C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2015C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1895enabled. 2016namespace. Other modules are encouraged (but by no means required) to use
2017C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2018namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2019be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2020variables starting with C<AE_>, see below).
2021
2022All variables can also be set via the C<AE_> prefix, that is, instead
2023of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2024case there is a clash btween anyevent and another program that uses
2025C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2026variable to the empty string, as those variables take precedence.
2027
2028When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2029to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2030exists. If taint mode is on, then AnyEvent will remove I<all> environment
2031variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2032with C<undef> or the empty string, if the corresaponding C<AE_> variable
2033is set).
2034
2035The exact algorithm is currently:
2036
2037 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2038 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2039 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2040
2041This ensures that child processes will not see the C<AE_> variables.
2042
2043The following environment variables are currently known to AnyEvent:
1896 2044
1897=over 4 2045=over 4
1898 2046
1899=item C<PERL_ANYEVENT_VERBOSE> 2047=item C<PERL_ANYEVENT_VERBOSE>
1900 2048
1901By default, AnyEvent will be completely silent except in fatal 2049By default, AnyEvent will only log messages with loglevel C<3>
1902conditions. You can set this environment variable to make AnyEvent more 2050(C<critical>) or higher (see L<AnyEvent::Log>). You can set this
2051environment variable to a numerical loglevel to make AnyEvent more (or
1903talkative. 2052less) talkative.
1904 2053
2054If you want to do more than just set the global logging level
2055you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2056complex specifications.
2057
2058When set to C<0> (C<off>), then no messages whatsoever will be logged with
2059the default logging settings.
2060
1905When set to C<1> or higher, causes AnyEvent to warn about unexpected 2061When set to C<5> or higher (C<warn>), causes AnyEvent to warn about
1906conditions, such as not being able to load the event model specified by 2062unexpected conditions, such as not being able to load the event model
1907C<PERL_ANYEVENT_MODEL>. 2063specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2064exception - this is the minimum recommended level.
1908 2065
1909When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2066When set to C<7> or higher (info), cause AnyEvent to report which event model it
1910model it chooses. 2067chooses.
1911 2068
1912When set to C<8> or higher, then AnyEvent will report extra information on 2069When set to C<8> or higher (debug), then AnyEvent will report extra information on
1913which optional modules it loads and how it implements certain features. 2070which optional modules it loads and how it implements certain features.
2071
2072=item C<PERL_ANYEVENT_LOG>
2073
2074Accepts rather complex logging specifications. For example, you could log
2075all C<debug> messages of some module to stderr, warnings and above to
2076stderr, and errors and above to syslog, with:
2077
2078 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2079
2080For the rather extensive details, see L<AnyEvent::Log>.
2081
2082This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2083so will take effect even before AnyEvent has initialised itself.
2084
2085Note that specifying this environment variable causes the L<AnyEvent::Log>
2086module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2087using the latter saves a few hundred kB of memory until the first message
2088is being logged.
1914 2089
1915=item C<PERL_ANYEVENT_STRICT> 2090=item C<PERL_ANYEVENT_STRICT>
1916 2091
1917AnyEvent does not do much argument checking by default, as thorough 2092AnyEvent does not do much argument checking by default, as thorough
1918argument checking is very costly. Setting this variable to a true value 2093argument checking is very costly. Setting this variable to a true value
1925Unlike C<use strict> (or its modern cousin, C<< use L<common::sense> 2100Unlike C<use strict> (or its modern cousin, C<< use L<common::sense>
1926>>, it is definitely recommended to keep it off in production. Keeping 2101>>, it is definitely recommended to keep it off in production. Keeping
1927C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2102C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1928can be very useful, however. 2103can be very useful, however.
1929 2104
2105=item C<PERL_ANYEVENT_DEBUG_SHELL>
2106
2107If this env variable is set, then its contents will be interpreted by
2108C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
2109C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
2110that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
2111
2112This happens when the first watcher is created.
2113
2114For example, to bind a debug shell on a unix domain socket in
2115F<< /tmp/debug<pid>.sock >>, you could use this:
2116
2117 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2118
2119Note that creating sockets in F</tmp> is very unsafe on multiuser
2120systems.
2121
2122=item C<PERL_ANYEVENT_DEBUG_WRAP>
2123
2124Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2125debugging purposes. See C<AnyEvent::Debug::wrap> for details.
2126
1930=item C<PERL_ANYEVENT_MODEL> 2127=item C<PERL_ANYEVENT_MODEL>
1931 2128
1932This can be used to specify the event model to be used by AnyEvent, before 2129This can be used to specify the event model to be used by AnyEvent, before
1933auto detection and -probing kicks in. It must be a string consisting 2130auto detection and -probing kicks in.
1934entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 2131
2132It normally is a string consisting entirely of ASCII letters (e.g. C<EV>
2133or C<IOAsync>). The string C<AnyEvent::Impl::> gets prepended and the
1935and the resulting module name is loaded and if the load was successful, 2134resulting module name is loaded and - if the load was successful - used as
1936used as event model. If it fails to load AnyEvent will proceed with 2135event model backend. If it fails to load then AnyEvent will proceed with
1937auto detection and -probing. 2136auto detection and -probing.
1938 2137
1939This functionality might change in future versions. 2138If the string ends with C<::> instead (e.g. C<AnyEvent::Impl::EV::>) then
2139nothing gets prepended and the module name is used as-is (hint: C<::> at
2140the end of a string designates a module name and quotes it appropriately).
1940 2141
1941For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you 2142For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
1942could start your program like this: 2143could start your program like this:
1943 2144
1944 PERL_ANYEVENT_MODEL=Perl perl ... 2145 PERL_ANYEVENT_MODEL=Perl perl ...
1962but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2163but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1963- only support IPv4, never try to resolve or contact IPv6 2164- only support IPv4, never try to resolve or contact IPv6
1964addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2165addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1965IPv6, but prefer IPv6 over IPv4. 2166IPv6, but prefer IPv6 over IPv4.
1966 2167
2168=item C<PERL_ANYEVENT_HOSTS>
2169
2170This variable, if specified, overrides the F</etc/hosts> file used by
2171L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2172from that file instead.
2173
1967=item C<PERL_ANYEVENT_EDNS0> 2174=item C<PERL_ANYEVENT_EDNS0>
1968 2175
1969Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2176Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
1970for DNS. This extension is generally useful to reduce DNS traffic, but 2177DNS. This extension is generally useful to reduce DNS traffic, especially
1971some (broken) firewalls drop such DNS packets, which is why it is off by 2178when DNSSEC is involved, but some (broken) firewalls drop such DNS
1972default. 2179packets, which is why it is off by default.
1973 2180
1974Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2181Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1975EDNS0 in its DNS requests. 2182EDNS0 in its DNS requests.
1976 2183
1977=item C<PERL_ANYEVENT_MAX_FORKS> 2184=item C<PERL_ANYEVENT_MAX_FORKS>
1985resolver - this is the maximum number of parallel DNS requests that are 2192resolver - this is the maximum number of parallel DNS requests that are
1986sent to the DNS server. 2193sent to the DNS server.
1987 2194
1988=item C<PERL_ANYEVENT_RESOLV_CONF> 2195=item C<PERL_ANYEVENT_RESOLV_CONF>
1989 2196
1990The file to use instead of F</etc/resolv.conf> (or OS-specific 2197The absolute path to a F<resolv.conf>-style file to use instead of
1991configuration) in the default resolver. When set to the empty string, no 2198F</etc/resolv.conf> (or the OS-specific configuration) in the default
1992default config will be used. 2199resolver, or the empty string to select the default configuration.
1993 2200
1994=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2201=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1995 2202
1996When neither C<ca_file> nor C<ca_path> was specified during 2203When neither C<ca_file> nor C<ca_path> was specified during
1997L<AnyEvent::TLS> context creation, and either of these environment 2204L<AnyEvent::TLS> context creation, and either of these environment
1998variables exist, they will be used to specify CA certificate locations 2205variables are nonempty, they will be used to specify CA certificate
1999instead of a system-dependent default. 2206locations instead of a system-dependent default.
2000 2207
2001=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2208=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2002 2209
2003When these are set to C<1>, then the respective modules are not 2210When these are set to C<1>, then the respective modules are not
2004loaded. Mostly good for testing AnyEvent itself. 2211loaded. Mostly good for testing AnyEvent itself.
2336(even when used without AnyEvent), but most event loops have acceptable 2543(even when used without AnyEvent), but most event loops have acceptable
2337performance with or without AnyEvent. 2544performance with or without AnyEvent.
2338 2545
2339=item * The overhead AnyEvent adds is usually much smaller than the overhead of 2546=item * The overhead AnyEvent adds is usually much smaller than the overhead of
2340the actual event loop, only with extremely fast event loops such as EV 2547the actual event loop, only with extremely fast event loops such as EV
2341adds AnyEvent significant overhead. 2548does AnyEvent add significant overhead.
2342 2549
2343=item * You should avoid POE like the plague if you want performance or 2550=item * You should avoid POE like the plague if you want performance or
2344reasonable memory usage. 2551reasonable memory usage.
2345 2552
2346=back 2553=back
2721 2928
2722Tutorial/Introduction: L<AnyEvent::Intro>. 2929Tutorial/Introduction: L<AnyEvent::Intro>.
2723 2930
2724FAQ: L<AnyEvent::FAQ>. 2931FAQ: L<AnyEvent::FAQ>.
2725 2932
2726Utility functions: L<AnyEvent::Util>. 2933Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2934(simply logging).
2727 2935
2936Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2937L<AnyEvent::Debug> (interactive shell, watcher tracing).
2938
2728Event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>, L<Glib::EV>, 2939Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2729L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2940L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2941L<Qt>, L<POE>, L<FLTK>.
2730 2942
2731Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2943Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2732L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2944L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2733L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2945L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2734L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 2946L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
2947L<AnyEvent::Impl::FLTK>.
2735 2948
2736Non-blocking file handles, sockets, TCP clients and 2949Non-blocking handles, pipes, stream sockets, TCP clients and
2737servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2950servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2738 2951
2739Asynchronous DNS: L<AnyEvent::DNS>. 2952Asynchronous DNS: L<AnyEvent::DNS>.
2740 2953
2741Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 2954Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines