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.362 by root, Sun Aug 14 01:57:18 2011 UTC vs.
Revision 1.369 by root, Wed Aug 17 02:32:01 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
… …
1049It should use C<postpone>: 1049It should use C<postpone>:
1050 1050
1051 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later 1051 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1052 if $some_error_condition; 1052 if $some_error_condition;
1053 1053
1054=item AnyEvent::log $level, $msg[, @args]
1055
1056Log the given C<$msg> at the given C<$level>.
1057
1058Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> -
1059consequently, look at the L<AnyEvent::Log> documentation for details.
1060
1061If you want to sprinkle loads of logging calls around your code, consider
1062creating a logger callback with the C<AnyEvent::Log::logger< function.
1063
1054=back 1064=back
1055 1065
1056=head1 WHAT TO DO IN A MODULE 1066=head1 WHAT TO DO IN A MODULE
1057 1067
1058As a module author, you should C<use AnyEvent> and call AnyEvent methods 1068As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
1114 1124
1115 1125
1116=head1 OTHER MODULES 1126=head1 OTHER MODULES
1117 1127
1118The following is a non-exhaustive list of additional modules that use 1128The following is a non-exhaustive list of additional modules that use
1119AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1129AnyEvent as a client and can therefore be mixed easily with other
1120modules and other event loops in the same program. Some of the modules 1130AnyEvent modules and other event loops in the same program. Some of the
1121come as part of AnyEvent, the others are available via CPAN. 1131modules come as part of AnyEvent, the others are available via CPAN (see
1132L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1133a longer non-exhaustive list), and the list is heavily biased towards
1134modules of the AnyEvent author himself :)
1122 1135
1123=over 4 1136=over 4
1124 1137
1125=item L<AnyEvent::Util> 1138=item L<AnyEvent::Util>
1126 1139
… …
1224 1237
1225 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1238 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1226 if ${^TAINT}; 1239 if ${^TAINT};
1227 1240
1228 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1241 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1229
1230} 1242}
1231 1243
1232our $MAX_SIGNAL_LATENCY = 10; 1244our $MAX_SIGNAL_LATENCY = 10;
1233 1245
1234our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1246our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
… …
1270 push @POSTPONE, shift; 1282 push @POSTPONE, shift;
1271 1283
1272 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec); 1284 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1273 1285
1274 () 1286 ()
1287}
1288
1289sub log($$;@) {
1290 require AnyEvent::Log;
1291 # AnyEvent::Log overwrites this function
1292 goto &log;
1275} 1293}
1276 1294
1277our @models = ( 1295our @models = (
1278 [EV:: => AnyEvent::Impl::EV:: , 1], 1296 [EV:: => AnyEvent::Impl::EV:: , 1],
1279 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1297 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
… …
1318# all autoloaded methods reserve the complete glob, not just the method slot. 1336# all autoloaded methods reserve the complete glob, not just the method slot.
1319# due to bugs in perls method cache implementation. 1337# due to bugs in perls method cache implementation.
1320our @methods = qw(io timer time now now_update signal child idle condvar); 1338our @methods = qw(io timer time now now_update signal child idle condvar);
1321 1339
1322sub detect() { 1340sub detect() {
1341 return $MODEL if $MODEL; # some programs keep references to detect
1342
1323 local $!; # for good measure 1343 local $!; # for good measure
1324 local $SIG{__DIE__}; # we use eval 1344 local $SIG{__DIE__}; # we use eval
1325 1345
1326 # free some memory 1346 # free some memory
1327 *detect = sub () { $MODEL }; 1347 *detect = sub () { $MODEL };
… …
1336 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1356 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1337 my $model = $1; 1357 my $model = $1;
1338 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1358 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1339 if (eval "require $model") { 1359 if (eval "require $model") {
1340 $MODEL = $model; 1360 $MODEL = $model;
1341 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2; 1361 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."
1362 if $VERBOSE >= 7;
1342 } else { 1363 } else {
1343 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1364 AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1344 } 1365 }
1345 } 1366 }
1346 1367
1347 # check for already loaded models 1368 # check for already loaded models
1348 unless ($MODEL) { 1369 unless ($MODEL) {
1349 for (@REGISTRY, @models) { 1370 for (@REGISTRY, @models) {
1350 my ($package, $model) = @$_; 1371 my ($package, $model) = @$_;
1351 if (${"$package\::VERSION"} > 0) { 1372 if (${"$package\::VERSION"} > 0) {
1352 if (eval "require $model") { 1373 if (eval "require $model") {
1353 $MODEL = $model; 1374 $MODEL = $model;
1354 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2; 1375 AnyEvent::log 7 => "autodetected model '$model', using it."
1376 if $VERBOSE >= 7;
1355 last; 1377 last;
1356 } 1378 }
1357 } 1379 }
1358 } 1380 }
1359 1381
… …
1366 and eval "require $package" 1388 and eval "require $package"
1367 and ${"$package\::VERSION"} > 0 1389 and ${"$package\::VERSION"} > 0
1368 and eval "require $model" 1390 and eval "require $model"
1369 ) { 1391 ) {
1370 $MODEL = $model; 1392 $MODEL = $model;
1371 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2; 1393 AnyEvent::log 7 => "autoloaded model '$model', using it."
1394 if $VERBOSE >= 7;
1372 last; 1395 last;
1373 } 1396 }
1374 } 1397 }
1375 1398
1376 $MODEL 1399 $MODEL
1377 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?\n"; 1400 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1378 } 1401 }
1379 } 1402 }
1380 1403
1381 # free memory only needed for probing 1404 # free memory only needed for probing
1382 undef @models; 1405 undef @models;
… …
1391 if defined &{"$MODEL\::$_"}; 1414 if defined &{"$MODEL\::$_"};
1392 } 1415 }
1393 1416
1394 _isa_set; 1417 _isa_set;
1395 1418
1419 # we're officially open!
1420
1396 if ($ENV{PERL_ANYEVENT_STRICT}) { 1421 if ($ENV{PERL_ANYEVENT_STRICT}) {
1397 require AnyEvent::Strict; 1422 require AnyEvent::Strict;
1398 } 1423 }
1399 1424
1400 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1425 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1401 require AnyEvent::Debug; 1426 require AnyEvent::Debug;
1402 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1427 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1403 } 1428 }
1404 1429
1405 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1430 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1406 require AnyEvent::Socket; 1431 require AnyEvent::Socket;
1407 require AnyEvent::Debug; 1432 require AnyEvent::Debug;
1408 1433
1409 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL}; 1434 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1410 $shell =~ s/\$\$/$$/g; 1435 $shell =~ s/\$\$/$$/g;
1411 1436
1412 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell); 1437 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1413 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1438 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1414 } 1439 }
1440
1441 # now the anyevent environment is set up as the user told us to, so
1442 # call the actual user code - post detects
1415 1443
1416 (shift @post_detect)->() while @post_detect; 1444 (shift @post_detect)->() while @post_detect;
1417 undef @post_detect; 1445 undef @post_detect;
1418 1446
1419 *post_detect = sub(&) { 1447 *post_detect = sub(&) {
… …
1506 sub time() { 1534 sub time() {
1507 AnyEvent->time 1535 AnyEvent->time
1508 } 1536 }
1509 1537
1510 *postpone = \&AnyEvent::postpone; 1538 *postpone = \&AnyEvent::postpone;
1539 *log = \&AnyEvent::log;
1511 }; 1540 };
1512 die if $@; 1541 die if $@;
1513} 1542}
1514 1543
1515BEGIN { _reset } 1544BEGIN { _reset }
… …
1520 1549
1521sub time { 1550sub time {
1522 eval q{ # poor man's autoloading {} 1551 eval q{ # poor man's autoloading {}
1523 # probe for availability of Time::HiRes 1552 # probe for availability of Time::HiRes
1524 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1553 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1525 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1554 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy."
1555 if $AnyEvent::VERBOSE >= 8;
1526 *time = sub { Time::HiRes::time () }; 1556 *time = sub { Time::HiRes::time () };
1527 *AE::time = \& Time::HiRes::time ; 1557 *AE::time = \& Time::HiRes::time ;
1528 # if (eval "use POSIX (); (POSIX::times())... 1558 # if (eval "use POSIX (); (POSIX::times())...
1529 } else { 1559 } else {
1530 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1560 AnyEvent::log critical => "using built-in time(), WARNING, no sub-second resolution!";
1531 *time = sub { CORE::time }; 1561 *time = sub { CORE::time };
1532 *AE::time = sub (){ CORE::time }; 1562 *AE::time = sub (){ CORE::time };
1533 } 1563 }
1534 1564
1535 *now = \&time; 1565 *now = \&time;
… …
1633 1663
1634sub signal { 1664sub signal {
1635 eval q{ # poor man's autoloading {} 1665 eval q{ # poor man's autoloading {}
1636 # probe for availability of Async::Interrupt 1666 # probe for availability of Async::Interrupt
1637 if (_have_async_interrupt) { 1667 if (_have_async_interrupt) {
1638 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1668 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling."
1669 if $AnyEvent::VERBOSE >= 8;
1639 1670
1640 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1671 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1641 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1672 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1642 1673
1643 } else { 1674 } else {
1644 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1675 AnyEvent::log 8 => "using emulated perl signal handling with latency timer."
1676 if $AnyEvent::VERBOSE >= 8;
1645 1677
1646 if (AnyEvent::WIN32) { 1678 if (AnyEvent::WIN32) {
1647 require AnyEvent::Util; 1679 require AnyEvent::Util;
1648 1680
1649 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1681 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1958 1990
1959By default, AnyEvent will be completely silent except in fatal 1991By default, AnyEvent will be completely silent except in fatal
1960conditions. You can set this environment variable to make AnyEvent more 1992conditions. You can set this environment variable to make AnyEvent more
1961talkative. 1993talkative.
1962 1994
1963When set to C<1> or higher, causes AnyEvent to warn about unexpected 1995When set to C<5> or higher, causes AnyEvent to warn about unexpected
1964conditions, such as not being able to load the event model specified by 1996conditions, such as not being able to load the event model specified by
1965C<PERL_ANYEVENT_MODEL>. 1997C<PERL_ANYEVENT_MODEL>.
1966 1998
1967When set to C<2> or higher, cause AnyEvent to report to STDERR which event 1999When set to C<7> or higher, cause AnyEvent to report to STDERR which event
1968model it chooses. 2000model it chooses.
1969 2001
1970When set to C<8> or higher, then AnyEvent will report extra information on 2002When set to C<8> or higher, then AnyEvent will report extra information on
1971which optional modules it loads and how it implements certain features. 2003which optional modules it loads and how it implements certain features.
1972 2004
… …
1995This takes place when the first watcher is created. 2027This takes place when the first watcher is created.
1996 2028
1997For example, to bind a debug shell on a unix domain socket in 2029For example, to bind a debug shell on a unix domain socket in
1998F<< /tmp/debug<pid>.sock >>, you could use this: 2030F<< /tmp/debug<pid>.sock >>, you could use this:
1999 2031
2000 PERL_ANYEVENT_DEBUG_SHELL=unix/:/tmp/debug\$\$.sock perlprog 2032 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2001 2033
2002Note that creating sockets in F</tmp> is very unsafe on multiuser 2034Note that creating sockets in F</tmp> is very unsafe on multiuser
2003systems. 2035systems.
2004 2036
2005=item C<PERL_ANYEVENT_DEBUG_WRAP> 2037=item C<PERL_ANYEVENT_DEBUG_WRAP>
… …
2805 2837
2806Tutorial/Introduction: L<AnyEvent::Intro>. 2838Tutorial/Introduction: L<AnyEvent::Intro>.
2807 2839
2808FAQ: L<AnyEvent::FAQ>. 2840FAQ: L<AnyEvent::FAQ>.
2809 2841
2810Utility functions: L<AnyEvent::Util>. 2842Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2843(simply logging).
2811 2844
2845Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2846L<AnyEvent::Debug> (interactive shell, watcher tracing).
2847
2812Event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>, L<Glib::EV>, 2848Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2813L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2849L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2850L<Qt>, L<POE>, L<FLTK>.
2814 2851
2815Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2852Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2816L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2853L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2817L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2854L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2818L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 2855L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
2856L<AnyEvent::Impl::FLTK>.
2819 2857
2820Non-blocking file handles, sockets, TCP clients and 2858Non-blocking handles, pipes, stream sockets, TCP clients and
2821servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2859servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2822 2860
2823Asynchronous DNS: L<AnyEvent::DNS>. 2861Asynchronous DNS: L<AnyEvent::DNS>.
2824 2862
2825Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 2863Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.

Diff Legend

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