ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.358 by root, Sat Aug 13 02:35:32 2011 UTC vs.
Revision 1.421 by root, Fri Sep 5 22:24:12 2014 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, UV, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
6and POE are various supported event loops/environments. 6Qt, FLTK 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
… …
271 271
272Example 2: fire an event after 0.5 seconds, then roughly every second. 272Example 2: fire an event after 0.5 seconds, then roughly every second.
273 273
274 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub { 274 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
275 warn "timeout\n"; 275 warn "timeout\n";
276 }; 276 });
277 277
278=head3 TIMING ISSUES 278=head3 TIMING ISSUES
279 279
280There are two ways to handle timers: based on real time (relative, "fire 280There are two ways to handle timers: based on real time (relative, "fire
281in 10 seconds") and based on wallclock time (absolute, "fire at 12 281in 10 seconds") and based on wallclock time (absolute, "fire at 12
… …
415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's 415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's
416pure perl implementation). 416pure perl implementation).
417 417
418=head3 Safe/Unsafe Signals 418=head3 Safe/Unsafe Signals
419 419
420Perl signals can be either "safe" (synchronous to opcode handling) or 420Perl signals can be either "safe" (synchronous to opcode handling)
421"unsafe" (asynchronous) - the former might get delayed indefinitely, the 421or "unsafe" (asynchronous) - the former might delay signal delivery
422latter might corrupt your memory. 422indefinitely, the latter might corrupt your memory.
423 423
424AnyEvent signal handlers are, in addition, synchronous to the event loop, 424AnyEvent signal handlers are, in addition, synchronous to the event loop,
425i.e. they will not interrupt your running perl program but will only be 425i.e. they will not interrupt your running perl program but will only be
426called as part of the normal event handling (just like timer, I/O etc. 426called as part of the normal event handling (just like timer, I/O etc.
427callbacks, too). 427callbacks, too).
428 428
429=head3 Signal Races, Delays and Workarounds 429=head3 Signal Races, Delays and Workarounds
430 430
431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support
432callbacks to signals in a generic way, which is a pity, as you cannot 432attaching callbacks to signals in a generic way, which is a pity,
433do race-free signal handling in perl, requiring C libraries for 433as you cannot do race-free signal handling in perl, requiring
434this. AnyEvent will try to do its best, which means in some cases, 434C libraries for this. AnyEvent will try to do its best, which
435signals will be delayed. The maximum time a signal might be delayed is 435means in some cases, signals will be delayed. The maximum time
436specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This 436a signal might be delayed is 10 seconds by default, but can
437variable can be changed only before the first signal watcher is created, 437be overriden via C<$ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY}> or
438and should be left alone otherwise. This variable determines how often 438C<$AnyEvent::MAX_SIGNAL_LATENCY> - see the L<ENVIRONMENT VARIABLES>
439AnyEvent polls for signals (in case a wake-up was missed). Higher values 439section for details.
440will cause fewer spurious wake-ups, which is better for power and CPU
441saving.
442 440
443All these problems can be avoided by installing the optional 441All these problems can be avoided by installing the optional
444L<Async::Interrupt> module, which works with most event loops. It will not 442L<Async::Interrupt> module, which works with most event loops. It will not
445work with inherently broken event loops such as L<Event> or L<Event::Lib> 443work with inherently broken event loops such as L<Event> or L<Event::Lib>
446(and not with L<POE> currently, as POE does its own workaround with 444(and not with L<POE> currently). For those, you just have to suffer the
447one-second latency). For those, you just have to suffer the delays. 445delays.
448 446
449=head2 CHILD PROCESS WATCHERS 447=head2 CHILD PROCESS WATCHERS
450 448
451 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 449 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
452 450
… …
489 487
490Example: fork a process and wait for it 488Example: fork a process and wait for it
491 489
492 my $done = AnyEvent->condvar; 490 my $done = AnyEvent->condvar;
493 491
492 # this forks and immediately calls exit in the child. this
493 # normally has all sorts of bad consequences for your parent,
494 # so take this as an example only. always fork and exec,
495 # or call POSIX::_exit, in real code.
494 my $pid = fork or exit 5; 496 my $pid = fork or exit 5;
495 497
496 my $w = AnyEvent->child ( 498 my $w = AnyEvent->child (
497 pid => $pid, 499 pid => $pid,
498 cb => sub { 500 cb => sub {
… …
747This works because for every event source (EOF on file handle), there is 749This works because for every event source (EOF on file handle), there is
748one call to C<begin>, so the condvar waits for all calls to C<end> before 750one call to C<begin>, so the condvar waits for all calls to C<end> before
749sending. 751sending.
750 752
751The ping example mentioned above is slightly more complicated, as the 753The ping example mentioned above is slightly more complicated, as the
752there are results to be passwd back, and the number of tasks that are 754there are results to be passed back, and the number of tasks that are
753begun can potentially be zero: 755begun can potentially be zero:
754 756
755 my $cv = AnyEvent->condvar; 757 my $cv = AnyEvent->condvar;
756 758
757 my %result; 759 my %result;
… …
765 }; 767 };
766 } 768 }
767 769
768 $cv->end; 770 $cv->end;
769 771
772 ...
773
774 my $results = $cv->recv;
775
770This code fragment supposedly pings a number of hosts and calls 776This code fragment supposedly pings a number of hosts and calls
771C<send> after results for all then have have been gathered - in any 777C<send> after results for all then have have been gathered - in any
772order. To achieve this, the code issues a call to C<begin> when it starts 778order. To achieve this, the code issues a call to C<begin> when it starts
773each ping request and calls C<end> when it has received some result for 779each ping request and calls C<end> when it has received some result for
774it. Since C<begin> and C<end> only maintain a counter, the order in which 780it. Since C<begin> and C<end> only maintain a counter, the order in which
… …
809 815
810In list context, all parameters passed to C<send> will be returned, 816In list context, all parameters passed to C<send> will be returned,
811in scalar context only the first one will be returned. 817in scalar context only the first one will be returned.
812 818
813Note that doing a blocking wait in a callback is not supported by any 819Note that doing a blocking wait in a callback is not supported by any
814event loop, that is, recursive invocation of a blocking C<< ->recv 820event loop, that is, recursive invocation of a blocking C<< ->recv >> is
815>> is not allowed, and the C<recv> call will C<croak> if such a 821not allowed and the C<recv> call will C<croak> if such a condition is
816condition is detected. This condition can be slightly loosened by using 822detected. This requirement can be dropped by relying on L<Coro::AnyEvent>
817L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from 823, which allows you to do a blocking C<< ->recv >> from any thread
818any thread that doesn't run the event loop itself. 824that doesn't run the event loop itself. L<Coro::AnyEvent> is loaded
825automatically when L<Coro> is used with L<AnyEvent>, so code does not need
826to do anything special to take advantage of that: any code that would
827normally block your program because it calls C<recv>, be executed in an
828C<async> thread instead without blocking other threads.
819 829
820Not all event models support a blocking wait - some die in that case 830Not all event models support a blocking wait - some die in that case
821(programs might want to do that to stay interactive), so I<if you are 831(programs might want to do that to stay interactive), so I<if you are
822using this from a module, never require a blocking wait>. Instead, let the 832using this from a module, never require a blocking wait>. Instead, let the
823caller decide whether the call will block or not (for example, by coupling 833caller decide whether the call will block or not (for example, by coupling
… …
873create watchers. Nothing special needs to be done by the main program. 883create watchers. Nothing special needs to be done by the main program.
874 884
875 AnyEvent::Impl::Event based on Event, very stable, few glitches. 885 AnyEvent::Impl::Event based on Event, very stable, few glitches.
876 AnyEvent::Impl::Glib based on Glib, slow but very stable. 886 AnyEvent::Impl::Glib based on Glib, slow but very stable.
877 AnyEvent::Impl::Tk based on Tk, very broken. 887 AnyEvent::Impl::Tk based on Tk, very broken.
888 AnyEvent::Impl::UV based on UV, innovated square wheels.
878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 889 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
879 AnyEvent::Impl::POE based on POE, very slow, some limitations. 890 AnyEvent::Impl::POE based on POE, very slow, some limitations.
880 AnyEvent::Impl::Irssi used when running within irssi. 891 AnyEvent::Impl::Irssi used when running within irssi.
881 AnyEvent::Impl::IOAsync based on IO::Async. 892 AnyEvent::Impl::IOAsync based on IO::Async.
882 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 893 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
883 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 894 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
884 895
885=item Backends with special needs. 896=item Backends with special needs.
886 897
887Qt requires the Qt::Application to be instantiated first, but will 898Qt requires the Qt::Application to be instantiated first, but will
888otherwise be picked up automatically. As long as the main program 899otherwise be picked up automatically. As long as the main program
… …
933 944
934Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 945Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
935if necessary. You should only call this function right before you would 946if necessary. You should only call this function right before you would
936have created an AnyEvent watcher anyway, that is, as late as possible at 947have created an AnyEvent watcher anyway, that is, as late as possible at
937runtime, and not e.g. during initialisation of your module. 948runtime, and not e.g. during initialisation of your module.
949
950The effect of calling this function is as if a watcher had been created
951(specifically, actions that happen "when the first watcher is created"
952happen when calling detetc as well).
938 953
939If you need to do some initialisation before AnyEvent watchers are 954If you need to do some initialisation before AnyEvent watchers are
940created, use C<post_detect>. 955created, use C<post_detect>.
941 956
942=item $guard = AnyEvent::post_detect { BLOCK } 957=item $guard = AnyEvent::post_detect { BLOCK }
… …
1019To understand the usefulness of this function, consider a function that 1034To understand the usefulness of this function, consider a function that
1020asynchronously does something for you and returns some transaction 1035asynchronously does something for you and returns some transaction
1021object or guard to let you cancel the operation. For example, 1036object or guard to let you cancel the operation. For example,
1022C<AnyEvent::Socket::tcp_connect>: 1037C<AnyEvent::Socket::tcp_connect>:
1023 1038
1024 # start a conenction attempt unless one is active 1039 # start a connection attempt unless one is active
1025 $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub { 1040 $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub {
1026 delete $self->{connect_guard}; 1041 delete $self->{connect_guard};
1027 ... 1042 ...
1028 }; 1043 };
1029 1044
… …
1045It should use C<postpone>: 1060It should use C<postpone>:
1046 1061
1047 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later 1062 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1048 if $some_error_condition; 1063 if $some_error_condition;
1049 1064
1065=item AnyEvent::log $level, $msg[, @args]
1066
1067Log the given C<$msg> at the given C<$level>.
1068
1069If L<AnyEvent::Log> is not loaded then this function makes a simple test
1070to see whether the message will be logged. If the test succeeds it will
1071load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1072the L<AnyEvent::Log> documentation for details.
1073
1074If the test fails it will simply return. Right now this happens when a
1075numerical loglevel is used and it is larger than the level specified via
1076C<$ENV{PERL_ANYEVENT_VERBOSE}>.
1077
1078If you want to sprinkle loads of logging calls around your code, consider
1079creating a logger callback with the C<AnyEvent::Log::logger> function,
1080which can reduce typing, codesize and can reduce the logging overhead
1081enourmously.
1082
1050=back 1083=back
1051 1084
1052=head1 WHAT TO DO IN A MODULE 1085=head1 WHAT TO DO IN A MODULE
1053 1086
1054As a module author, you should C<use AnyEvent> and call AnyEvent methods 1087As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
1110 1143
1111 1144
1112=head1 OTHER MODULES 1145=head1 OTHER MODULES
1113 1146
1114The following is a non-exhaustive list of additional modules that use 1147The following is a non-exhaustive list of additional modules that use
1115AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1148AnyEvent as a client and can therefore be mixed easily with other
1116modules and other event loops in the same program. Some of the modules 1149AnyEvent modules and other event loops in the same program. Some of the
1117come as part of AnyEvent, the others are available via CPAN. 1150modules come as part of AnyEvent, the others are available via CPAN (see
1151L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1152a longer non-exhaustive list), and the list is heavily biased towards
1153modules of the AnyEvent author himself :)
1118 1154
1119=over 4 1155=over 4
1120 1156
1121=item L<AnyEvent::Util> 1157=item L<AnyEvent::Util> (part of the AnyEvent distribution)
1122 1158
1123Contains various utility functions that replace often-used blocking 1159Contains various utility functions that replace often-used blocking
1124functions such as C<inet_aton> with event/callback-based versions. 1160functions such as C<inet_aton> with event/callback-based versions.
1125 1161
1126=item L<AnyEvent::Socket> 1162=item L<AnyEvent::Socket> (part of the AnyEvent distribution)
1127 1163
1128Provides various utility functions for (internet protocol) sockets, 1164Provides various utility functions for (internet protocol) sockets,
1129addresses and name resolution. Also functions to create non-blocking tcp 1165addresses and name resolution. Also functions to create non-blocking tcp
1130connections or tcp servers, with IPv6 and SRV record support and more. 1166connections or tcp servers, with IPv6 and SRV record support and more.
1131 1167
1132=item L<AnyEvent::Handle> 1168=item L<AnyEvent::Handle> (part of the AnyEvent distribution)
1133 1169
1134Provide read and write buffers, manages watchers for reads and writes, 1170Provide read and write buffers, manages watchers for reads and writes,
1135supports raw and formatted I/O, I/O queued and fully transparent and 1171supports raw and formatted I/O, I/O queued and fully transparent and
1136non-blocking SSL/TLS (via L<AnyEvent::TLS>). 1172non-blocking SSL/TLS (via L<AnyEvent::TLS>).
1137 1173
1138=item L<AnyEvent::DNS> 1174=item L<AnyEvent::DNS> (part of the AnyEvent distribution)
1139 1175
1140Provides rich asynchronous DNS resolver capabilities. 1176Provides rich asynchronous DNS resolver capabilities.
1141 1177
1142=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP> 1178=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1143 1179
1144Implement event-based interfaces to the protocols of the same name (for 1180Implement event-based interfaces to the protocols of the same name (for
1145the curious, IGS is the International Go Server and FCP is the Freenet 1181the curious, IGS is the International Go Server and FCP is the Freenet
1146Client Protocol). 1182Client Protocol).
1147 1183
1148=item L<AnyEvent::Handle::UDP> 1184=item L<AnyEvent::AIO> (part of the AnyEvent distribution)
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=item L<AnyEvent::AIO>
1171 1185
1172Truly asynchronous (as opposed to non-blocking) I/O, should be in the 1186Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1173toolbox of every event programmer. AnyEvent::AIO transparently fuses 1187toolbox of every event programmer. AnyEvent::AIO transparently fuses
1174L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1188L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1175file I/O, and much more. 1189file I/O, and much more.
1176 1190
1191=item L<AnyEvent::Fork>, L<AnyEvent::Fork::RPC>, L<AnyEvent::Fork::Pool>, L<AnyEvent::Fork::Remote>
1192
1193These let you safely fork new subprocesses, either locally or
1194remotely (e.g.v ia ssh), using some RPC protocol or not, without
1195the limitations normally imposed by fork (AnyEvent works fine for
1196example). Dynamically-resized worker pools are obviously included as well.
1197
1198And they are quite tiny and fast as well - "abusing" L<AnyEvent::Fork>
1199just to exec external programs can easily beat using C<fork> and C<exec>
1200(or even C<system>) in most programs.
1201
1202=item L<AnyEvent::Filesys::Notify>
1203
1204AnyEvent is good for non-blocking stuff, but it can't detect file or
1205path changes (e.g. "watch this directory for new files", "watch this
1206file for changes"). The L<AnyEvent::Filesys::Notify> module promises to
1207do just that in a portbale fashion, supporting inotify on GNU/Linux and
1208some weird, without doubt broken, stuff on OS X to monitor files. It can
1209fall back to blocking scans at regular intervals transparently on other
1210platforms, so it's about as portable as it gets.
1211
1212(I haven't used it myself, but it seems the biggest problem with it is
1213it quite bad performance).
1214
1177=item L<AnyEvent::HTTPD> 1215=item L<AnyEvent::DBI>
1178 1216
1179A simple embedded webserver. 1217Executes L<DBI> requests asynchronously in a proxy process for you,
1218notifying you in an event-based way when the operation is finished.
1180 1219
1181=item L<AnyEvent::FastPing> 1220=item L<AnyEvent::FastPing>
1182 1221
1183The fastest ping in the west. 1222The fastest ping in the west.
1184 1223
1185=item L<Coro> 1224=item L<Coro>
1186 1225
1187Has special support for AnyEvent via L<Coro::AnyEvent>. 1226Has special support for AnyEvent via L<Coro::AnyEvent>, which allows you
1227to simply invert the flow control - don't call us, we will call you:
1228
1229 async {
1230 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1231 print "5 seconds later!\n";
1232
1233 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1234 my $line = <STDIN>; # works for ttys
1235
1236 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1237 my ($body, $hdr) = Coro::rouse_wait;
1238 };
1188 1239
1189=back 1240=back
1190 1241
1191=cut 1242=cut
1192 1243
1193package AnyEvent; 1244package AnyEvent;
1194
1195# basically a tuned-down version of common::sense
1196sub common_sense {
1197 # from common:.sense 3.4
1198 ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "\x3c\x3f\x33\x00\x0f\xf0\x0f\xc0\xf0\xfc\x33\x00";
1199 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1200 $^H |= 0x00000600;
1201}
1202
1203BEGIN { AnyEvent::common_sense }
1204
1205use Carp ();
1206
1207our $VERSION = '5.34';
1208our $MODEL;
1209
1210our @ISA;
1211
1212our @REGISTRY;
1213
1214our $VERBOSE;
1215 1245
1216BEGIN { 1246BEGIN {
1217 require "AnyEvent/constants.pl"; 1247 require "AnyEvent/constants.pl";
1248 &AnyEvent::common_sense;
1249}
1218 1250
1251use Carp ();
1252
1253our $VERSION = '7.08';
1254our $MODEL;
1255our @ISA;
1256our @REGISTRY;
1257our $VERBOSE;
1258our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1259our $MAX_SIGNAL_LATENCY = $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} || 10; # executes after the BEGIN block below (tainting!)
1260
1261BEGIN {
1219 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1262 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1220 1263
1221 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1264 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1222 if ${^TAINT}; 1265 if ${^TAINT};
1223 1266
1224 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1267 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1268 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1225 1269
1226} 1270 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1271 if ${^TAINT};
1227 1272
1228our $MAX_SIGNAL_LATENCY = 10; 1273 # $ENV{PERL_ANYEVENT_xxx} now valid
1229 1274
1230our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1275 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1231 1276
1232{
1233 my $idx; 1277 my $idx;
1234 $PROTOCOL{$_} = ++$idx 1278 $PROTOCOL{$_} = ++$idx
1235 for reverse split /\s*,\s*/, 1279 for reverse split /\s*,\s*/,
1236 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1280 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1237} 1281}
… …
1268 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec); 1312 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1269 1313
1270 () 1314 ()
1271} 1315}
1272 1316
1317sub log($$;@) {
1318 # only load the big bloated module when we actually are about to log something
1319 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1320 local ($!, $@);
1321 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1322 # AnyEvent::Log overwrites this function
1323 goto &log;
1324 }
1325
1326 0 # not logged
1327}
1328
1329sub _logger($;$) {
1330 my ($level, $renabled) = @_;
1331
1332 $$renabled = $level <= $VERBOSE;
1333
1334 my $logger = [(caller)[0], $level, $renabled];
1335
1336 $AnyEvent::Log::LOGGER{$logger+0} = $logger;
1337
1338# return unless defined wantarray;
1339#
1340# require AnyEvent::Util;
1341# my $guard = AnyEvent::Util::guard (sub {
1342# # "clean up"
1343# delete $LOGGER{$logger+0};
1344# });
1345#
1346# sub {
1347# return 0 unless $$renabled;
1348#
1349# $guard if 0; # keep guard alive, but don't cause runtime overhead
1350# require AnyEvent::Log unless $AnyEvent::Log::VERSION;
1351# package AnyEvent::Log;
1352# _log ($logger->[0], $level, @_) # logger->[0] has been converted at load time
1353# }
1354}
1355
1356if (length $ENV{PERL_ANYEVENT_LOG}) {
1357 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1358}
1359
1273our @models = ( 1360our @models = (
1274 [EV:: => AnyEvent::Impl::EV:: , 1], 1361 [EV:: => AnyEvent::Impl::EV::],
1275 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1362 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1276 # everything below here will not (normally) be autoprobed 1363 # everything below here will not (normally) be autoprobed
1277 # as the pure perl backend should work everywhere 1364 # as the pure perl backend should work everywhere
1278 # and is usually faster 1365 # and is usually faster
1366 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package, so msut be near the top
1279 [Event:: => AnyEvent::Impl::Event::, 1], 1367 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1280 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1368 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1369 # everything below here should not be autoloaded
1281 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1370 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1282 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1283 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1371 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1372 [UV:: => AnyEvent::Impl::UV::], # switched from libev, added back all bugs imaginable
1284 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1373 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1285 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1374 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1286 [Wx:: => AnyEvent::Impl::POE::], 1375 [Wx:: => AnyEvent::Impl::POE::],
1287 [Prima:: => AnyEvent::Impl::POE::], 1376 [Prima:: => AnyEvent::Impl::POE::],
1288 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1377 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1289 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1378 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1290 [FLTK:: => AnyEvent::Impl::FLTK2::], 1379 [FLTK:: => AnyEvent::Impl::FLTK::],
1291); 1380);
1381
1382our @isa_hook;
1383
1384sub _isa_set {
1385 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1386
1387 @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1388 for 1 .. $#pkg;
1389
1390 grep $_ && $_->[1], @isa_hook
1391 and AE::_reset ();
1392}
1393
1394# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1395sub _isa_hook($$;$) {
1396 my ($i, $pkg, $reset_ae) = @_;
1397
1398 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1399
1400 _isa_set;
1401}
1292 1402
1293# all autoloaded methods reserve the complete glob, not just the method slot. 1403# all autoloaded methods reserve the complete glob, not just the method slot.
1294# due to bugs in perls method cache implementation. 1404# due to bugs in perls method cache implementation.
1295our @methods = qw(io timer time now now_update signal child idle condvar); 1405our @methods = qw(io timer time now now_update signal child idle condvar);
1296 1406
1297sub detect() { 1407sub detect() {
1408 return $MODEL if $MODEL; # some programs keep references to detect
1409
1410 # IO::Async::Loop::AnyEvent is extremely evil, refuse to work with it
1411 # the author knows about the problems and what it does to AnyEvent as a whole
1412 # (and the ability of others to use AnyEvent), but simply wants to abuse AnyEvent
1413 # anyway.
1414 AnyEvent::log fatal => "IO::Async::Loop::AnyEvent detected - that module is broken by\n"
1415 . "design, abuses internals and breaks AnyEvent - will not continue."
1416 if exists $INC{"IO/Async/Loop/AnyEvent.pm"};
1417
1298 local $!; # for good measure 1418 local $!; # for good measure
1299 local $SIG{__DIE__}; # we use eval 1419 local $SIG{__DIE__}; # we use eval
1300 1420
1301 # free some memory 1421 # free some memory
1302 *detect = sub () { $MODEL }; 1422 *detect = sub () { $MODEL };
… …
1310 1430
1311 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1431 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1312 my $model = $1; 1432 my $model = $1;
1313 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1433 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1314 if (eval "require $model") { 1434 if (eval "require $model") {
1435 AnyEvent::log 7 => "Loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1315 $MODEL = $model; 1436 $MODEL = $model;
1316 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1317 } else { 1437 } else {
1318 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1438 AnyEvent::log 4 => "Unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1319 } 1439 }
1320 } 1440 }
1321 1441
1322 # check for already loaded models 1442 # check for already loaded models
1323 unless ($MODEL) { 1443 unless ($MODEL) {
1324 for (@REGISTRY, @models) { 1444 for (@REGISTRY, @models) {
1325 my ($package, $model) = @$_; 1445 my ($package, $model) = @$_;
1326 if (${"$package\::VERSION"} > 0) { 1446 if (${"$package\::VERSION"} > 0) {
1327 if (eval "require $model") { 1447 if (eval "require $model") {
1448 AnyEvent::log 7 => "Autodetected model '$model', using it.";
1328 $MODEL = $model; 1449 $MODEL = $model;
1329 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2; 1450 last;
1451 } else {
1452 AnyEvent::log 8 => "Detected event loop $package, but cannot load '$model', skipping: $@";
1453 }
1454 }
1455 }
1456
1457 unless ($MODEL) {
1458 # try to autoload a model
1459 for (@REGISTRY, @models) {
1460 my ($package, $model) = @$_;
1461 if (
1462 eval "require $package"
1463 and ${"$package\::VERSION"} > 0
1464 and eval "require $model"
1465 ) {
1466 AnyEvent::log 7 => "Autoloaded model '$model', using it.";
1467 $MODEL = $model;
1330 last; 1468 last;
1331 } 1469 }
1332 } 1470 }
1333 }
1334
1335 unless ($MODEL) {
1336 # try to autoload a model
1337 for (@REGISTRY, @models) {
1338 my ($package, $model, $autoload) = @$_;
1339 if (
1340 $autoload
1341 and eval "require $package"
1342 and ${"$package\::VERSION"} > 0
1343 and eval "require $model"
1344 ) {
1345 $MODEL = $model;
1346 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1347 last;
1348 }
1349 }
1350 1471
1351 $MODEL 1472 $MODEL
1352 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?\n"; 1473 or AnyEvent::log fatal => "Backend autodetection failed - did you properly install AnyEvent?";
1353 } 1474 }
1354 } 1475 }
1355 1476
1356 # free memory only needed for probing 1477 # free memory only needed for probing
1357 undef @models; 1478 undef @models;
1358 undef @REGISTRY; 1479 undef @REGISTRY;
1359 1480
1360 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1481 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1361 unshift @ISA, $MODEL;
1362 1482
1363 # now nuke some methods that are overridden by the backend. 1483 # now nuke some methods that are overridden by the backend.
1364 # SUPER usage is not allowed in these. 1484 # SUPER usage is not allowed in these.
1365 for (qw(time signal child idle)) { 1485 for (qw(time signal child idle)) {
1366 undef &{"AnyEvent::Base::$_"} 1486 undef &{"AnyEvent::Base::$_"}
1367 if defined &{"$MODEL\::$_"}; 1487 if defined &{"$MODEL\::$_"};
1368 } 1488 }
1369 1489
1490 _isa_set;
1491
1492 # we're officially open!
1493
1370 if ($ENV{PERL_ANYEVENT_STRICT}) { 1494 if ($ENV{PERL_ANYEVENT_STRICT}) {
1371 require AnyEvent::Strict; 1495 require AnyEvent::Strict;
1372 } 1496 }
1373 1497
1374 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1498 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1375 require AnyEvent::Debug; 1499 require AnyEvent::Debug;
1376 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1500 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1377 } 1501 }
1378 1502
1379 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1503 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1380 require AnyEvent::Socket; 1504 require AnyEvent::Socket;
1381 require AnyEvent::Debug; 1505 require AnyEvent::Debug;
1382 1506
1507 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1508 $shell =~ s/\$\$/$$/g;
1509
1383 my ($host, $service) = AnyEvent::Socket::parse_hostport ($ENV{PERL_ANYEVENT_DEBUG_SHELL}); 1510 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1384 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1511 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1385 } 1512 }
1513
1514 # now the anyevent environment is set up as the user told us to, so
1515 # call the actual user code - post detects
1386 1516
1387 (shift @post_detect)->() while @post_detect; 1517 (shift @post_detect)->() while @post_detect;
1388 undef @post_detect; 1518 undef @post_detect;
1389 1519
1390 *post_detect = sub(&) { 1520 *post_detect = sub(&) {
… …
1436package AE; 1566package AE;
1437 1567
1438our $VERSION = $AnyEvent::VERSION; 1568our $VERSION = $AnyEvent::VERSION;
1439 1569
1440sub _reset() { 1570sub _reset() {
1441 eval q{ 1571 eval q{
1442 # fall back to the main API by default - backends and AnyEvent::Base 1572 # fall back to the main API by default - backends and AnyEvent::Base
1443 # implementations can overwrite these. 1573 # implementations can overwrite these.
1444 1574
1445 sub io($$$) { 1575 sub io($$$) {
1446 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2]) 1576 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
… …
1477 sub time() { 1607 sub time() {
1478 AnyEvent->time 1608 AnyEvent->time
1479 } 1609 }
1480 1610
1481 *postpone = \&AnyEvent::postpone; 1611 *postpone = \&AnyEvent::postpone;
1612 *log = \&AnyEvent::log;
1482 }; 1613 };
1483 die if $@; 1614 die if $@;
1484} 1615}
1485 1616
1486BEGIN { _reset } 1617BEGIN { _reset }
… …
1491 1622
1492sub time { 1623sub time {
1493 eval q{ # poor man's autoloading {} 1624 eval q{ # poor man's autoloading {}
1494 # probe for availability of Time::HiRes 1625 # probe for availability of Time::HiRes
1495 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1626 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1496 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1627 *time = sub { Time::HiRes::time () };
1497 *AE::time = \&Time::HiRes::time; 1628 *AE::time = \& Time::HiRes::time ;
1629 *now = \&time;
1630 AnyEvent::log 8 => "using Time::HiRes for sub-second timing accuracy.";
1498 # if (eval "use POSIX (); (POSIX::times())... 1631 # if (eval "use POSIX (); (POSIX::times())...
1499 } else { 1632 } else {
1500 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1633 *time = sub { CORE::time };
1501 *AE::time = sub (){ time }; # epic fail 1634 *AE::time = sub (){ CORE::time };
1635 *now = \&time;
1636 AnyEvent::log 3 => "Using built-in time(), no sub-second resolution!";
1502 } 1637 }
1503
1504 *time = sub { AE::time }; # different prototypes
1505 }; 1638 };
1506 die if $@; 1639 die if $@;
1507 1640
1508 &time 1641 &time
1509} 1642}
1510 1643
1511*now = \&time; 1644*now = \&time;
1512
1513sub now_update { } 1645sub now_update { }
1514 1646
1515sub _poll { 1647sub _poll {
1516 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught"; 1648 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1517} 1649}
… …
1603 1735
1604sub signal { 1736sub signal {
1605 eval q{ # poor man's autoloading {} 1737 eval q{ # poor man's autoloading {}
1606 # probe for availability of Async::Interrupt 1738 # probe for availability of Async::Interrupt
1607 if (_have_async_interrupt) { 1739 if (_have_async_interrupt) {
1608 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1740 AnyEvent::log 8 => "Using Async::Interrupt for race-free signal handling.";
1609 1741
1610 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1742 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1611 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1743 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1612 1744
1613 } else { 1745 } else {
1614 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1746 AnyEvent::log 8 => "Using emulated perl signal handling with latency timer.";
1615 1747
1616 if (AnyEvent::WIN32) { 1748 if (AnyEvent::WIN32) {
1617 require AnyEvent::Util; 1749 require AnyEvent::Util;
1618 1750
1619 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1751 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1913$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2045$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1914so on. 2046so on.
1915 2047
1916=head1 ENVIRONMENT VARIABLES 2048=head1 ENVIRONMENT VARIABLES
1917 2049
1918The following environment variables are used by this module or its 2050AnyEvent supports a number of environment variables that tune the
1919submodules. 2051runtime behaviour. They are usually evaluated when AnyEvent is
2052loaded, initialised, or a submodule that uses them is loaded. Many of
2053them also cause AnyEvent to load additional modules - for example,
2054C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2055loaded.
1920 2056
1921Note that AnyEvent will remove I<all> environment variables starting with 2057All the environment variables documented here start with
1922C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2058C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1923enabled. 2059namespace. Other modules are encouraged (but by no means required) to use
2060C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2061namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2062be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2063variables starting with C<AE_>, see below).
2064
2065All variables can also be set via the C<AE_> prefix, that is, instead
2066of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2067case there is a clash btween anyevent and another program that uses
2068C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2069variable to the empty string, as those variables take precedence.
2070
2071When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2072to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2073exists. If taint mode is on, then AnyEvent will remove I<all> environment
2074variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2075with C<undef> or the empty string, if the corresaponding C<AE_> variable
2076is set).
2077
2078The exact algorithm is currently:
2079
2080 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2081 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2082 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2083
2084This ensures that child processes will not see the C<AE_> variables.
2085
2086The following environment variables are currently known to AnyEvent:
1924 2087
1925=over 4 2088=over 4
1926 2089
1927=item C<PERL_ANYEVENT_VERBOSE> 2090=item C<PERL_ANYEVENT_VERBOSE>
1928 2091
1929By default, AnyEvent will be completely silent except in fatal 2092By default, AnyEvent will log messages with loglevel C<4> (C<error>) or
1930conditions. You can set this environment variable to make AnyEvent more 2093higher (see L<AnyEvent::Log>). You can set this environment variable to a
1931talkative. 2094numerical loglevel to make AnyEvent more (or less) talkative.
1932 2095
2096If you want to do more than just set the global logging level
2097you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2098complex specifications.
2099
2100When set to C<0> (C<off>), then no messages whatsoever will be logged with
2101everything else at defaults.
2102
1933When set to C<1> or higher, causes AnyEvent to warn about unexpected 2103When set to C<5> or higher (C<warn>), AnyEvent warns about unexpected
1934conditions, such as not being able to load the event model specified by 2104conditions, such as not being able to load the event model specified by
1935C<PERL_ANYEVENT_MODEL>. 2105C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
2106is the minimum recommended level for use during development.
1936 2107
1937When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2108When set to C<7> or higher (info), AnyEvent reports which event model it
1938model it chooses. 2109chooses.
1939 2110
1940When set to C<8> or higher, then AnyEvent will report extra information on 2111When set to C<8> or higher (debug), then AnyEvent will report extra
1941which optional modules it loads and how it implements certain features. 2112information on which optional modules it loads and how it implements
2113certain features.
2114
2115=item C<PERL_ANYEVENT_LOG>
2116
2117Accepts rather complex logging specifications. For example, you could log
2118all C<debug> messages of some module to stderr, warnings and above to
2119stderr, and errors and above to syslog, with:
2120
2121 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2122
2123For the rather extensive details, see L<AnyEvent::Log>.
2124
2125This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2126so will take effect even before AnyEvent has initialised itself.
2127
2128Note that specifying this environment variable causes the L<AnyEvent::Log>
2129module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2130using the latter saves a few hundred kB of memory unless a module
2131explicitly needs the extra features of AnyEvent::Log.
1942 2132
1943=item C<PERL_ANYEVENT_STRICT> 2133=item C<PERL_ANYEVENT_STRICT>
1944 2134
1945AnyEvent does not do much argument checking by default, as thorough 2135AnyEvent does not do much argument checking by default, as thorough
1946argument checking is very costly. Setting this variable to a true value 2136argument checking is very costly. Setting this variable to a true value
… …
1955C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2145C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1956can be very useful, however. 2146can be very useful, however.
1957 2147
1958=item C<PERL_ANYEVENT_DEBUG_SHELL> 2148=item C<PERL_ANYEVENT_DEBUG_SHELL>
1959 2149
1960If this env variable is set, then its contents will be 2150If this env variable is nonempty, then its contents will be interpreted by
1961interpreted by C<AnyEvent::Socket::parse_hostport> and an 2151C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
1962C<AnyEvent::Debug::shell> is bound on that port. The shell object is saved 2152replacing every occurance of C<$$> by the process pid). The shell object
1963in C<$AnyEvent::Debug::SHELL>. 2153is saved in C<$AnyEvent::Debug::SHELL>.
2154
2155This happens when the first watcher is created.
1964 2156
1965For example, to bind a debug shell on a unix domain socket in 2157For example, to bind a debug shell on a unix domain socket in
1966F</tmp/debug.sock>, you could use this: 2158F<< /tmp/debug<pid>.sock >>, you could use this:
1967 2159
1968 PERL_ANYEVENT_DEBUG_SHELL=unix/:/tmp/debug.sock perlprog 2160 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2161 # connect with e.g.: socat readline /tmp/debug123.sock
2162
2163Or to bind to tcp port 4545 on localhost:
2164
2165 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
2166 # connect with e.g.: telnet localhost 4545
2167
2168Note that creating sockets in F</tmp> or on localhost is very unsafe on
2169multiuser systems.
1969 2170
1970=item C<PERL_ANYEVENT_DEBUG_WRAP> 2171=item C<PERL_ANYEVENT_DEBUG_WRAP>
1971 2172
1972Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for 2173Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
1973debugging purposes. See C<AnyEvent::Debug::wrap> for details. 2174debugging purposes. See C<AnyEvent::Debug::wrap> for details.
… …
1990For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you 2191For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
1991could start your program like this: 2192could start your program like this:
1992 2193
1993 PERL_ANYEVENT_MODEL=Perl perl ... 2194 PERL_ANYEVENT_MODEL=Perl perl ...
1994 2195
2196=item C<PERL_ANYEVENT_IO_MODEL>
2197
2198The current file I/O model - see L<AnyEvent::IO> for more info.
2199
2200At the moment, only C<Perl> (small, pure-perl, synchronous) and
2201C<IOAIO> (truly asynchronous) are supported. The default is C<IOAIO> if
2202L<AnyEvent::AIO> can be loaded, otherwise it is C<Perl>.
2203
1995=item C<PERL_ANYEVENT_PROTOCOLS> 2204=item C<PERL_ANYEVENT_PROTOCOLS>
1996 2205
1997Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences 2206Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1998for IPv4 or IPv6. The default is unspecified (and might change, or be the result 2207for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1999of auto probing). 2208of auto probing).
… …
2003used, and preference will be given to protocols mentioned earlier in the 2212used, and preference will be given to protocols mentioned earlier in the
2004list. 2213list.
2005 2214
2006This variable can effectively be used for denial-of-service attacks 2215This variable can effectively be used for denial-of-service attacks
2007against local programs (e.g. when setuid), although the impact is likely 2216against local programs (e.g. when setuid), although the impact is likely
2008small, as the program has to handle conenction and other failures anyways. 2217small, as the program has to handle connection and other failures anyways.
2009 2218
2010Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6, 2219Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
2011but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2220but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2012- only support IPv4, never try to resolve or contact IPv6 2221- only support IPv4, never try to resolve or contact IPv6
2013addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2222addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2014IPv6, but prefer IPv6 over IPv4. 2223IPv6, but prefer IPv6 over IPv4.
2015 2224
2225=item C<PERL_ANYEVENT_HOSTS>
2226
2227This variable, if specified, overrides the F</etc/hosts> file used by
2228L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2229from that file instead.
2230
2016=item C<PERL_ANYEVENT_EDNS0> 2231=item C<PERL_ANYEVENT_EDNS0>
2017 2232
2018Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2233Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
2019for DNS. This extension is generally useful to reduce DNS traffic, but 2234DNS. This extension is generally useful to reduce DNS traffic, especially
2020some (broken) firewalls drop such DNS packets, which is why it is off by 2235when DNSSEC is involved, but some (broken) firewalls drop such DNS
2021default. 2236packets, which is why it is off by default.
2022 2237
2023Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2238Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2024EDNS0 in its DNS requests. 2239EDNS0 in its DNS requests.
2025 2240
2026=item C<PERL_ANYEVENT_MAX_FORKS> 2241=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2032 2247
2033The default value for the C<max_outstanding> parameter for the default DNS 2248The default value for the C<max_outstanding> parameter for the default DNS
2034resolver - this is the maximum number of parallel DNS requests that are 2249resolver - this is the maximum number of parallel DNS requests that are
2035sent to the DNS server. 2250sent to the DNS server.
2036 2251
2252=item C<PERL_ANYEVENT_MAX_SIGNAL_LATENCY>
2253
2254Perl has inherently racy signal handling (you can basically choose between
2255losing signals and memory corruption) - pure perl event loops (including
2256C<AnyEvent::Loop>, when C<Async::Interrupt> isn't available) therefore
2257have to poll regularly to avoid losing signals.
2258
2259Some event loops are racy, but don't poll regularly, and some event loops
2260are written in C but are still racy. For those event loops, AnyEvent
2261installs a timer that regularly wakes up the event loop.
2262
2263By default, the interval for this timer is C<10> seconds, but you can
2264override this delay with this environment variable (or by setting
2265the C<$AnyEvent::MAX_SIGNAL_LATENCY> variable before creating signal
2266watchers).
2267
2268Lower values increase CPU (and energy) usage, higher values can introduce
2269long delays when reaping children or waiting for signals.
2270
2271The L<AnyEvent::Async> module, if available, will be used to avoid this
2272polling (with most event loops).
2273
2037=item C<PERL_ANYEVENT_RESOLV_CONF> 2274=item C<PERL_ANYEVENT_RESOLV_CONF>
2038 2275
2039The file to use instead of F</etc/resolv.conf> (or OS-specific 2276The absolute path to a F<resolv.conf>-style file to use instead of
2040configuration) in the default resolver. When set to the empty string, no 2277F</etc/resolv.conf> (or the OS-specific configuration) in the default
2041default config will be used. 2278resolver, or the empty string to select the default configuration.
2042 2279
2043=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2280=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2044 2281
2045When neither C<ca_file> nor C<ca_path> was specified during 2282When neither C<ca_file> nor C<ca_path> was specified during
2046L<AnyEvent::TLS> context creation, and either of these environment 2283L<AnyEvent::TLS> context creation, and either of these environment
2047variables exist, they will be used to specify CA certificate locations 2284variables are nonempty, they will be used to specify CA certificate
2048instead of a system-dependent default. 2285locations instead of a system-dependent default.
2049 2286
2050=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2287=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2051 2288
2052When these are set to C<1>, then the respective modules are not 2289When these are set to C<1>, then the respective modules are not
2053loaded. Mostly good for testing AnyEvent itself. 2290loaded. Mostly good for testing AnyEvent itself.
… …
2385(even when used without AnyEvent), but most event loops have acceptable 2622(even when used without AnyEvent), but most event loops have acceptable
2386performance with or without AnyEvent. 2623performance with or without AnyEvent.
2387 2624
2388=item * The overhead AnyEvent adds is usually much smaller than the overhead of 2625=item * The overhead AnyEvent adds is usually much smaller than the overhead of
2389the actual event loop, only with extremely fast event loops such as EV 2626the actual event loop, only with extremely fast event loops such as EV
2390adds AnyEvent significant overhead. 2627does AnyEvent add significant overhead.
2391 2628
2392=item * You should avoid POE like the plague if you want performance or 2629=item * You should avoid POE like the plague if you want performance or
2393reasonable memory usage. 2630reasonable memory usage.
2394 2631
2395=back 2632=back
… …
2697This module is part of perl since release 5.008. It will be used when the 2934This module is part of perl since release 5.008. It will be used when the
2698chosen event library does not come with a timing source of its own. The 2935chosen event library does not come with a timing source of its own. The
2699pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to 2936pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to
2700try to use a monotonic clock for timing stability. 2937try to use a monotonic clock for timing stability.
2701 2938
2939=item L<AnyEvent::AIO> (and L<IO::AIO>)
2940
2941The default implementation of L<AnyEvent::IO> is to do I/O synchronously,
2942stopping programs while they access the disk, which is fine for a lot of
2943programs.
2944
2945Installing AnyEvent::AIO (and its IO::AIO dependency) makes it switch to
2946a true asynchronous implementation, so event processing can continue even
2947while waiting for disk I/O.
2948
2702=back 2949=back
2703 2950
2704 2951
2705=head1 FORK 2952=head1 FORK
2706 2953
… …
2717usually happens when the first AnyEvent watcher is created, or the library 2964usually happens when the first AnyEvent watcher is created, or the library
2718is loaded). 2965is loaded).
2719 2966
2720If you have to fork, you must either do so I<before> creating your first 2967If you have to fork, you must either do so I<before> creating your first
2721watcher OR you must not use AnyEvent at all in the child OR you must do 2968watcher OR you must not use AnyEvent at all in the child OR you must do
2722something completely out of the scope of AnyEvent. 2969something completely out of the scope of AnyEvent (see below).
2723 2970
2724The problem of doing event processing in the parent I<and> the child 2971The problem of doing event processing in the parent I<and> the child
2725is much more complicated: even for backends that I<are> fork-aware or 2972is much more complicated: even for backends that I<are> fork-aware or
2726fork-safe, their behaviour is not usually what you want: fork clones all 2973fork-safe, their behaviour is not usually what you want: fork clones all
2727watchers, that means all timers, I/O watchers etc. are active in both 2974watchers, that means all timers, I/O watchers etc. are active in both
2728parent and child, which is almost never what you want. USing C<exec> 2975parent and child, which is almost never what you want. Using C<exec>
2729to start worker children from some kind of manage rprocess is usually 2976to start worker children from some kind of manage prrocess is usually
2730preferred, because it is much easier and cleaner, at the expense of having 2977preferred, because it is much easier and cleaner, at the expense of having
2731to have another binary. 2978to have another binary.
2979
2980In addition to logical problems with fork, there are also implementation
2981problems. For example, on POSIX systems, you cannot fork at all in Perl
2982code if a thread (I am talking of pthreads here) was ever created in the
2983process, and this is just the tip of the iceberg. In general, using fork
2984from Perl is difficult, and attempting to use fork without an exec to
2985implement some kind of parallel processing is almost certainly doomed.
2986
2987To safely fork and exec, you should use a module such as
2988L<Proc::FastSpawn> that let's you safely fork and exec new processes.
2989
2990If you want to do multiprocessing using processes, you can
2991look at the L<AnyEvent::Fork> module (and some related modules
2992such as L<AnyEvent::Fork::RPC>, L<AnyEvent::Fork::Pool> and
2993L<AnyEvent::Fork::Remote>). This module allows you to safely create
2994subprocesses without any limitations - you can use X11 toolkits or
2995AnyEvent in the children created by L<AnyEvent::Fork> safely and without
2996any special precautions.
2732 2997
2733 2998
2734=head1 SECURITY CONSIDERATIONS 2999=head1 SECURITY CONSIDERATIONS
2735 3000
2736AnyEvent can be forced to load any event model via 3001AnyEvent can be forced to load any event model via
… …
2770 3035
2771Tutorial/Introduction: L<AnyEvent::Intro>. 3036Tutorial/Introduction: L<AnyEvent::Intro>.
2772 3037
2773FAQ: L<AnyEvent::FAQ>. 3038FAQ: L<AnyEvent::FAQ>.
2774 3039
2775Utility functions: L<AnyEvent::Util>. 3040Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
3041(simply logging).
2776 3042
3043Development/Debugging: L<AnyEvent::Strict> (stricter checking),
3044L<AnyEvent::Debug> (interactive shell, watcher tracing).
3045
2777Event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>, L<Glib::EV>, 3046Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2778L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 3047L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
3048L<Qt>, L<POE>, L<FLTK>.
2779 3049
2780Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 3050Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2781L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 3051L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2782L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 3052L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2783L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 3053L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
3054L<AnyEvent::Impl::FLTK>.
2784 3055
2785Non-blocking file handles, sockets, TCP clients and 3056Non-blocking handles, pipes, stream sockets, TCP clients and
2786servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 3057servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
3058
3059Asynchronous File I/O: L<AnyEvent::IO>.
2787 3060
2788Asynchronous DNS: L<AnyEvent::DNS>. 3061Asynchronous DNS: L<AnyEvent::DNS>.
2789 3062
2790Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 3063Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
2791 3064
… …
2794 3067
2795 3068
2796=head1 AUTHOR 3069=head1 AUTHOR
2797 3070
2798 Marc Lehmann <schmorp@schmorp.de> 3071 Marc Lehmann <schmorp@schmorp.de>
2799 http://home.schmorp.de/ 3072 http://anyevent.schmorp.de
2800 3073
2801=cut 3074=cut
2802 3075
28031 30761
2804 3077

Diff Legend

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