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.247 by root, Sat Jul 18 22:24:17 2009 UTC vs.
Revision 1.260 by root, Tue Jul 28 11:02:19 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - the DBI of event loop programming
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt
6event loops. 6and POE are various supported event loops/environments.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
… …
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
52Repository>, 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?
… …
392 400
393=head2 CHILD PROCESS WATCHERS 401=head2 CHILD PROCESS WATCHERS
394 402
395You 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.
396 404
397The 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,
398watches for any child process exit). The watcher will triggered only when 406using C<0> watches for any child process exit, on others this will
399the child process has finished and an exit status is available, not on 407croak). The watcher will be triggered only when the child process has
400any trace events (stopped/continued). 408finished and an exit status is available, not on any trace events
409(stopped/continued).
401 410
402The 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
403waitpid), 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
404callback arguments. 413callback arguments.
405 414
… …
509Condition variables are similar to callbacks, except that you can 518Condition variables are similar to callbacks, except that you can
510optionally wait for them. They can also be called merge points - points 519optionally wait for them. They can also be called merge points - points
511in time where multiple outstanding events have been processed. And yet 520in time where multiple outstanding events have been processed. And yet
512another way to call them is transactions - each condition variable can be 521another way to call them is transactions - each condition variable can be
513used to represent a transaction, which finishes at some point and delivers 522used to represent a transaction, which finishes at some point and delivers
514a result. 523a result. And yet some people know them as "futures" - a promise to
524compute/deliver something that you can wait for.
515 525
516Condition variables are very useful to signal that something has finished, 526Condition variables are very useful to signal that something has finished,
517for example, if you write a module that does asynchronous http requests, 527for example, if you write a module that does asynchronous http requests,
518then a condition variable would be the ideal candidate to signal the 528then a condition variable would be the ideal candidate to signal the
519availability of results. The user can either act when the callback is 529availability of results. The user can either act when the callback is
… …
787 797
788 AnyEvent::Impl::Glib based on Glib, slow but very stable. 798 AnyEvent::Impl::Glib based on Glib, slow but very stable.
789 AnyEvent::Impl::Tk based on Tk, very broken. 799 AnyEvent::Impl::Tk based on Tk, very broken.
790 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 800 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
791 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.
792 803
793=item Backends with special needs. 804=item Backends with special needs.
794 805
795Qt requires the Qt::Application to be instantiated first, but will 806Qt requires the Qt::Application to be instantiated first, but will
796otherwise be picked up automatically. As long as the main program 807otherwise be picked up automatically. As long as the main program
… …
870event module detection too early, for example, L<AnyEvent::AIO> creates 881event module detection too early, for example, L<AnyEvent::AIO> creates
871and 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
872avoid autodetecting the event module at load time. 883avoid autodetecting the event module at load time.
873 884
874If 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
875that 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
876L<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;
877 905
878=item @AnyEvent::post_detect 906=item @AnyEvent::post_detect
879 907
880If 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
881before or after loading AnyEvent), then they will called directly after 909before or after loading AnyEvent), then they will called directly after
… …
1058 1086
1059BEGIN { AnyEvent::common_sense } 1087BEGIN { AnyEvent::common_sense }
1060 1088
1061use Carp (); 1089use Carp ();
1062 1090
1063our $VERSION = 4.85; 1091our $VERSION = 4.881;
1064our $MODEL; 1092our $MODEL;
1065 1093
1066our $AUTOLOAD; 1094our $AUTOLOAD;
1067our @ISA; 1095our @ISA;
1068 1096
… …
1093 for reverse split /\s*,\s*/, 1121 for reverse split /\s*,\s*/,
1094 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1122 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1095} 1123}
1096 1124
1097my @models = ( 1125my @models = (
1098 [EV:: => AnyEvent::Impl::EV::], 1126 [EV:: => AnyEvent::Impl::EV:: , 1],
1099 [Event:: => AnyEvent::Impl::Event::], 1127 [Event:: => AnyEvent::Impl::Event::, 1],
1100 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1128 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1101 # everything below here will not be autoprobed 1129 # everything below here will not (normally) be autoprobed
1102 # as the pureperl backend should work everywhere 1130 # as the pureperl backend should work everywhere
1103 # and is usually faster 1131 # and is usually faster
1104 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1132 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1105 [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
1106 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1135 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1107 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1136 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1108 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1137 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1109 [Wx:: => AnyEvent::Impl::POE::], 1138 [Wx:: => AnyEvent::Impl::POE::],
1110 [Prima:: => AnyEvent::Impl::POE::], 1139 [Prima:: => AnyEvent::Impl::POE::],
1111 # 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
1112 # byzantine signal and broken child handling, among others. 1141 # byzantine signal and broken child handling, among others.
1113 # 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
1114 # obvious default class. 1143 # obvious default class.
1115# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1144# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1116# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1145# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1117# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1146# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1118); 1147);
1119 1148
1120our %method = map +($_ => 1), 1149our %method = map +($_ => 1),
1121 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);
1122 1151
… …
1126 my ($cb) = @_; 1155 my ($cb) = @_;
1127 1156
1128 if ($MODEL) { 1157 if ($MODEL) {
1129 $cb->(); 1158 $cb->();
1130 1159
1131 1 1160 undef
1132 } else { 1161 } else {
1133 push @post_detect, $cb; 1162 push @post_detect, $cb;
1134 1163
1135 defined wantarray 1164 defined wantarray
1136 ? bless \$cb, "AnyEvent::Util::postdetect" 1165 ? bless \$cb, "AnyEvent::Util::postdetect"
… …
1168 } 1197 }
1169 } 1198 }
1170 } 1199 }
1171 1200
1172 unless ($MODEL) { 1201 unless ($MODEL) {
1173 # try to load a model 1202 # try to autoload a model
1174
1175 for (@REGISTRY, @models) { 1203 for (@REGISTRY, @models) {
1176 my ($package, $model) = @$_; 1204 my ($package, $model, $autoload) = @$_;
1205 if (
1206 $autoload
1177 if (eval "require $package" 1207 and eval "require $package"
1178 and ${"$package\::VERSION"} > 0 1208 and ${"$package\::VERSION"} > 0
1179 and eval "require $model") { 1209 and eval "require $model"
1210 ) {
1180 $MODEL = $model; 1211 $MODEL = $model;
1181 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2; 1212 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1182 last; 1213 last;
1183 } 1214 }
1184 } 1215 }
1185 1216
1186 $MODEL 1217 $MODEL
… …
1396our %PID_CB; 1427our %PID_CB;
1397our $CHLD_W; 1428our $CHLD_W;
1398our $CHLD_DELAY_W; 1429our $CHLD_DELAY_W;
1399our $WNOHANG; 1430our $WNOHANG;
1400 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
1401sub _sigchld { 1440sub _sigchld {
1441 my $pid;
1442
1443 AnyEvent->_emit_childstatus ($pid, $?)
1402 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1444 while ($pid = waitpid -1, $WNOHANG) > 0;
1403 $_->($pid, $?)
1404 for values %{ $PID_CB{$pid} || {} },
1405 values %{ $PID_CB{0} || {} };
1406 }
1407} 1445}
1408 1446
1409sub child { 1447sub child {
1410 my (undef, %arg) = @_; 1448 my (undef, %arg) = @_;
1411 1449
… …
2313 2351
2314=item L<JSON> and L<JSON::XS> 2352=item L<JSON> and L<JSON::XS>
2315 2353
2316This module is required when you want to read or write JSON data via 2354This module is required when you want to read or write JSON data via
2317L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2355L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2318advantage of the ulta-high-speed L<JSON::XS> module when it is installed. 2356advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2319 2357
2320In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is 2358In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2321installed. 2359installed.
2322 2360
2323=item L<Net::SSLeay> 2361=item L<Net::SSLeay>
… …
2390L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2428L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2391 2429
2392Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2430Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2393L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2431L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2394L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2432L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2395L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>. 2433L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>.
2396 2434
2397Non-blocking file handles, sockets, TCP clients and 2435Non-blocking file handles, sockets, TCP clients and
2398servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2436servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2399 2437
2400Asynchronous DNS: L<AnyEvent::DNS>. 2438Asynchronous DNS: L<AnyEvent::DNS>.

Diff Legend

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