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.240 by root, Fri Jul 17 14:57:03 2009 UTC vs.
Revision 1.253 by root, Tue Jul 21 06:00:47 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - events independent of event loop implementation
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 5EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
6event loops. 6event loops.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
… …
40=head1 INTRODUCTION/TUTORIAL 40=head1 INTRODUCTION/TUTORIAL
41 41
42This manpage is mainly a reference manual. If you are interested 42This manpage is mainly a reference manual. If you are interested
43in a tutorial or some gentle introduction, have a look at the 43in a tutorial or some gentle introduction, have a look at the
44L<AnyEvent::Intro> manpage. 44L<AnyEvent::Intro> manpage.
45
46=head1 SUPPORT
47
48There is a mailinglist for discussing all things AnyEvent, and an IRC
49channel, too.
50
51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
52Respository>, at L<http://anyevent.schmorp.de>, for more info.
45 53
46=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
47 55
48Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
49nowadays. So what is different about AnyEvent? 57nowadays. So what is different about AnyEvent?
… …
361invocation, and callback invocation will be synchronous. Synchronous means 369invocation, and callback invocation will be synchronous. Synchronous means
362that it might take a while until the signal gets handled by the process, 370that it might take a while until the signal gets handled by the process,
363but it is guaranteed not to interrupt any other callbacks. 371but it is guaranteed not to interrupt any other callbacks.
364 372
365The main advantage of using these watchers is that you can share a signal 373The main advantage of using these watchers is that you can share a signal
366between multiple watchers. 374between multiple watchers, and AnyEvent will ensure that signals will not
375interrupt your program at bad times.
367 376
368This watcher might use C<%SIG>, so programs overwriting those signals 377This watcher might use C<%SIG> (depending on the event loop used),
369directly will likely not work correctly. 378so programs overwriting those signals directly will likely not work
379correctly.
370 380
371Example: exit on SIGINT 381Example: exit on SIGINT
372 382
373 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 383 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
384
385=head3 Signal Races, Delays and Workarounds
386
387Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
388callbacks to signals in a generic way, which is a pity, as you cannot do
389race-free signal handling in perl. AnyEvent will try to do it's best, but
390in some cases, signals will be delayed. The maximum time a signal might
391be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
392seconds). This variable can be changed only before the first signal
393watcher is created, and should be left alone otherwise. Higher values
394will cause fewer spurious wake-ups, which is better for power and CPU
395saving. All these problems can be avoided by installing the optional
396L<Async::Interrupt> module. This will not work with inherently broken
397event loops such as L<Event> or L<Event::Lib> (and not with L<POE>
398currently, as POE does it's own workaround with one-second latency). With
399those, you just have to suffer the delays.
374 400
375=head2 CHILD PROCESS WATCHERS 401=head2 CHILD PROCESS WATCHERS
376 402
377You can also watch on a child process exit and catch its exit status. 403You can also watch on a child process exit and catch its exit status.
378 404
… …
403 429
404This means you cannot create a child watcher as the very first 430This means you cannot create a child watcher as the very first
405thing in an AnyEvent program, you I<have> to create at least one 431thing in an AnyEvent program, you I<have> to create at least one
406watcher before you C<fork> the child (alternatively, you can call 432watcher before you C<fork> the child (alternatively, you can call
407C<AnyEvent::detect>). 433C<AnyEvent::detect>).
434
435As most event loops do not support waiting for child events, they will be
436emulated by AnyEvent in most cases, in which the latency and race problems
437mentioned in the description of signal watchers apply.
408 438
409Example: fork a process and wait for it 439Example: fork a process and wait for it
410 440
411 my $done = AnyEvent->condvar; 441 my $done = AnyEvent->condvar;
412 442
… …
487Condition variables are similar to callbacks, except that you can 517Condition variables are similar to callbacks, except that you can
488optionally wait for them. They can also be called merge points - points 518optionally wait for them. They can also be called merge points - points
489in time where multiple outstanding events have been processed. And yet 519in time where multiple outstanding events have been processed. And yet
490another way to call them is transactions - each condition variable can be 520another way to call them is transactions - each condition variable can be
491used to represent a transaction, which finishes at some point and delivers 521used to represent a transaction, which finishes at some point and delivers
492a result. 522a result. And yet some people know them as "futures" - a promise to
523compute/deliver something that you can wait for.
493 524
494Condition variables are very useful to signal that something has finished, 525Condition variables are very useful to signal that something has finished,
495for example, if you write a module that does asynchronous http requests, 526for example, if you write a module that does asynchronous http requests,
496then a condition variable would be the ideal candidate to signal the 527then a condition variable would be the ideal candidate to signal the
497availability of results. The user can either act when the callback is 528availability of results. The user can either act when the callback is
… …
848event module detection too early, for example, L<AnyEvent::AIO> creates 879event module detection too early, for example, L<AnyEvent::AIO> creates
849and installs the global L<IO::AIO> watcher in a C<post_detect> block to 880and installs the global L<IO::AIO> watcher in a C<post_detect> block to
850avoid autodetecting the event module at load time. 881avoid autodetecting the event module at load time.
851 882
852If called in scalar or list context, then it creates and returns an object 883If called in scalar or list context, then it creates and returns an object
853that automatically removes the callback again when it is destroyed. See 884that automatically removes the callback again when it is destroyed (or
885C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
854L<Coro::BDB> for a case where this is useful. 886a case where this is useful.
887
888Example: Create a watcher for the IO::AIO module and store it in
889C<$WATCHER>. Only do so after the event loop is initialised, though.
890
891 our WATCHER;
892
893 my $guard = AnyEvent::post_detect {
894 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
895 };
896
897 # the ||= is important in case post_detect immediately runs the block,
898 # as to not clobber the newly-created watcher. assigning both watcher and
899 # post_detect guard to the same variable has the advantage of users being
900 # able to just C<undef $WATCHER> if the watcher causes them grief.
901
902 $WATCHER ||= $guard;
855 903
856=item @AnyEvent::post_detect 904=item @AnyEvent::post_detect
857 905
858If there are any code references in this array (you can C<push> to it 906If there are any code references in this array (you can C<push> to it
859before or after loading AnyEvent), then they will called directly after 907before or after loading AnyEvent), then they will called directly after
… …
1024 1072
1025=cut 1073=cut
1026 1074
1027package AnyEvent; 1075package AnyEvent;
1028 1076
1077# basically a tuned-down version of common::sense
1078sub common_sense {
1029no warnings; 1079 # no warnings
1080 ${^WARNING_BITS} ^= ${^WARNING_BITS};
1030use strict qw(vars subs); 1081 # use strict vars subs
1082 $^H |= 0x00000600;
1083}
1084
1085BEGIN { AnyEvent::common_sense }
1031 1086
1032use Carp (); 1087use Carp ();
1033 1088
1034our $VERSION = 4.83; 1089our $VERSION = 4.86;
1035our $MODEL; 1090our $MODEL;
1036 1091
1037our $AUTOLOAD; 1092our $AUTOLOAD;
1038our @ISA; 1093our @ISA;
1039 1094
1040our @REGISTRY; 1095our @REGISTRY;
1041 1096
1042our $WIN32; 1097our $WIN32;
1098
1099our $VERBOSE;
1043 1100
1044BEGIN { 1101BEGIN {
1045 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1102 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
1046 eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; 1103 eval "sub TAINT(){ " . (${^TAINT}*1) . " }";
1047 1104
1048 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1105 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1049 if ${^TAINT}; 1106 if ${^TAINT};
1050}
1051 1107
1052our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1108 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1109
1110}
1111
1112our $MAX_SIGNAL_LATENCY = 10;
1053 1113
1054our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1114our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1055 1115
1056{ 1116{
1057 my $idx; 1117 my $idx;
… …
1092 my ($cb) = @_; 1152 my ($cb) = @_;
1093 1153
1094 if ($MODEL) { 1154 if ($MODEL) {
1095 $cb->(); 1155 $cb->();
1096 1156
1097 1 1157 undef
1098 } else { 1158 } else {
1099 push @post_detect, $cb; 1159 push @post_detect, $cb;
1100 1160
1101 defined wantarray 1161 defined wantarray
1102 ? bless \$cb, "AnyEvent::Util::postdetect" 1162 ? bless \$cb, "AnyEvent::Util::postdetect"
… …
1108 @post_detect = grep $_ != ${$_[0]}, @post_detect; 1168 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1109} 1169}
1110 1170
1111sub detect() { 1171sub detect() {
1112 unless ($MODEL) { 1172 unless ($MODEL) {
1113 no strict 'refs';
1114 local $SIG{__DIE__}; 1173 local $SIG{__DIE__};
1115 1174
1116 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1175 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
1117 my $model = "AnyEvent::Impl::$1"; 1176 my $model = "AnyEvent::Impl::$1";
1118 if (eval "require $model") { 1177 if (eval "require $model") {
1119 $MODEL = $model; 1178 $MODEL = $model;
1120 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $verbose > 1; 1179 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1121 } else { 1180 } else {
1122 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $verbose; 1181 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
1123 } 1182 }
1124 } 1183 }
1125 1184
1126 # check for already loaded models 1185 # check for already loaded models
1127 unless ($MODEL) { 1186 unless ($MODEL) {
1128 for (@REGISTRY, @models) { 1187 for (@REGISTRY, @models) {
1129 my ($package, $model) = @$_; 1188 my ($package, $model) = @$_;
1130 if (${"$package\::VERSION"} > 0) { 1189 if (${"$package\::VERSION"} > 0) {
1131 if (eval "require $model") { 1190 if (eval "require $model") {
1132 $MODEL = $model; 1191 $MODEL = $model;
1133 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 1192 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1134 last; 1193 last;
1135 } 1194 }
1136 } 1195 }
1137 } 1196 }
1138 1197
… …
1143 my ($package, $model) = @$_; 1202 my ($package, $model) = @$_;
1144 if (eval "require $package" 1203 if (eval "require $package"
1145 and ${"$package\::VERSION"} > 0 1204 and ${"$package\::VERSION"} > 0
1146 and eval "require $model") { 1205 and eval "require $model") {
1147 $MODEL = $model; 1206 $MODEL = $model;
1148 warn "AnyEvent: autoprobed model '$model', using it.\n" if $verbose > 1; 1207 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2;
1149 last; 1208 last;
1150 } 1209 }
1151 } 1210 }
1152 1211
1153 $MODEL 1212 $MODEL
… …
1184# allow only one watcher per fd, so we dup it to get a different one). 1243# allow only one watcher per fd, so we dup it to get a different one).
1185sub _dupfh($$;$$) { 1244sub _dupfh($$;$$) {
1186 my ($poll, $fh, $r, $w) = @_; 1245 my ($poll, $fh, $r, $w) = @_;
1187 1246
1188 # cygwin requires the fh mode to be matching, unix doesn't 1247 # cygwin requires the fh mode to be matching, unix doesn't
1189 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">"); 1248 my ($rw, $mode) = $poll eq "r" ? ($r, "<&") : ($w, ">&");
1190 1249
1191 open my $fh2, "$mode&", $fh 1250 open my $fh2, $mode, $fh
1192 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,"; 1251 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1193 1252
1194 # we assume CLOEXEC is already set by perl in all important cases 1253 # we assume CLOEXEC is already set by perl in all important cases
1195 1254
1196 ($fh2, $rw) 1255 ($fh2, $rw)
… …
1198 1257
1199package AnyEvent::Base; 1258package AnyEvent::Base;
1200 1259
1201# default implementations for many methods 1260# default implementations for many methods
1202 1261
1203BEGIN { 1262sub _time {
1263 # probe for availability of Time::HiRes
1204 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1264 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1265 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1205 *_time = \&Time::HiRes::time; 1266 *_time = \&Time::HiRes::time;
1206 # if (eval "use POSIX (); (POSIX::times())... 1267 # if (eval "use POSIX (); (POSIX::times())...
1207 } else { 1268 } else {
1269 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1208 *_time = sub { time }; # epic fail 1270 *_time = sub { time }; # epic fail
1209 } 1271 }
1272
1273 &_time
1210} 1274}
1211 1275
1212sub time { _time } 1276sub time { _time }
1213sub now { _time } 1277sub now { _time }
1214sub now_update { } 1278sub now_update { }
… …
1219 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" 1283 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1220} 1284}
1221 1285
1222# default implementation for ->signal 1286# default implementation for ->signal
1223 1287
1288our $HAVE_ASYNC_INTERRUPT;
1224our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1289our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1290our (%SIG_ASY, %SIG_ASY_W);
1291our ($SIG_COUNT, $SIG_TW);
1225 1292
1226sub _signal_exec { 1293sub _signal_exec {
1294 $HAVE_ASYNC_INTERRUPT
1295 ? $SIGPIPE_R->drain
1227 sysread $SIGPIPE_R, my $dummy, 4; 1296 : sysread $SIGPIPE_R, my $dummy, 9;
1228 1297
1229 while (%SIG_EV) { 1298 while (%SIG_EV) {
1230 for (keys %SIG_EV) { 1299 for (keys %SIG_EV) {
1231 delete $SIG_EV{$_}; 1300 delete $SIG_EV{$_};
1232 $_->() for values %{ $SIG_CB{$_} || {} }; 1301 $_->() for values %{ $SIG_CB{$_} || {} };
1233 } 1302 }
1234 } 1303 }
1235} 1304}
1236 1305
1306# install a dumym wakeupw atcher to reduce signal catching latency
1307sub _sig_add() {
1308 unless ($SIG_COUNT++) {
1309 # try to align timer on a full-second boundary, if possible
1310 my $NOW = AnyEvent->now;
1311
1312 $SIG_TW = AnyEvent->timer (
1313 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1314 interval => $MAX_SIGNAL_LATENCY,
1315 cb => sub { }, # just for the PERL_ASYNC_CHECK
1316 );
1317 }
1318}
1319
1320sub _sig_del {
1321 undef $SIG_TW
1322 unless --$SIG_COUNT;
1323}
1324
1325sub _signal {
1326 my (undef, %arg) = @_;
1327
1328 my $signal = uc $arg{signal}
1329 or Carp::croak "required option 'signal' is missing";
1330
1331 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1332
1333 if ($HAVE_ASYNC_INTERRUPT) {
1334 # async::interrupt
1335
1336 $SIG_ASY{$signal} ||= do {
1337 my $asy = new Async::Interrupt
1338 cb => sub { undef $SIG_EV{$signal} },
1339 signal => $signal,
1340 pipe => [$SIGPIPE_R->filenos],
1341 ;
1342 $asy->pipe_autodrain (0);
1343
1344 $asy
1345 };
1346
1347 } else {
1348 # pure perl
1349
1350 $SIG{$signal} ||= sub {
1351 local $!;
1352 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1353 undef $SIG_EV{$signal};
1354 };
1355
1356 # can't do signal processing without introducing races in pure perl,
1357 # so limit the signal latency.
1358 _sig_add;
1359 }
1360
1361 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1362}
1363
1237sub signal { 1364sub signal {
1238 my (undef, %arg) = @_; 1365 # probe for availability of Async::Interrupt
1366 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 0.6 (); 1") {
1367 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1239 1368
1240 unless ($SIGPIPE_R) { 1369 $HAVE_ASYNC_INTERRUPT = 1;
1370 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1371 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1372
1373 } else {
1374 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1375
1241 require Fcntl; 1376 require Fcntl;
1242 1377
1243 if (AnyEvent::WIN32) { 1378 if (AnyEvent::WIN32) {
1244 require AnyEvent::Util; 1379 require AnyEvent::Util;
1245 1380
… …
1260 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1395 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1261 1396
1262 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1397 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1263 } 1398 }
1264 1399
1265 my $signal = uc $arg{signal} 1400 *signal = \&_signal;
1266 or Carp::croak "required option 'signal' is missing"; 1401 &signal
1267
1268 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1269 $SIG{$signal} ||= sub {
1270 local $!;
1271 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1272 undef $SIG_EV{$signal};
1273 };
1274
1275 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1276} 1402}
1277 1403
1278sub AnyEvent::Base::signal::DESTROY { 1404sub AnyEvent::Base::signal::DESTROY {
1279 my ($signal, $cb) = @{$_[0]}; 1405 my ($signal, $cb) = @{$_[0]};
1280 1406
1407 _sig_del;
1408
1281 delete $SIG_CB{$signal}{$cb}; 1409 delete $SIG_CB{$signal}{$cb};
1282 1410
1411 $HAVE_ASYNC_INTERRUPT
1412 ? delete $SIG_ASY{$signal}
1283 # delete doesn't work with older perls - they then 1413 : # delete doesn't work with older perls - they then
1284 # print weird messages, or just unconditionally exit 1414 # print weird messages, or just unconditionally exit
1285 # instead of getting the default action. 1415 # instead of getting the default action.
1416 undef $SIG{$signal}
1286 undef $SIG{$signal} unless keys %{ $SIG_CB{$signal} }; 1417 unless keys %{ $SIG_CB{$signal} };
1287} 1418}
1288 1419
1289# default implementation for ->child 1420# default implementation for ->child
1290 1421
1291our %PID_CB; 1422our %PID_CB;
… …
1293our $CHLD_DELAY_W; 1424our $CHLD_DELAY_W;
1294our $WNOHANG; 1425our $WNOHANG;
1295 1426
1296sub _sigchld { 1427sub _sigchld {
1297 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1428 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
1429 $_->($pid, $?)
1298 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 1430 for values %{ $PID_CB{$pid} || {} },
1299 (values %{ $PID_CB{0} || {} }); 1431 values %{ $PID_CB{0} || {} };
1300 } 1432 }
1301} 1433}
1302 1434
1303sub child { 1435sub child {
1304 my (undef, %arg) = @_; 1436 my (undef, %arg) = @_;
… …
1306 defined (my $pid = $arg{pid} + 0) 1438 defined (my $pid = $arg{pid} + 0)
1307 or Carp::croak "required option 'pid' is missing"; 1439 or Carp::croak "required option 'pid' is missing";
1308 1440
1309 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1441 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
1310 1442
1443 # WNOHANG is almost cetrainly 1 everywhere
1444 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1445 ? 1
1311 $WNOHANG ||= eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1446 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1312 1447
1313 unless ($CHLD_W) { 1448 unless ($CHLD_W) {
1314 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1449 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
1315 # child could be a zombie already, so make at least one round 1450 # child could be a zombie already, so make at least one round
1316 &_sigchld; 1451 &_sigchld;
… …
1368 1503
1369our @ISA = AnyEvent::CondVar::Base::; 1504our @ISA = AnyEvent::CondVar::Base::;
1370 1505
1371package AnyEvent::CondVar::Base; 1506package AnyEvent::CondVar::Base;
1372 1507
1373use overload 1508#use overload
1374 '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1509# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1375 fallback => 1; 1510# fallback => 1;
1511
1512# save 300+ kilobytes by dirtily hardcoding overloading
1513${"AnyEvent::CondVar::Base::OVERLOAD"}{dummy}++; # Register with magic by touching.
1514*{'AnyEvent::CondVar::Base::()'} = sub { }; # "Make it findable via fetchmethod."
1515*{'AnyEvent::CondVar::Base::(&{}'} = sub { my $self = shift; sub { $self->send (@_) } }; # &{}
1516${'AnyEvent::CondVar::Base::()'} = 1; # fallback
1376 1517
1377our $WAITING; 1518our $WAITING;
1378 1519
1379sub _send { 1520sub _send {
1380 # nop 1521 # nop
… …
1471C<PERL_ANYEVENT_MODEL>. 1612C<PERL_ANYEVENT_MODEL>.
1472 1613
1473When set to C<2> or higher, cause AnyEvent to report to STDERR which event 1614When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1474model it chooses. 1615model it chooses.
1475 1616
1617When set to C<8> or higher, then AnyEvent will report extra information on
1618which optional modules it loads and how it implements certain features.
1619
1476=item C<PERL_ANYEVENT_STRICT> 1620=item C<PERL_ANYEVENT_STRICT>
1477 1621
1478AnyEvent does not do much argument checking by default, as thorough 1622AnyEvent does not do much argument checking by default, as thorough
1479argument checking is very costly. Setting this variable to a true value 1623argument checking is very costly. Setting this variable to a true value
1480will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly 1624will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1481check the arguments passed to most method calls. If it finds any problems, 1625check the arguments passed to most method calls. If it finds any problems,
1482it will croak. 1626it will croak.
1483 1627
1484In other words, enables "strict" mode. 1628In other words, enables "strict" mode.
1485 1629
1486Unlike C<use strict>, it is definitely recommended to keep it off in 1630Unlike C<use strict> (or it's modern cousin, C<< use L<common::sense>
1487production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while 1631>>, it is definitely recommended to keep it off in production. Keeping
1488developing programs can be very useful, however. 1632C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1633can be very useful, however.
1489 1634
1490=item C<PERL_ANYEVENT_MODEL> 1635=item C<PERL_ANYEVENT_MODEL>
1491 1636
1492This can be used to specify the event model to be used by AnyEvent, before 1637This can be used to specify the event model to be used by AnyEvent, before
1493auto detection and -probing kicks in. It must be a string consisting 1638auto detection and -probing kicks in. It must be a string consisting
… …
1555 1700
1556When neither C<ca_file> nor C<ca_path> was specified during 1701When neither C<ca_file> nor C<ca_path> was specified during
1557L<AnyEvent::TLS> context creation, and either of these environment 1702L<AnyEvent::TLS> context creation, and either of these environment
1558variables exist, they will be used to specify CA certificate locations 1703variables exist, they will be used to specify CA certificate locations
1559instead of a system-dependent default. 1704instead of a system-dependent default.
1705
1706=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1707
1708When these are set to C<1>, then the respective modules are not
1709loaded. Mostly good for testing AnyEvent itself.
1560 1710
1561=back 1711=back
1562 1712
1563=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1713=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1564 1714
… …
2132 if $SIG{CHLD} eq 'IGNORE'; 2282 if $SIG{CHLD} eq 'IGNORE';
2133 2283
2134$SIG{PIPE} = sub { } 2284$SIG{PIPE} = sub { }
2135 unless defined $SIG{PIPE}; 2285 unless defined $SIG{PIPE};
2136 2286
2287=head1 RECOMMENDED/OPTIONAL MODULES
2288
2289One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2290it's built-in modules) are required to use it.
2291
2292That does not mean that AnyEvent won't take advantage of some additional
2293modules if they are installed.
2294
2295This section epxlains which additional modules will be used, and how they
2296affect AnyEvent's operetion.
2297
2298=over 4
2299
2300=item L<Async::Interrupt>
2301
2302This slightly arcane module is used to implement fast signal handling: To
2303my knowledge, there is no way to do completely race-free and quick
2304signal handling in pure perl. To ensure that signals still get
2305delivered, AnyEvent will start an interval timer to wake up perl (and
2306catch the signals) with some delay (default is 10 seconds, look for
2307C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2308
2309If this module is available, then it will be used to implement signal
2310catching, which means that signals will not be delayed, and the event loop
2311will not be interrupted regularly, which is more efficient (And good for
2312battery life on laptops).
2313
2314This affects not just the pure-perl event loop, but also other event loops
2315that have no signal handling on their own (e.g. Glib, Tk, Qt).
2316
2317Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2318and either employ their own workarounds (POE) or use AnyEvent's workaround
2319(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2320does nothing for those backends.
2321
2322=item L<EV>
2323
2324This module isn't really "optional", as it is simply one of the backend
2325event loops that AnyEvent can use. However, it is simply the best event
2326loop available in terms of features, speed and stability: It supports
2327the AnyEvent API optimally, implements all the watcher types in XS, does
2328automatic timer adjustments even when no monotonic clock is available,
2329can take avdantage of advanced kernel interfaces such as C<epoll> and
2330C<kqueue>, and is the fastest backend I<by far>. You can even embed
2331L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2332
2333=item L<Guard>
2334
2335The guard module, when used, will be used to implement
2336C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2337lot less memory), but otherwise doesn't affect guard operation much. It is
2338purely used for performance.
2339
2340=item L<JSON> and L<JSON::XS>
2341
2342This module is required when you want to read or write JSON data via
2343L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2344advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2345
2346In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2347installed.
2348
2349=item L<Net::SSLeay>
2350
2351Implementing TLS/SSL in Perl is certainly interesting, but not very
2352worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2353the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2354
2355=item L<Time::HiRes>
2356
2357This module is part of perl since release 5.008. It will be used when the
2358chosen event library does not come with a timing source on it's own. The
2359pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to
2360try to use a monotonic clock for timing stability.
2361
2362=back
2363
2364
2137=head1 FORK 2365=head1 FORK
2138 2366
2139Most event libraries are not fork-safe. The ones who are usually are 2367Most event libraries are not fork-safe. The ones who are usually are
2140because they rely on inefficient but fork-safe C<select> or C<poll> 2368because they rely on inefficient but fork-safe C<select> or C<poll>
2141calls. Only L<EV> is fully fork-aware. 2369calls. Only L<EV> is fully fork-aware.
2142 2370
2143If you have to fork, you must either do so I<before> creating your first 2371If you have to fork, you must either do so I<before> creating your first
2144watcher OR you must not use AnyEvent at all in the child. 2372watcher OR you must not use AnyEvent at all in the child OR you must do
2373something completely out of the scope of AnyEvent.
2145 2374
2146 2375
2147=head1 SECURITY CONSIDERATIONS 2376=head1 SECURITY CONSIDERATIONS
2148 2377
2149AnyEvent can be forced to load any event model via 2378AnyEvent can be forced to load any event model via

Diff Legend

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