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.299 by root, Tue Dec 1 17:53:48 2009 UTC vs.
Revision 1.316 by root, Mon Mar 15 18:51:30 2010 UTC

… …
503 503
504=head2 IDLE WATCHERS 504=head2 IDLE WATCHERS
505 505
506 $w = AnyEvent->idle (cb => <callback>); 506 $w = AnyEvent->idle (cb => <callback>);
507 507
508Sometimes there is a need to do something, but it is not so important 508Repeatedly invoke the callback after the process becomes idle, until
509to do it instantly, but only when there is nothing better to do. This 509either the watcher is destroyed or new events have been detected.
510"nothing better to do" is usually defined to be "no other events need
511attention by the event loop".
512 510
513Idle watchers ideally get invoked when the event loop has nothing 511Idle watchers are useful when there is a need to do something, but it
514better to do, just before it would block the process to wait for new 512is not so important (or wise) to do it instantly. The callback will be
515events. Instead of blocking, the idle watcher is invoked. 513invoked only when there is "nothing better to do", which is usually
514defined as "all outstanding events have been handled and no new events
515have been detected". That means that idle watchers ideally get invoked
516when the event loop has just polled for new events but none have been
517detected. Instead of blocking to wait for more events, the idle watchers
518will be invoked.
516 519
517Most event loops unfortunately do not really support idle watchers (only 520Unfortunately, most event loops do not really support idle watchers (only
518EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent 521EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
519will simply call the callback "from time to time". 522will simply call the callback "from time to time".
520 523
521Example: read lines from STDIN, but only process them when the 524Example: read lines from STDIN, but only process them when the
522program is otherwise idle: 525program is otherwise idle:
… …
966You should check C<$AnyEvent::MODEL> before adding to this array, though: 969You should check C<$AnyEvent::MODEL> before adding to this array, though:
967if it is defined then the event loop has already been detected, and the 970if it is defined then the event loop has already been detected, and the
968array will be ignored. 971array will be ignored.
969 972
970Best use C<AnyEvent::post_detect { BLOCK }> when your application allows 973Best use C<AnyEvent::post_detect { BLOCK }> when your application allows
971it,as it takes care of these details. 974it, as it takes care of these details.
972 975
973This variable is mainly useful for modules that can do something useful 976This variable is mainly useful for modules that can do something useful
974when AnyEvent is used and thus want to know when it is initialised, but do 977when AnyEvent is used and thus want to know when it is initialised, but do
975not need to even load it by default. This array provides the means to hook 978not need to even load it by default. This array provides the means to hook
976into AnyEvent passively, without loading it. 979into AnyEvent passively, without loading it.
980
981Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
982together, you could put this into Coro (this is the actual code used by
983Coro to accomplish this):
984
985 if (defined $AnyEvent::MODEL) {
986 # AnyEvent already initialised, so load Coro::AnyEvent
987 require Coro::AnyEvent;
988 } else {
989 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
990 # as soon as it is
991 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
992 }
977 993
978=back 994=back
979 995
980=head1 WHAT TO DO IN A MODULE 996=head1 WHAT TO DO IN A MODULE
981 997
… …
1131package AnyEvent; 1147package AnyEvent;
1132 1148
1133# basically a tuned-down version of common::sense 1149# basically a tuned-down version of common::sense
1134sub common_sense { 1150sub common_sense {
1135 # from common:.sense 1.0 1151 # from common:.sense 1.0
1136 ${^WARNING_BITS} = "\xfc\x3f\xf3\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x03"; 1152 ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x00";
1137 # use strict vars subs 1153 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1138 $^H |= 0x00000600; 1154 $^H |= 0x00000600;
1139} 1155}
1140 1156
1141BEGIN { AnyEvent::common_sense } 1157BEGIN { AnyEvent::common_sense }
1142 1158
1143use Carp (); 1159use Carp ();
1144 1160
1145our $VERSION = '5.21'; 1161our $VERSION = '5.251';
1146our $MODEL; 1162our $MODEL;
1147 1163
1148our $AUTOLOAD; 1164our $AUTOLOAD;
1149our @ISA; 1165our @ISA;
1150 1166
1151our @REGISTRY; 1167our @REGISTRY;
1152 1168
1153our $VERBOSE; 1169our $VERBOSE;
1154 1170
1155BEGIN { 1171BEGIN {
1156 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1172 require "AnyEvent/constants.pl";
1173
1157 eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; 1174 eval "sub TAINT (){" . (${^TAINT} *1) . "}";
1158 1175
1159 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1176 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1160 if ${^TAINT}; 1177 if ${^TAINT};
1161 1178
1162 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1179 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
… …
1223sub AnyEvent::Util::postdetect::DESTROY { 1240sub AnyEvent::Util::postdetect::DESTROY {
1224 @post_detect = grep $_ != ${$_[0]}, @post_detect; 1241 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1225} 1242}
1226 1243
1227sub detect() { 1244sub detect() {
1245 # free some memory
1246 *detect = sub () { $MODEL };
1247
1248 local $!; # for good measure
1249 local $SIG{__DIE__};
1250
1251 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
1252 my $model = "AnyEvent::Impl::$1";
1253 if (eval "require $model") {
1254 $MODEL = $model;
1255 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1256 } else {
1257 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
1258 }
1259 }
1260
1261 # check for already loaded models
1228 unless ($MODEL) { 1262 unless ($MODEL) {
1229 local $SIG{__DIE__}; 1263 for (@REGISTRY, @models) {
1230 1264 my ($package, $model) = @$_;
1231 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1265 if (${"$package\::VERSION"} > 0) {
1232 my $model = "AnyEvent::Impl::$1";
1233 if (eval "require $model") { 1266 if (eval "require $model") {
1234 $MODEL = $model; 1267 $MODEL = $model;
1235 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2; 1268 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1236 } else { 1269 last;
1237 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1270 }
1238 } 1271 }
1239 } 1272 }
1240 1273
1241 # check for already loaded models
1242 unless ($MODEL) { 1274 unless ($MODEL) {
1275 # try to autoload a model
1243 for (@REGISTRY, @models) { 1276 for (@REGISTRY, @models) {
1244 my ($package, $model) = @$_; 1277 my ($package, $model, $autoload) = @$_;
1278 if (
1279 $autoload
1280 and eval "require $package"
1245 if (${"$package\::VERSION"} > 0) { 1281 and ${"$package\::VERSION"} > 0
1246 if (eval "require $model") { 1282 and eval "require $model"
1283 ) {
1247 $MODEL = $model; 1284 $MODEL = $model;
1248 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2; 1285 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1249 last; 1286 last;
1250 }
1251 } 1287 }
1252 } 1288 }
1253 1289
1254 unless ($MODEL) {
1255 # try to autoload a model
1256 for (@REGISTRY, @models) {
1257 my ($package, $model, $autoload) = @$_;
1258 if (
1259 $autoload
1260 and eval "require $package"
1261 and ${"$package\::VERSION"} > 0
1262 and eval "require $model"
1263 ) {
1264 $MODEL = $model;
1265 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1266 last;
1267 }
1268 }
1269
1270 $MODEL 1290 $MODEL
1271 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n"; 1291 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n";
1272 }
1273 } 1292 }
1274
1275 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1276
1277 unshift @ISA, $MODEL;
1278
1279 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
1280
1281 (shift @post_detect)->() while @post_detect;
1282 } 1293 }
1294
1295 @models = (); # free probe data
1296
1297 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1298 unshift @ISA, $MODEL;
1299
1300 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
1301
1302 (shift @post_detect)->() while @post_detect;
1283 1303
1284 $MODEL 1304 $MODEL
1285} 1305}
1286 1306
1287sub AUTOLOAD { 1307sub AUTOLOAD {
1288 (my $func = $AUTOLOAD) =~ s/.*://; 1308 (my $func = $AUTOLOAD) =~ s/.*://;
1289 1309
1290 $method{$func} 1310 $method{$func}
1291 or Carp::croak "$func: not a valid method for AnyEvent objects"; 1311 or Carp::croak "$func: not a valid AnyEvent class method";
1292 1312
1293 detect unless $MODEL; 1313 detect;
1294 1314
1295 my $class = shift; 1315 my $class = shift;
1296 $class->$func (@_); 1316 $class->$func (@_);
1297} 1317}
1298 1318
… …
1366package AnyEvent::Base; 1386package AnyEvent::Base;
1367 1387
1368# default implementations for many methods 1388# default implementations for many methods
1369 1389
1370sub _time() { 1390sub _time() {
1391 eval q{ # poor man's autoloading
1371 # probe for availability of Time::HiRes 1392 # probe for availability of Time::HiRes
1372 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1393 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1373 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1394 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1374 *_time = \&Time::HiRes::time; 1395 *_time = \&Time::HiRes::time;
1375 # if (eval "use POSIX (); (POSIX::times())... 1396 # if (eval "use POSIX (); (POSIX::times())...
1376 } else { 1397 } else {
1377 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1398 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1378 *_time = sub { time }; # epic fail 1399 *_time = sub (){ time }; # epic fail
1400 }
1379 } 1401 };
1402 die if $@;
1380 1403
1381 &_time 1404 &_time
1382} 1405}
1383 1406
1384sub time { _time } 1407sub time { _time }
… …
1405 1428
1406our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1429our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1407our (%SIG_ASY, %SIG_ASY_W); 1430our (%SIG_ASY, %SIG_ASY_W);
1408our ($SIG_COUNT, $SIG_TW); 1431our ($SIG_COUNT, $SIG_TW);
1409 1432
1410sub _signal_exec {
1411 $HAVE_ASYNC_INTERRUPT
1412 ? $SIGPIPE_R->drain
1413 : sysread $SIGPIPE_R, (my $dummy), 9;
1414
1415 while (%SIG_EV) {
1416 for (keys %SIG_EV) {
1417 delete $SIG_EV{$_};
1418 $_->() for values %{ $SIG_CB{$_} || {} };
1419 }
1420 }
1421}
1422
1423# install a dummy wakeup watcher to reduce signal catching latency 1433# install a dummy wakeup watcher to reduce signal catching latency
1434# used by Impls
1424sub _sig_add() { 1435sub _sig_add() {
1425 unless ($SIG_COUNT++) { 1436 unless ($SIG_COUNT++) {
1426 # try to align timer on a full-second boundary, if possible 1437 # try to align timer on a full-second boundary, if possible
1427 my $NOW = AE::now; 1438 my $NOW = AE::now;
1428 1439
… …
1480 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1491 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1481 1492
1482 } else { 1493 } else {
1483 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1494 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1484 1495
1485 require Fcntl;
1486
1487 if (AnyEvent::WIN32) { 1496 if (AnyEvent::WIN32) {
1488 require AnyEvent::Util; 1497 require AnyEvent::Util;
1489 1498
1490 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1499 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1491 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R; 1500 AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
1492 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case 1501 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case
1493 } else { 1502 } else {
1494 pipe $SIGPIPE_R, $SIGPIPE_W; 1503 pipe $SIGPIPE_R, $SIGPIPE_W;
1495 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R; 1504 fcntl $SIGPIPE_R, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_R;
1496 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case 1505 fcntl $SIGPIPE_W, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_W; # just in case
1497 1506
1498 # not strictly required, as $^F is normally 2, but let's make sure... 1507 # not strictly required, as $^F is normally 2, but let's make sure...
1499 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC; 1508 fcntl $SIGPIPE_R, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1500 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC; 1509 fcntl $SIGPIPE_W, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC;
1501 } 1510 }
1502 1511
1503 $SIGPIPE_R 1512 $SIGPIPE_R
1504 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1513 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1505 1514
… …
1559 # print weird messages, or just unconditionally exit 1568 # print weird messages, or just unconditionally exit
1560 # instead of getting the default action. 1569 # instead of getting the default action.
1561 undef $SIG{$signal} 1570 undef $SIG{$signal}
1562 unless keys %{ $SIG_CB{$signal} }; 1571 unless keys %{ $SIG_CB{$signal} };
1563 }; 1572 };
1573
1574 *_signal_exec = sub {
1575 $HAVE_ASYNC_INTERRUPT
1576 ? $SIGPIPE_R->drain
1577 : sysread $SIGPIPE_R, (my $dummy), 9;
1578
1579 while (%SIG_EV) {
1580 for (keys %SIG_EV) {
1581 delete $SIG_EV{$_};
1582 $_->() for values %{ $SIG_CB{$_} || {} };
1583 }
1584 }
1585 };
1564 }; 1586 };
1565 die if $@; 1587 die if $@;
1588
1566 &signal 1589 &signal
1567} 1590}
1568 1591
1569# default implementation for ->child 1592# default implementation for ->child
1570 1593
1571our %PID_CB; 1594our %PID_CB;
1572our $CHLD_W; 1595our $CHLD_W;
1573our $CHLD_DELAY_W; 1596our $CHLD_DELAY_W;
1574our $WNOHANG; 1597our $WNOHANG;
1575 1598
1599# used by many Impl's
1576sub _emit_childstatus($$) { 1600sub _emit_childstatus($$) {
1577 my (undef, $rpid, $rstatus) = @_; 1601 my (undef, $rpid, $rstatus) = @_;
1578 1602
1579 $_->($rpid, $rstatus) 1603 $_->($rpid, $rstatus)
1580 for values %{ $PID_CB{$rpid} || {} }, 1604 for values %{ $PID_CB{$rpid} || {} },
1581 values %{ $PID_CB{0} || {} }; 1605 values %{ $PID_CB{0} || {} };
1582} 1606}
1583 1607
1584sub _sigchld {
1585 my $pid;
1586
1587 AnyEvent->_emit_childstatus ($pid, $?)
1588 while ($pid = waitpid -1, $WNOHANG) > 0;
1589}
1590
1591sub child { 1608sub child {
1609 eval q{ # poor man's autoloading {}
1610 *_sigchld = sub {
1611 my $pid;
1612
1613 AnyEvent->_emit_childstatus ($pid, $?)
1614 while ($pid = waitpid -1, $WNOHANG) > 0;
1615 };
1616
1617 *child = sub {
1592 my (undef, %arg) = @_; 1618 my (undef, %arg) = @_;
1593 1619
1594 defined (my $pid = $arg{pid} + 0) 1620 defined (my $pid = $arg{pid} + 0)
1595 or Carp::croak "required option 'pid' is missing"; 1621 or Carp::croak "required option 'pid' is missing";
1596 1622
1597 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1623 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
1598 1624
1599 # WNOHANG is almost cetrainly 1 everywhere 1625 # WNOHANG is almost cetrainly 1 everywhere
1600 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/ 1626 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1601 ? 1 1627 ? 1
1602 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1628 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1603 1629
1604 unless ($CHLD_W) { 1630 unless ($CHLD_W) {
1605 $CHLD_W = AE::signal CHLD => \&_sigchld; 1631 $CHLD_W = AE::signal CHLD => \&_sigchld;
1606 # child could be a zombie already, so make at least one round 1632 # child could be a zombie already, so make at least one round
1607 &_sigchld; 1633 &_sigchld;
1608 } 1634 }
1609 1635
1610 bless [$pid, $arg{cb}], "AnyEvent::Base::child" 1636 bless [$pid, $arg{cb}], "AnyEvent::Base::child"
1611} 1637 };
1612 1638
1613sub AnyEvent::Base::child::DESTROY { 1639 *AnyEvent::Base::child::DESTROY = sub {
1614 my ($pid, $cb) = @{$_[0]}; 1640 my ($pid, $cb) = @{$_[0]};
1615 1641
1616 delete $PID_CB{$pid}{$cb}; 1642 delete $PID_CB{$pid}{$cb};
1617 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1643 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1618 1644
1619 undef $CHLD_W unless keys %PID_CB; 1645 undef $CHLD_W unless keys %PID_CB;
1646 };
1647 };
1648 die if $@;
1649
1650 &child
1620} 1651}
1621 1652
1622# idle emulation is done by simply using a timer, regardless 1653# idle emulation is done by simply using a timer, regardless
1623# of whether the process is idle or not, and not letting 1654# of whether the process is idle or not, and not letting
1624# the callback use more than 50% of the time. 1655# the callback use more than 50% of the time.
1625sub idle { 1656sub idle {
1657 eval q{ # poor man's autoloading {}
1658 *idle = sub {
1626 my (undef, %arg) = @_; 1659 my (undef, %arg) = @_;
1627 1660
1628 my ($cb, $w, $rcb) = $arg{cb}; 1661 my ($cb, $w, $rcb) = $arg{cb};
1629 1662
1630 $rcb = sub { 1663 $rcb = sub {
1631 if ($cb) { 1664 if ($cb) {
1632 $w = _time; 1665 $w = _time;
1633 &$cb; 1666 &$cb;
1634 $w = _time - $w; 1667 $w = _time - $w;
1635 1668
1636 # never use more then 50% of the time for the idle watcher, 1669 # never use more then 50% of the time for the idle watcher,
1637 # within some limits 1670 # within some limits
1638 $w = 0.0001 if $w < 0.0001; 1671 $w = 0.0001 if $w < 0.0001;
1639 $w = 5 if $w > 5; 1672 $w = 5 if $w > 5;
1640 1673
1641 $w = AE::timer $w, 0, $rcb; 1674 $w = AE::timer $w, 0, $rcb;
1642 } else { 1675 } else {
1643 # clean up... 1676 # clean up...
1644 undef $w; 1677 undef $w;
1645 undef $rcb; 1678 undef $rcb;
1679 }
1680 };
1681
1682 $w = AE::timer 0.05, 0, $rcb;
1683
1684 bless \\$cb, "AnyEvent::Base::idle"
1646 } 1685 };
1686
1687 *AnyEvent::Base::idle::DESTROY = sub {
1688 undef $${$_[0]};
1689 };
1647 }; 1690 };
1691 die if $@;
1648 1692
1649 $w = AE::timer 0.05, 0, $rcb; 1693 &idle
1650
1651 bless \\$cb, "AnyEvent::Base::idle"
1652}
1653
1654sub AnyEvent::Base::idle::DESTROY {
1655 undef $${$_[0]};
1656} 1694}
1657 1695
1658package AnyEvent::CondVar; 1696package AnyEvent::CondVar;
1659 1697
1660our @ISA = AnyEvent::CondVar::Base::; 1698our @ISA = AnyEvent::CondVar::Base::;
… …
2448it's built-in modules) are required to use it. 2486it's built-in modules) are required to use it.
2449 2487
2450That does not mean that AnyEvent won't take advantage of some additional 2488That does not mean that AnyEvent won't take advantage of some additional
2451modules if they are installed. 2489modules if they are installed.
2452 2490
2453This section epxlains which additional modules will be used, and how they 2491This section explains which additional modules will be used, and how they
2454affect AnyEvent's operation. 2492affect AnyEvent's operation.
2455 2493
2456=over 4 2494=over 4
2457 2495
2458=item L<Async::Interrupt> 2496=item L<Async::Interrupt>
… …
2464catch the signals) with some delay (default is 10 seconds, look for 2502catch the signals) with some delay (default is 10 seconds, look for
2465C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2503C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2466 2504
2467If this module is available, then it will be used to implement signal 2505If this module is available, then it will be used to implement signal
2468catching, which means that signals will not be delayed, and the event loop 2506catching, which means that signals will not be delayed, and the event loop
2469will not be interrupted regularly, which is more efficient (And good for 2507will not be interrupted regularly, which is more efficient (and good for
2470battery life on laptops). 2508battery life on laptops).
2471 2509
2472This affects not just the pure-perl event loop, but also other event loops 2510This affects not just the pure-perl event loop, but also other event loops
2473that have no signal handling on their own (e.g. Glib, Tk, Qt). 2511that have no signal handling on their own (e.g. Glib, Tk, Qt).
2474 2512
… …
2486automatic timer adjustments even when no monotonic clock is available, 2524automatic timer adjustments even when no monotonic clock is available,
2487can take avdantage of advanced kernel interfaces such as C<epoll> and 2525can take avdantage of advanced kernel interfaces such as C<epoll> and
2488C<kqueue>, and is the fastest backend I<by far>. You can even embed 2526C<kqueue>, and is the fastest backend I<by far>. You can even embed
2489L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>). 2527L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2490 2528
2529If you only use backends that rely on another event loop (e.g. C<Tk>),
2530then this module will do nothing for you.
2531
2491=item L<Guard> 2532=item L<Guard>
2492 2533
2493The guard module, when used, will be used to implement 2534The guard module, when used, will be used to implement
2494C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a 2535C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2495lot less memory), but otherwise doesn't affect guard operation much. It is 2536lot less memory), but otherwise doesn't affect guard operation much. It is
2496purely used for performance. 2537purely used for performance.
2497 2538
2498=item L<JSON> and L<JSON::XS> 2539=item L<JSON> and L<JSON::XS>
2499 2540
2500One of these modules is required when you want to read or write JSON data 2541One of these modules is required when you want to read or write JSON data
2501via L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2542via L<AnyEvent::Handle>. L<JSON> is also written in pure-perl, but can take
2502advantage of the ultra-high-speed L<JSON::XS> module when it is installed. 2543advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2503
2504In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2505installed.
2506 2544
2507=item L<Net::SSLeay> 2545=item L<Net::SSLeay>
2508 2546
2509Implementing TLS/SSL in Perl is certainly interesting, but not very 2547Implementing TLS/SSL in Perl is certainly interesting, but not very
2510worthwhile: If this module is installed, then L<AnyEvent::Handle> (with 2548worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
… …
2521 2559
2522 2560
2523=head1 FORK 2561=head1 FORK
2524 2562
2525Most event libraries are not fork-safe. The ones who are usually are 2563Most event libraries are not fork-safe. The ones who are usually are
2526because they rely on inefficient but fork-safe C<select> or C<poll> 2564because they rely on inefficient but fork-safe C<select> or C<poll> calls
2527calls. Only L<EV> is fully fork-aware. 2565- higher performance APIs such as BSD's kqueue or the dreaded Linux epoll
2566are usually badly thought-out hacks that are incompatible with fork in
2567one way or another. Only L<EV> is fully fork-aware and ensures that you
2568continue event-processing in both parent and child (or both, if you know
2569what you are doing).
2570
2571This means that, in general, you cannot fork and do event processing in
2572the child if the event library was initialised before the fork (which
2573usually happens when the first AnyEvent watcher is created, or the library
2574is loaded).
2528 2575
2529If you have to fork, you must either do so I<before> creating your first 2576If you have to fork, you must either do so I<before> creating your first
2530watcher OR you must not use AnyEvent at all in the child OR you must do 2577watcher OR you must not use AnyEvent at all in the child OR you must do
2531something completely out of the scope of AnyEvent. 2578something completely out of the scope of AnyEvent.
2579
2580The problem of doing event processing in the parent I<and> the child
2581is much more complicated: even for backends that I<are> fork-aware or
2582fork-safe, their behaviour is not usually what you want: fork clones all
2583watchers, that means all timers, I/O watchers etc. are active in both
2584parent and child, which is almost never what you want. USing C<exec>
2585to start worker children from some kind of manage rprocess is usually
2586preferred, because it is much easier and cleaner, at the expense of having
2587to have another binary.
2532 2588
2533 2589
2534=head1 SECURITY CONSIDERATIONS 2590=head1 SECURITY CONSIDERATIONS
2535 2591
2536AnyEvent can be forced to load any event model via 2592AnyEvent can be forced to load any event model via

Diff Legend

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