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.249 by root, Mon Jul 20 06:00:42 2009 UTC vs.
Revision 1.255 by root, Fri Jul 24 23:45:54 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - events independent of event loop implementation 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, Irssi, IO::Async, Qt and POE are
6event loops. 6various supported event loops/environments.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
… …
47 47
48There is a mailinglist for discussing all things AnyEvent, and an IRC 48There is a mailinglist for discussing all things AnyEvent, and an IRC
49channel, too. 49channel, too.
50 50
51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software 51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
52Respository>, at L<http://anyevent.schmorp.de>, for more info. 52Repository>, at L<http://anyevent.schmorp.de>, for more info.
53 53
54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
55 55
56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
57nowadays. So what is different about AnyEvent? 57nowadays. So what is different about AnyEvent?
… …
400 400
401=head2 CHILD PROCESS WATCHERS 401=head2 CHILD PROCESS WATCHERS
402 402
403You 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.
404 404
405The child process is specified by the C<pid> argument (if set to C<0>, it 405The child process is specified by the C<pid> argument (one some backends,
406watches for any child process exit). The watcher will triggered only when 406using C<0> watches for any child process exit, on others this will
407the child process has finished and an exit status is available, not on 407croak). The watcher will be triggered only when the child process has
408any trace events (stopped/continued). 408finished and an exit status is available, not on any trace events
409(stopped/continued).
409 410
410The callback will be called with the pid and exit status (as returned by 411The callback will be called with the pid and exit status (as returned by
411waitpid), so unlike other watcher types, you I<can> rely on child watcher 412waitpid), so unlike other watcher types, you I<can> rely on child watcher
412callback arguments. 413callback arguments.
413 414
… …
517Condition variables are similar to callbacks, except that you can 518Condition variables are similar to callbacks, except that you can
518optionally wait for them. They can also be called merge points - points 519optionally wait for them. They can also be called merge points - points
519in time where multiple outstanding events have been processed. And yet 520in time where multiple outstanding events have been processed. And yet
520another way to call them is transactions - each condition variable can be 521another way to call them is transactions - each condition variable can be
521used to represent a transaction, which finishes at some point and delivers 522used to represent a transaction, which finishes at some point and delivers
522a result. 523a result. And yet some people know them as "futures" - a promise to
524compute/deliver something that you can wait for.
523 525
524Condition variables are very useful to signal that something has finished, 526Condition variables are very useful to signal that something has finished,
525for example, if you write a module that does asynchronous http requests, 527for example, if you write a module that does asynchronous http requests,
526then a condition variable would be the ideal candidate to signal the 528then a condition variable would be the ideal candidate to signal the
527availability of results. The user can either act when the callback is 529availability of results. The user can either act when the callback is
… …
795 797
796 AnyEvent::Impl::Glib based on Glib, slow but very stable. 798 AnyEvent::Impl::Glib based on Glib, slow but very stable.
797 AnyEvent::Impl::Tk based on Tk, very broken. 799 AnyEvent::Impl::Tk based on Tk, very broken.
798 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 800 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
799 AnyEvent::Impl::POE based on POE, very slow, some limitations. 801 AnyEvent::Impl::POE based on POE, very slow, some limitations.
802 AnyEvent::Impl::Irssi used when running within irssi.
800 803
801=item Backends with special needs. 804=item Backends with special needs.
802 805
803Qt requires the Qt::Application to be instantiated first, but will 806Qt requires the Qt::Application to be instantiated first, but will
804otherwise be picked up automatically. As long as the main program 807otherwise be picked up automatically. As long as the main program
… …
878event module detection too early, for example, L<AnyEvent::AIO> creates 881event module detection too early, for example, L<AnyEvent::AIO> creates
879and installs the global L<IO::AIO> watcher in a C<post_detect> block to 882and installs the global L<IO::AIO> watcher in a C<post_detect> block to
880avoid autodetecting the event module at load time. 883avoid autodetecting the event module at load time.
881 884
882If called in scalar or list context, then it creates and returns an object 885If called in scalar or list context, then it creates and returns an object
883that automatically removes the callback again when it is destroyed. See 886that automatically removes the callback again when it is destroyed (or
887C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
884L<Coro::BDB> for a case where this is useful. 888a case where this is useful.
889
890Example: Create a watcher for the IO::AIO module and store it in
891C<$WATCHER>. Only do so after the event loop is initialised, though.
892
893 our WATCHER;
894
895 my $guard = AnyEvent::post_detect {
896 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
897 };
898
899 # the ||= is important in case post_detect immediately runs the block,
900 # as to not clobber the newly-created watcher. assigning both watcher and
901 # post_detect guard to the same variable has the advantage of users being
902 # able to just C<undef $WATCHER> if the watcher causes them grief.
903
904 $WATCHER ||= $guard;
885 905
886=item @AnyEvent::post_detect 906=item @AnyEvent::post_detect
887 907
888If there are any code references in this array (you can C<push> to it 908If there are any code references in this array (you can C<push> to it
889before or after loading AnyEvent), then they will called directly after 909before or after loading AnyEvent), then they will called directly after
… …
1066 1086
1067BEGIN { AnyEvent::common_sense } 1087BEGIN { AnyEvent::common_sense }
1068 1088
1069use Carp (); 1089use Carp ();
1070 1090
1071our $VERSION = 4.85; 1091our $VERSION = 4.86;
1072our $MODEL; 1092our $MODEL;
1073 1093
1074our $AUTOLOAD; 1094our $AUTOLOAD;
1075our @ISA; 1095our @ISA;
1076 1096
… …
1101 for reverse split /\s*,\s*/, 1121 for reverse split /\s*,\s*/,
1102 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1122 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1103} 1123}
1104 1124
1105my @models = ( 1125my @models = (
1106 [EV:: => AnyEvent::Impl::EV::], 1126 [EV:: => AnyEvent::Impl::EV:: , 1],
1107 [Event:: => AnyEvent::Impl::Event::], 1127 [Event:: => AnyEvent::Impl::Event::, 1],
1108 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1128 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1109 # everything below here will not be autoprobed 1129 # everything below here will not (normally) be autoprobed
1110 # as the pureperl backend should work everywhere 1130 # as the pureperl backend should work everywhere
1111 # and is usually faster 1131 # and is usually faster
1112 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1132 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1113 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1133 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1134 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1114 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1135 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1115 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1136 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1116 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1137 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1117 [Wx:: => AnyEvent::Impl::POE::], 1138 [Wx:: => AnyEvent::Impl::POE::],
1118 [Prima:: => AnyEvent::Impl::POE::], 1139 [Prima:: => AnyEvent::Impl::POE::],
1119 # IO::Async is just too broken - we would need workarounds for its 1140 # IO::Async is just too broken - we would need workarounds for its
1120 # byzantine signal and broken child handling, among others. 1141 # byzantine signal and broken child handling, among others.
1121 # IO::Async is rather hard to detect, as it doesn't have any 1142 # IO::Async is rather hard to detect, as it doesn't have any
1122 # obvious default class. 1143 # obvious default class.
1123# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1144# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1124# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1145# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1125# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1146# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1126); 1147);
1127 1148
1128our %method = map +($_ => 1), 1149our %method = map +($_ => 1),
1129 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1150 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
1130 1151
… …
1134 my ($cb) = @_; 1155 my ($cb) = @_;
1135 1156
1136 if ($MODEL) { 1157 if ($MODEL) {
1137 $cb->(); 1158 $cb->();
1138 1159
1139 1 1160 undef
1140 } else { 1161 } else {
1141 push @post_detect, $cb; 1162 push @post_detect, $cb;
1142 1163
1143 defined wantarray 1164 defined wantarray
1144 ? bless \$cb, "AnyEvent::Util::postdetect" 1165 ? bless \$cb, "AnyEvent::Util::postdetect"
… …
1176 } 1197 }
1177 } 1198 }
1178 } 1199 }
1179 1200
1180 unless ($MODEL) { 1201 unless ($MODEL) {
1181 # try to load a model 1202 # try to autoload a model
1182
1183 for (@REGISTRY, @models) { 1203 for (@REGISTRY, @models) {
1184 my ($package, $model) = @$_; 1204 my ($package, $model, $autoload) = @$_;
1205 if (
1206 $autoload
1185 if (eval "require $package" 1207 and eval "require $package"
1186 and ${"$package\::VERSION"} > 0 1208 and ${"$package\::VERSION"} > 0
1187 and eval "require $model") { 1209 and eval "require $model"
1210 ) {
1188 $MODEL = $model; 1211 $MODEL = $model;
1189 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2; 1212 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1190 last; 1213 last;
1191 } 1214 }
1192 } 1215 }
1193 1216
1194 $MODEL 1217 $MODEL
… …
1404our %PID_CB; 1427our %PID_CB;
1405our $CHLD_W; 1428our $CHLD_W;
1406our $CHLD_DELAY_W; 1429our $CHLD_DELAY_W;
1407our $WNOHANG; 1430our $WNOHANG;
1408 1431
1432sub _emit_childstatus($$) {
1433 my (undef, $rpid, $rstatus) = @_;
1434
1435 $_->($rpid, $rstatus)
1436 for values %{ $PID_CB{$rpid} || {} },
1437 values %{ $PID_CB{0} || {} };
1438}
1439
1409sub _sigchld { 1440sub _sigchld {
1441 my $pid;
1442
1443 AnyEvent->_emit_childstatus ($pid, $?)
1410 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1444 while ($pid = waitpid -1, $WNOHANG) > 0;
1411 $_->($pid, $?)
1412 for values %{ $PID_CB{$pid} || {} },
1413 values %{ $PID_CB{0} || {} };
1414 }
1415} 1445}
1416 1446
1417sub child { 1447sub child {
1418 my (undef, %arg) = @_; 1448 my (undef, %arg) = @_;
1419 1449
… …
2398L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2428L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2399 2429
2400Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2430Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2401L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2431L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2402L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2432L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2403L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>. 2433L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>.
2404 2434
2405Non-blocking file handles, sockets, TCP clients and 2435Non-blocking file handles, sockets, TCP clients and
2406servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2436servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2407 2437
2408Asynchronous DNS: L<AnyEvent::DNS>. 2438Asynchronous DNS: L<AnyEvent::DNS>.

Diff Legend

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