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.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::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.
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 $AUTOLOAD;
1211our @ISA; 1241our @ISA;
1212 1242
1213our @REGISTRY; 1243our @REGISTRY;
1214 1244
1215our $VERBOSE; 1245our $VERBOSE;
1220 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1250 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1221 1251
1222 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1252 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1223 if ${^TAINT}; 1253 if ${^TAINT};
1224 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
1225 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1261 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1226
1227} 1262}
1228 1263
1229our $MAX_SIGNAL_LATENCY = 10; 1264our $MAX_SIGNAL_LATENCY = 10;
1230 1265
1231our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1266our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1235 $PROTOCOL{$_} = ++$idx 1270 $PROTOCOL{$_} = ++$idx
1236 for reverse split /\s*,\s*/, 1271 for reverse split /\s*,\s*/,
1237 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1272 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1238} 1273}
1239 1274
1275our @post_detect;
1276
1277sub post_detect(&) {
1278 my ($cb) = @_;
1279
1280 push @post_detect, $cb;
1281
1282 defined wantarray
1283 ? bless \$cb, "AnyEvent::Util::postdetect"
1284 : ()
1285}
1286
1287sub AnyEvent::Util::postdetect::DESTROY {
1288 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1289}
1290
1291our $POSTPONE_W;
1292our @POSTPONE;
1293
1294sub _postpone_exec {
1295 undef $POSTPONE_W;
1296
1297 &{ shift @POSTPONE }
1298 while @POSTPONE;
1299}
1300
1301sub postpone(&) {
1302 push @POSTPONE, shift;
1303
1304 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1305
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
1322}
1323
1240my @models = ( 1324our @models = (
1241 [EV:: => AnyEvent::Impl::EV:: , 1], 1325 [EV:: => AnyEvent::Impl::EV:: , 1],
1242 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1326 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
1243 # everything below here will not (normally) be autoprobed 1327 # everything below here will not (normally) be autoprobed
1244 # as the pure perl backend should work everywhere 1328 # as the pure perl backend should work everywhere
1245 # and is usually faster 1329 # and is usually faster
1250 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1334 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1251 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1335 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1252 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1336 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1253 [Wx:: => AnyEvent::Impl::POE::], 1337 [Wx:: => AnyEvent::Impl::POE::],
1254 [Prima:: => AnyEvent::Impl::POE::], 1338 [Prima:: => AnyEvent::Impl::POE::],
1255 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], 1339 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1256 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1340 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1257 [FLTK:: => AnyEvent::Impl::FLTK::], 1341 [FLTK:: => AnyEvent::Impl::FLTK::],
1258); 1342);
1259 1343
1260our %method = map +($_ => 1), 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}
1364
1365# all autoloaded methods reserve the complete glob, not just the method slot.
1366# due to bugs in perls method cache implementation.
1261 qw(io timer time now now_update signal child idle condvar DESTROY); 1367our @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 1368
1279sub detect() { 1369sub detect() {
1370 return $MODEL if $MODEL; # some programs keep references to detect
1371
1372 local $!; # for good measure
1373 local $SIG{__DIE__}; # we use eval
1374
1280 # free some memory 1375 # free some memory
1281 *detect = sub () { $MODEL }; 1376 *detect = sub () { $MODEL };
1377 # undef &func doesn't correctly update the method cache. grmbl.
1378 # so we delete the whole glob. grmbl.
1379 # otoh, perl doesn't let me undef an active usb, but it lets me free
1380 # a glob with an active sub. hrm. i hope it works, but perl is
1381 # usually buggy in this department. sigh.
1382 delete @{"AnyEvent::"}{@methods};
1383 undef @methods;
1282 1384
1283 local $!; # for good measure
1284 local $SIG{__DIE__};
1285
1286 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1385 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1287 my $model = "AnyEvent::Impl::$1"; 1386 my $model = $1;
1387 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1288 if (eval "require $model") { 1388 if (eval "require $model") {
1389 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1289 $MODEL = $model; 1390 $MODEL = $model;
1290 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1291 } else { 1391 } else {
1292 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$@";
1293 } 1393 }
1294 } 1394 }
1295 1395
1296 # check for already loaded models 1396 # check for already loaded models
1297 unless ($MODEL) { 1397 unless ($MODEL) {
1298 for (@REGISTRY, @models) { 1398 for (@REGISTRY, @models) {
1299 my ($package, $model) = @$_; 1399 my ($package, $model) = @$_;
1300 if (${"$package\::VERSION"} > 0) { 1400 if (${"$package\::VERSION"} > 0) {
1301 if (eval "require $model") { 1401 if (eval "require $model") {
1402 AnyEvent::log 7 => "autodetected model '$model', using it.";
1302 $MODEL = $model; 1403 $MODEL = $model;
1303 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1304 last; 1404 last;
1305 } 1405 }
1306 } 1406 }
1307 } 1407 }
1308 1408
1314 $autoload 1414 $autoload
1315 and eval "require $package" 1415 and eval "require $package"
1316 and ${"$package\::VERSION"} > 0 1416 and ${"$package\::VERSION"} > 0
1317 and eval "require $model" 1417 and eval "require $model"
1318 ) { 1418 ) {
1419 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1319 $MODEL = $model; 1420 $MODEL = $model;
1320 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1321 last; 1421 last;
1322 } 1422 }
1323 } 1423 }
1324 1424
1325 $MODEL 1425 $MODEL
1326 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?\n"; 1426 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1327 } 1427 }
1328 } 1428 }
1329 1429
1330 @models = (); # free probe data 1430 # free memory only needed for probing
1431 undef @models;
1432 undef @REGISTRY;
1331 1433
1332 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1434 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1333 unshift @ISA, $MODEL;
1334 1435
1335 # now nuke some methods that are overridden by the backend. 1436 # now nuke some methods that are overridden by the backend.
1336 # SUPER is not allowed. 1437 # SUPER usage is not allowed in these.
1337 for (qw(time signal child idle)) { 1438 for (qw(time signal child idle)) {
1338 undef &{"AnyEvent::Base::$_"} 1439 undef &{"AnyEvent::Base::$_"}
1339 if defined &{"$MODEL\::$_"}; 1440 if defined &{"$MODEL\::$_"};
1340 } 1441 }
1341 1442
1443 _isa_set;
1444
1445 # we're officially open!
1446
1342 if ($ENV{PERL_ANYEVENT_STRICT}) { 1447 if ($ENV{PERL_ANYEVENT_STRICT}) {
1343 eval { require AnyEvent::Strict }; 1448 require AnyEvent::Strict;
1344 warn "AnyEvent: cannot load AnyEvent::Strict: $@"
1345 if $@ && $VERBOSE;
1346 } 1449 }
1347 1450
1451 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1452 require AnyEvent::Debug;
1453 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1454 }
1455
1456 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1457 require AnyEvent::Socket;
1458 require AnyEvent::Debug;
1459
1460 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1461 $shell =~ s/\$\$/$$/g;
1462
1463 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1464 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
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
1469
1348 (shift @post_detect)->() while @post_detect; 1470 (shift @post_detect)->() while @post_detect;
1471 undef @post_detect;
1349 1472
1350 *post_detect = sub(&) { 1473 *post_detect = sub(&) {
1351 shift->(); 1474 shift->();
1352 1475
1353 undef 1476 undef
1354 }; 1477 };
1355 1478
1356 $MODEL 1479 $MODEL
1357} 1480}
1358 1481
1359sub AUTOLOAD { 1482for my $name (@methods) {
1360 (my $func = $AUTOLOAD) =~ s/.*://; 1483 *$name = sub {
1361
1362 $method{$func}
1363 or Carp::croak "$func: not a valid AnyEvent class method";
1364
1365 detect; 1484 detect;
1366 1485 # we use goto because
1367 my $class = shift; 1486 # a) it makes the thunk more transparent
1368 $class->$func (@_); 1487 # b) it allows us to delete the thunk later
1369} 1488 goto &{ UNIVERSAL::can AnyEvent => "SUPER::$name" }
1370 1489 };
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} 1490}
1387 1491
1388# utility function to dup a filehandle. this is used by many backends 1492# utility function to dup a filehandle. this is used by many backends
1389# to support binding more than one watcher per filehandle (they usually 1493# 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). 1494# allow only one watcher per fd, so we dup it to get a different one).
1414 1518
1415package AE; 1519package AE;
1416 1520
1417our $VERSION = $AnyEvent::VERSION; 1521our $VERSION = $AnyEvent::VERSION;
1418 1522
1523sub _reset() {
1524 eval q{
1419# fall back to the main API by default - backends and AnyEvent::Base 1525 # fall back to the main API by default - backends and AnyEvent::Base
1420# implementations can overwrite these. 1526 # implementations can overwrite these.
1421 1527
1422sub io($$$) { 1528 sub io($$$) {
1423 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2]) 1529 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1424} 1530 }
1425 1531
1426sub timer($$$) { 1532 sub timer($$$) {
1427 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]) 1533 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1428} 1534 }
1429 1535
1430sub signal($$) { 1536 sub signal($$) {
1431 AnyEvent->signal (signal => $_[0], cb => $_[1]) 1537 AnyEvent->signal (signal => $_[0], cb => $_[1])
1432} 1538 }
1433 1539
1434sub child($$) { 1540 sub child($$) {
1435 AnyEvent->child (pid => $_[0], cb => $_[1]) 1541 AnyEvent->child (pid => $_[0], cb => $_[1])
1436} 1542 }
1437 1543
1438sub idle($) { 1544 sub idle($) {
1439 AnyEvent->idle (cb => $_[0]) 1545 AnyEvent->idle (cb => $_[0]);
1440} 1546 }
1441 1547
1442sub cv(;&) { 1548 sub cv(;&) {
1443 AnyEvent->condvar (@_ ? (cb => $_[0]) : ()) 1549 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1444} 1550 }
1445 1551
1446sub now() { 1552 sub now() {
1447 AnyEvent->now 1553 AnyEvent->now
1448} 1554 }
1449 1555
1450sub now_update() { 1556 sub now_update() {
1451 AnyEvent->now_update 1557 AnyEvent->now_update
1452} 1558 }
1453 1559
1454sub time() { 1560 sub time() {
1455 AnyEvent->time 1561 AnyEvent->time
1456} 1562 }
1457 1563
1458*postpone = \&AnyEvent::postpone; 1564 *postpone = \&AnyEvent::postpone;
1565 *log = \&AnyEvent::log;
1566 };
1567 die if $@;
1568}
1569
1570BEGIN { _reset }
1459 1571
1460package AnyEvent::Base; 1572package AnyEvent::Base;
1461 1573
1462# default implementations for many methods 1574# default implementations for many methods
1463 1575
1464sub time { 1576sub time {
1465 eval q{ # poor man's autoloading {} 1577 eval q{ # poor man's autoloading {}
1466 # probe for availability of Time::HiRes 1578 # probe for availability of Time::HiRes
1467 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1579 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1468 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1580 *time = sub { Time::HiRes::time () };
1469 *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.";
1470 # if (eval "use POSIX (); (POSIX::times())... 1584 # if (eval "use POSIX (); (POSIX::times())...
1471 } else { 1585 } else {
1586 *time = sub { CORE::time };
1587 *AE::time = sub (){ CORE::time };
1588 *now = \&time;
1472 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!";
1473 *AE::time = sub (){ time }; # epic fail
1474 } 1590 }
1475
1476 *time = sub { AE::time }; # different prototypes
1477 }; 1591 };
1478 die if $@; 1592 die if $@;
1479 1593
1480 &time 1594 &time
1481} 1595}
1482 1596
1483*now = \&time; 1597*now = \&time;
1484
1485sub now_update { } 1598sub now_update { }
1486 1599
1487sub _poll { 1600sub _poll {
1488 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught"; 1601 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1489} 1602}
1575 1688
1576sub signal { 1689sub signal {
1577 eval q{ # poor man's autoloading {} 1690 eval q{ # poor man's autoloading {}
1578 # probe for availability of Async::Interrupt 1691 # probe for availability of Async::Interrupt
1579 if (_have_async_interrupt) { 1692 if (_have_async_interrupt) {
1580 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.";
1581 1694
1582 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1695 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1583 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1696 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1584 1697
1585 } else { 1698 } else {
1586 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.";
1587 1700
1588 if (AnyEvent::WIN32) { 1701 if (AnyEvent::WIN32) {
1589 require AnyEvent::Util; 1702 require AnyEvent::Util;
1590 1703
1591 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1704 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1667 : sysread $SIGPIPE_R, (my $dummy), 9; 1780 : sysread $SIGPIPE_R, (my $dummy), 9;
1668 1781
1669 while (%SIG_EV) { 1782 while (%SIG_EV) {
1670 for (keys %SIG_EV) { 1783 for (keys %SIG_EV) {
1671 delete $SIG_EV{$_}; 1784 delete $SIG_EV{$_};
1672 $_->() for values %{ $SIG_CB{$_} || {} }; 1785 &$_ for values %{ $SIG_CB{$_} || {} };
1673 } 1786 }
1674 } 1787 }
1675 }; 1788 };
1676 }; 1789 };
1677 die if $@; 1790 die if $@;
1744 1857
1745 my ($cb, $w, $rcb) = $arg{cb}; 1858 my ($cb, $w, $rcb) = $arg{cb};
1746 1859
1747 $rcb = sub { 1860 $rcb = sub {
1748 if ($cb) { 1861 if ($cb) {
1749 $w = _time; 1862 $w = AE::time;
1750 &$cb; 1863 &$cb;
1751 $w = _time - $w; 1864 $w = AE::time - $w;
1752 1865
1753 # never use more then 50% of the time for the idle watcher, 1866 # never use more then 50% of the time for the idle watcher,
1754 # within some limits 1867 # within some limits
1755 $w = 0.0001 if $w < 0.0001; 1868 $w = 0.0001 if $w < 0.0001;
1756 $w = 5 if $w > 5; 1869 $w = 5 if $w > 5;
1885$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 1998$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1886so on. 1999so on.
1887 2000
1888=head1 ENVIRONMENT VARIABLES 2001=head1 ENVIRONMENT VARIABLES
1889 2002
1890The following environment variables are used by this module or its 2003AnyEvent supports a number of environment variables that tune the
1891submodules. 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.
1892 2009
1893Note that AnyEvent will remove I<all> environment variables starting with 2010All the environment variables documented here start with
1894C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2011C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1895enabled. 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:
1896 2040
1897=over 4 2041=over 4
1898 2042
1899=item C<PERL_ANYEVENT_VERBOSE> 2043=item C<PERL_ANYEVENT_VERBOSE>
1900 2044
1901By default, AnyEvent will be completely silent except in fatal 2045By default, AnyEvent will be completely silent except in fatal
1902conditions. You can set this environment variable to make AnyEvent more 2046conditions. You can set this environment variable to make AnyEvent more
1903talkative. 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.
1904 2050
1905When 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
1906conditions, 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
1907C<PERL_ANYEVENT_MODEL>. 2053C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
2054is the minimum recommended level.
1908 2055
1909When 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
1910model it chooses. 2057chooses.
1911 2058
1912When 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
1913which 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.
1914 2079
1915=item C<PERL_ANYEVENT_STRICT> 2080=item C<PERL_ANYEVENT_STRICT>
1916 2081
1917AnyEvent does not do much argument checking by default, as thorough 2082AnyEvent does not do much argument checking by default, as thorough
1918argument checking is very costly. Setting this variable to a true value 2083argument checking is very costly. Setting this variable to a true value
1925Unlike C<use strict> (or its modern cousin, C<< use L<common::sense> 2090Unlike C<use strict> (or its modern cousin, C<< use L<common::sense>
1926>>, it is definitely recommended to keep it off in production. Keeping 2091>>, it is definitely recommended to keep it off in production. Keeping
1927C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2092C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1928can be very useful, however. 2093can be very useful, however.
1929 2094
2095=item C<PERL_ANYEVENT_DEBUG_SHELL>
2096
2097If this env variable is set, then its contents will be interpreted by
2098C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
2099C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
2100that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
2101
2102This happens when the first watcher is created.
2103
2104For example, to bind a debug shell on a unix domain socket in
2105F<< /tmp/debug<pid>.sock >>, you could use this:
2106
2107 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2108
2109Note that creating sockets in F</tmp> is very unsafe on multiuser
2110systems.
2111
2112=item C<PERL_ANYEVENT_DEBUG_WRAP>
2113
2114Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2115debugging purposes. See C<AnyEvent::Debug::wrap> for details.
2116
1930=item C<PERL_ANYEVENT_MODEL> 2117=item C<PERL_ANYEVENT_MODEL>
1931 2118
1932This can be used to specify the event model to be used by AnyEvent, before 2119This 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 2120auto detection and -probing kicks in.
1934entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 2121
2122It normally is a string consisting entirely of ASCII letters (e.g. C<EV>
2123or C<IOAsync>). The string C<AnyEvent::Impl::> gets prepended and the
1935and the resulting module name is loaded and if the load was successful, 2124resulting 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 2125event model backend. If it fails to load then AnyEvent will proceed with
1937auto detection and -probing. 2126auto detection and -probing.
1938 2127
1939This functionality might change in future versions. 2128If the string ends with C<::> instead (e.g. C<AnyEvent::Impl::EV::>) then
2129nothing gets prepended and the module name is used as-is (hint: C<::> at
2130the end of a string designates a module name and quotes it appropriately).
1940 2131
1941For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you 2132For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
1942could start your program like this: 2133could start your program like this:
1943 2134
1944 PERL_ANYEVENT_MODEL=Perl perl ... 2135 PERL_ANYEVENT_MODEL=Perl perl ...
1962but 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>
1963- only support IPv4, never try to resolve or contact IPv6 2154- only support IPv4, never try to resolve or contact IPv6
1964addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2155addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1965IPv6, but prefer IPv6 over IPv4. 2156IPv6, but prefer IPv6 over IPv4.
1966 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
1967=item C<PERL_ANYEVENT_EDNS0> 2164=item C<PERL_ANYEVENT_EDNS0>
1968 2165
1969Used 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
1970for DNS. This extension is generally useful to reduce DNS traffic, but 2167DNS. This extension is generally useful to reduce DNS traffic, especially
1971some (broken) firewalls drop such DNS packets, which is why it is off by 2168when DNSSEC is involved, but some (broken) firewalls drop such DNS
1972default. 2169packets, which is why it is off by default.
1973 2170
1974Setting 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
1975EDNS0 in its DNS requests. 2172EDNS0 in its DNS requests.
1976 2173
1977=item C<PERL_ANYEVENT_MAX_FORKS> 2174=item C<PERL_ANYEVENT_MAX_FORKS>
1985resolver - this is the maximum number of parallel DNS requests that are 2182resolver - this is the maximum number of parallel DNS requests that are
1986sent to the DNS server. 2183sent to the DNS server.
1987 2184
1988=item C<PERL_ANYEVENT_RESOLV_CONF> 2185=item C<PERL_ANYEVENT_RESOLV_CONF>
1989 2186
1990The 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
1991configuration) in the default resolver. When set to the empty string, no 2188F</etc/resolv.conf> (or the OS-specific configuration) in the default
1992default config will be used. 2189resolver, or the empty string to select the default configuration.
1993 2190
1994=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2191=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1995 2192
1996When neither C<ca_file> nor C<ca_path> was specified during 2193When neither C<ca_file> nor C<ca_path> was specified during
1997L<AnyEvent::TLS> context creation, and either of these environment 2194L<AnyEvent::TLS> context creation, and either of these environment
1998variables exist, they will be used to specify CA certificate locations 2195variables are nonempty, they will be used to specify CA certificate
1999instead of a system-dependent default. 2196locations instead of a system-dependent default.
2000 2197
2001=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>
2002 2199
2003When 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
2004loaded. Mostly good for testing AnyEvent itself. 2201loaded. Mostly good for testing AnyEvent itself.
2336(even when used without AnyEvent), but most event loops have acceptable 2533(even when used without AnyEvent), but most event loops have acceptable
2337performance with or without AnyEvent. 2534performance with or without AnyEvent.
2338 2535
2339=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
2340the 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
2341adds AnyEvent significant overhead. 2538does AnyEvent add significant overhead.
2342 2539
2343=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
2344reasonable memory usage. 2541reasonable memory usage.
2345 2542
2346=back 2543=back
2721 2918
2722Tutorial/Introduction: L<AnyEvent::Intro>. 2919Tutorial/Introduction: L<AnyEvent::Intro>.
2723 2920
2724FAQ: L<AnyEvent::FAQ>. 2921FAQ: L<AnyEvent::FAQ>.
2725 2922
2726Utility functions: L<AnyEvent::Util>. 2923Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2924(simply logging).
2727 2925
2926Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2927L<AnyEvent::Debug> (interactive shell, watcher tracing).
2928
2728Event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>, L<Glib::EV>, 2929Supported 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>. 2930L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2931L<Qt>, L<POE>, L<FLTK>.
2730 2932
2731Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2933Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2732L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2934L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2733L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2935L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2734L<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>.
2735 2938
2736Non-blocking file handles, sockets, TCP clients and 2939Non-blocking handles, pipes, stream sockets, TCP clients and
2737servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2940servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2738 2941
2739Asynchronous DNS: L<AnyEvent::DNS>. 2942Asynchronous DNS: L<AnyEvent::DNS>.
2740 2943
2741Thread 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