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.241 by root, Fri Jul 17 18:08:35 2009 UTC vs.
Revision 1.249 by root, Mon Jul 20 06:00:42 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
… …
1024 1054
1025=cut 1055=cut
1026 1056
1027package AnyEvent; 1057package AnyEvent;
1028 1058
1059# basically a tuned-down version of common::sense
1060sub common_sense {
1029no warnings; 1061 # no warnings
1062 ${^WARNING_BITS} ^= ${^WARNING_BITS};
1030use strict qw(vars subs); 1063 # use strict vars subs
1064 $^H |= 0x00000600;
1065}
1066
1067BEGIN { AnyEvent::common_sense }
1031 1068
1032use Carp (); 1069use Carp ();
1033 1070
1034our $VERSION = 4.83; 1071our $VERSION = 4.85;
1035our $MODEL; 1072our $MODEL;
1036 1073
1037our $AUTOLOAD; 1074our $AUTOLOAD;
1038our @ISA; 1075our @ISA;
1039 1076
1040our @REGISTRY; 1077our @REGISTRY;
1041 1078
1042our $WIN32; 1079our $WIN32;
1080
1081our $VERBOSE;
1043 1082
1044BEGIN { 1083BEGIN {
1045 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1084 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
1046 eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; 1085 eval "sub TAINT(){ " . (${^TAINT}*1) . " }";
1047 1086
1048 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1087 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1049 if ${^TAINT}; 1088 if ${^TAINT};
1050}
1051 1089
1052our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1090 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1091
1092}
1093
1094our $MAX_SIGNAL_LATENCY = 10;
1053 1095
1054our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1096our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1055 1097
1056{ 1098{
1057 my $idx; 1099 my $idx;
… …
1108 @post_detect = grep $_ != ${$_[0]}, @post_detect; 1150 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1109} 1151}
1110 1152
1111sub detect() { 1153sub detect() {
1112 unless ($MODEL) { 1154 unless ($MODEL) {
1113 no strict 'refs';
1114 local $SIG{__DIE__}; 1155 local $SIG{__DIE__};
1115 1156
1116 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1157 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
1117 my $model = "AnyEvent::Impl::$1"; 1158 my $model = "AnyEvent::Impl::$1";
1118 if (eval "require $model") { 1159 if (eval "require $model") {
1119 $MODEL = $model; 1160 $MODEL = $model;
1120 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $verbose > 1; 1161 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1121 } else { 1162 } else {
1122 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $verbose; 1163 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
1123 } 1164 }
1124 } 1165 }
1125 1166
1126 # check for already loaded models 1167 # check for already loaded models
1127 unless ($MODEL) { 1168 unless ($MODEL) {
1128 for (@REGISTRY, @models) { 1169 for (@REGISTRY, @models) {
1129 my ($package, $model) = @$_; 1170 my ($package, $model) = @$_;
1130 if (${"$package\::VERSION"} > 0) { 1171 if (${"$package\::VERSION"} > 0) {
1131 if (eval "require $model") { 1172 if (eval "require $model") {
1132 $MODEL = $model; 1173 $MODEL = $model;
1133 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 1174 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1134 last; 1175 last;
1135 } 1176 }
1136 } 1177 }
1137 } 1178 }
1138 1179
… …
1143 my ($package, $model) = @$_; 1184 my ($package, $model) = @$_;
1144 if (eval "require $package" 1185 if (eval "require $package"
1145 and ${"$package\::VERSION"} > 0 1186 and ${"$package\::VERSION"} > 0
1146 and eval "require $model") { 1187 and eval "require $model") {
1147 $MODEL = $model; 1188 $MODEL = $model;
1148 warn "AnyEvent: autoprobed model '$model', using it.\n" if $verbose > 1; 1189 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2;
1149 last; 1190 last;
1150 } 1191 }
1151 } 1192 }
1152 1193
1153 $MODEL 1194 $MODEL
… …
1198 1239
1199package AnyEvent::Base; 1240package AnyEvent::Base;
1200 1241
1201# default implementations for many methods 1242# default implementations for many methods
1202 1243
1203BEGIN { 1244sub _time {
1245 # probe for availability of Time::HiRes
1204 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1246 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1247 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1205 *_time = \&Time::HiRes::time; 1248 *_time = \&Time::HiRes::time;
1206 # if (eval "use POSIX (); (POSIX::times())... 1249 # if (eval "use POSIX (); (POSIX::times())...
1207 } else { 1250 } else {
1251 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1208 *_time = sub { time }; # epic fail 1252 *_time = sub { time }; # epic fail
1209 } 1253 }
1254
1255 &_time
1210} 1256}
1211 1257
1212sub time { _time } 1258sub time { _time }
1213sub now { _time } 1259sub now { _time }
1214sub now_update { } 1260sub now_update { }
… …
1219 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" 1265 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1220} 1266}
1221 1267
1222# default implementation for ->signal 1268# default implementation for ->signal
1223 1269
1270our $HAVE_ASYNC_INTERRUPT;
1224our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1271our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1272our (%SIG_ASY, %SIG_ASY_W);
1273our ($SIG_COUNT, $SIG_TW);
1225 1274
1226sub _signal_exec { 1275sub _signal_exec {
1276 $HAVE_ASYNC_INTERRUPT
1277 ? $SIGPIPE_R->drain
1227 sysread $SIGPIPE_R, my $dummy, 4; 1278 : sysread $SIGPIPE_R, my $dummy, 9;
1228 1279
1229 while (%SIG_EV) { 1280 while (%SIG_EV) {
1230 for (keys %SIG_EV) { 1281 for (keys %SIG_EV) {
1231 delete $SIG_EV{$_}; 1282 delete $SIG_EV{$_};
1232 $_->() for values %{ $SIG_CB{$_} || {} }; 1283 $_->() for values %{ $SIG_CB{$_} || {} };
1233 } 1284 }
1234 } 1285 }
1235} 1286}
1236 1287
1288# install a dumym wakeupw atcher to reduce signal catching latency
1289sub _sig_add() {
1290 unless ($SIG_COUNT++) {
1291 # try to align timer on a full-second boundary, if possible
1292 my $NOW = AnyEvent->now;
1293
1294 $SIG_TW = AnyEvent->timer (
1295 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1296 interval => $MAX_SIGNAL_LATENCY,
1297 cb => sub { }, # just for the PERL_ASYNC_CHECK
1298 );
1299 }
1300}
1301
1302sub _sig_del {
1303 undef $SIG_TW
1304 unless --$SIG_COUNT;
1305}
1306
1307sub _signal {
1308 my (undef, %arg) = @_;
1309
1310 my $signal = uc $arg{signal}
1311 or Carp::croak "required option 'signal' is missing";
1312
1313 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1314
1315 if ($HAVE_ASYNC_INTERRUPT) {
1316 # async::interrupt
1317
1318 $SIG_ASY{$signal} ||= do {
1319 my $asy = new Async::Interrupt
1320 cb => sub { undef $SIG_EV{$signal} },
1321 signal => $signal,
1322 pipe => [$SIGPIPE_R->filenos],
1323 ;
1324 $asy->pipe_autodrain (0);
1325
1326 $asy
1327 };
1328
1329 } else {
1330 # pure perl
1331
1332 $SIG{$signal} ||= sub {
1333 local $!;
1334 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1335 undef $SIG_EV{$signal};
1336 };
1337
1338 # can't do signal processing without introducing races in pure perl,
1339 # so limit the signal latency.
1340 _sig_add;
1341 }
1342
1343 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1344}
1345
1237sub signal { 1346sub signal {
1238 my (undef, %arg) = @_; 1347 # probe for availability of Async::Interrupt
1348 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 0.6 (); 1") {
1349 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1239 1350
1240 unless ($SIGPIPE_R) { 1351 $HAVE_ASYNC_INTERRUPT = 1;
1352 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1353 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1354
1355 } else {
1356 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1357
1241 require Fcntl; 1358 require Fcntl;
1242 1359
1243 if (AnyEvent::WIN32) { 1360 if (AnyEvent::WIN32) {
1244 require AnyEvent::Util; 1361 require AnyEvent::Util;
1245 1362
… …
1260 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1377 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1261 1378
1262 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1379 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1263 } 1380 }
1264 1381
1265 my $signal = uc $arg{signal} 1382 *signal = \&_signal;
1266 or Carp::croak "required option 'signal' is missing"; 1383 &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} 1384}
1277 1385
1278sub AnyEvent::Base::signal::DESTROY { 1386sub AnyEvent::Base::signal::DESTROY {
1279 my ($signal, $cb) = @{$_[0]}; 1387 my ($signal, $cb) = @{$_[0]};
1280 1388
1389 _sig_del;
1390
1281 delete $SIG_CB{$signal}{$cb}; 1391 delete $SIG_CB{$signal}{$cb};
1282 1392
1393 $HAVE_ASYNC_INTERRUPT
1394 ? delete $SIG_ASY{$signal}
1283 # delete doesn't work with older perls - they then 1395 : # delete doesn't work with older perls - they then
1284 # print weird messages, or just unconditionally exit 1396 # print weird messages, or just unconditionally exit
1285 # instead of getting the default action. 1397 # instead of getting the default action.
1398 undef $SIG{$signal}
1286 undef $SIG{$signal} unless keys %{ $SIG_CB{$signal} }; 1399 unless keys %{ $SIG_CB{$signal} };
1287} 1400}
1288 1401
1289# default implementation for ->child 1402# default implementation for ->child
1290 1403
1291our %PID_CB; 1404our %PID_CB;
… …
1293our $CHLD_DELAY_W; 1406our $CHLD_DELAY_W;
1294our $WNOHANG; 1407our $WNOHANG;
1295 1408
1296sub _sigchld { 1409sub _sigchld {
1297 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1410 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
1411 $_->($pid, $?)
1298 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 1412 for values %{ $PID_CB{$pid} || {} },
1299 (values %{ $PID_CB{0} || {} }); 1413 values %{ $PID_CB{0} || {} };
1300 } 1414 }
1301} 1415}
1302 1416
1303sub child { 1417sub child {
1304 my (undef, %arg) = @_; 1418 my (undef, %arg) = @_;
… …
1306 defined (my $pid = $arg{pid} + 0) 1420 defined (my $pid = $arg{pid} + 0)
1307 or Carp::croak "required option 'pid' is missing"; 1421 or Carp::croak "required option 'pid' is missing";
1308 1422
1309 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1423 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
1310 1424
1425 # WNOHANG is almost cetrainly 1 everywhere
1426 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1427 ? 1
1311 $WNOHANG ||= eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1428 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1312 1429
1313 unless ($CHLD_W) { 1430 unless ($CHLD_W) {
1314 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1431 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
1315 # child could be a zombie already, so make at least one round 1432 # child could be a zombie already, so make at least one round
1316 &_sigchld; 1433 &_sigchld;
… …
1368 1485
1369our @ISA = AnyEvent::CondVar::Base::; 1486our @ISA = AnyEvent::CondVar::Base::;
1370 1487
1371package AnyEvent::CondVar::Base; 1488package AnyEvent::CondVar::Base;
1372 1489
1373use overload 1490#use overload
1374 '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1491# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1375 fallback => 1; 1492# fallback => 1;
1493
1494# save 300+ kilobytes by dirtily hardcoding overloading
1495${"AnyEvent::CondVar::Base::OVERLOAD"}{dummy}++; # Register with magic by touching.
1496*{'AnyEvent::CondVar::Base::()'} = sub { }; # "Make it findable via fetchmethod."
1497*{'AnyEvent::CondVar::Base::(&{}'} = sub { my $self = shift; sub { $self->send (@_) } }; # &{}
1498${'AnyEvent::CondVar::Base::()'} = 1; # fallback
1376 1499
1377our $WAITING; 1500our $WAITING;
1378 1501
1379sub _send { 1502sub _send {
1380 # nop 1503 # nop
… …
1471C<PERL_ANYEVENT_MODEL>. 1594C<PERL_ANYEVENT_MODEL>.
1472 1595
1473When set to C<2> or higher, cause AnyEvent to report to STDERR which event 1596When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1474model it chooses. 1597model it chooses.
1475 1598
1599When set to C<8> or higher, then AnyEvent will report extra information on
1600which optional modules it loads and how it implements certain features.
1601
1476=item C<PERL_ANYEVENT_STRICT> 1602=item C<PERL_ANYEVENT_STRICT>
1477 1603
1478AnyEvent does not do much argument checking by default, as thorough 1604AnyEvent does not do much argument checking by default, as thorough
1479argument checking is very costly. Setting this variable to a true value 1605argument checking is very costly. Setting this variable to a true value
1480will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly 1606will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1481check the arguments passed to most method calls. If it finds any problems, 1607check the arguments passed to most method calls. If it finds any problems,
1482it will croak. 1608it will croak.
1483 1609
1484In other words, enables "strict" mode. 1610In other words, enables "strict" mode.
1485 1611
1486Unlike C<use strict>, it is definitely recommended to keep it off in 1612Unlike C<use strict> (or it's modern cousin, C<< use L<common::sense>
1487production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while 1613>>, it is definitely recommended to keep it off in production. Keeping
1488developing programs can be very useful, however. 1614C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1615can be very useful, however.
1489 1616
1490=item C<PERL_ANYEVENT_MODEL> 1617=item C<PERL_ANYEVENT_MODEL>
1491 1618
1492This can be used to specify the event model to be used by AnyEvent, before 1619This 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 1620auto detection and -probing kicks in. It must be a string consisting
… …
1555 1682
1556When neither C<ca_file> nor C<ca_path> was specified during 1683When neither C<ca_file> nor C<ca_path> was specified during
1557L<AnyEvent::TLS> context creation, and either of these environment 1684L<AnyEvent::TLS> context creation, and either of these environment
1558variables exist, they will be used to specify CA certificate locations 1685variables exist, they will be used to specify CA certificate locations
1559instead of a system-dependent default. 1686instead of a system-dependent default.
1687
1688=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1689
1690When these are set to C<1>, then the respective modules are not
1691loaded. Mostly good for testing AnyEvent itself.
1560 1692
1561=back 1693=back
1562 1694
1563=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1695=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1564 1696
… …
2132 if $SIG{CHLD} eq 'IGNORE'; 2264 if $SIG{CHLD} eq 'IGNORE';
2133 2265
2134$SIG{PIPE} = sub { } 2266$SIG{PIPE} = sub { }
2135 unless defined $SIG{PIPE}; 2267 unless defined $SIG{PIPE};
2136 2268
2269=head1 RECOMMENDED/OPTIONAL MODULES
2270
2271One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2272it's built-in modules) are required to use it.
2273
2274That does not mean that AnyEvent won't take advantage of some additional
2275modules if they are installed.
2276
2277This section epxlains which additional modules will be used, and how they
2278affect AnyEvent's operetion.
2279
2280=over 4
2281
2282=item L<Async::Interrupt>
2283
2284This slightly arcane module is used to implement fast signal handling: To
2285my knowledge, there is no way to do completely race-free and quick
2286signal handling in pure perl. To ensure that signals still get
2287delivered, AnyEvent will start an interval timer to wake up perl (and
2288catch the signals) with some delay (default is 10 seconds, look for
2289C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2290
2291If this module is available, then it will be used to implement signal
2292catching, which means that signals will not be delayed, and the event loop
2293will not be interrupted regularly, which is more efficient (And good for
2294battery life on laptops).
2295
2296This affects not just the pure-perl event loop, but also other event loops
2297that have no signal handling on their own (e.g. Glib, Tk, Qt).
2298
2299Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2300and either employ their own workarounds (POE) or use AnyEvent's workaround
2301(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2302does nothing for those backends.
2303
2304=item L<EV>
2305
2306This module isn't really "optional", as it is simply one of the backend
2307event loops that AnyEvent can use. However, it is simply the best event
2308loop available in terms of features, speed and stability: It supports
2309the AnyEvent API optimally, implements all the watcher types in XS, does
2310automatic timer adjustments even when no monotonic clock is available,
2311can take avdantage of advanced kernel interfaces such as C<epoll> and
2312C<kqueue>, and is the fastest backend I<by far>. You can even embed
2313L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2314
2315=item L<Guard>
2316
2317The guard module, when used, will be used to implement
2318C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2319lot less memory), but otherwise doesn't affect guard operation much. It is
2320purely used for performance.
2321
2322=item L<JSON> and L<JSON::XS>
2323
2324This module is required when you want to read or write JSON data via
2325L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2326advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2327
2328In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2329installed.
2330
2331=item L<Net::SSLeay>
2332
2333Implementing TLS/SSL in Perl is certainly interesting, but not very
2334worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2335the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2336
2337=item L<Time::HiRes>
2338
2339This module is part of perl since release 5.008. It will be used when the
2340chosen event library does not come with a timing source on it's own. The
2341pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to
2342try to use a monotonic clock for timing stability.
2343
2344=back
2345
2346
2137=head1 FORK 2347=head1 FORK
2138 2348
2139Most event libraries are not fork-safe. The ones who are usually are 2349Most 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> 2350because they rely on inefficient but fork-safe C<select> or C<poll>
2141calls. Only L<EV> is fully fork-aware. 2351calls. Only L<EV> is fully fork-aware.
2142 2352
2143If you have to fork, you must either do so I<before> creating your first 2353If 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. 2354watcher OR you must not use AnyEvent at all in the child OR you must do
2355something completely out of the scope of AnyEvent.
2145 2356
2146 2357
2147=head1 SECURITY CONSIDERATIONS 2358=head1 SECURITY CONSIDERATIONS
2148 2359
2149AnyEvent can be forced to load any event model via 2360AnyEvent can be forced to load any event model via

Diff Legend

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