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.23 by root, Wed Mar 7 17:37:24 2007 UTC vs.
Revision 1.44 by root, Mon Apr 7 19:42:18 2008 UTC

… …
17 }); 17 });
18 18
19 my $w = AnyEvent->condvar; # stores wether a condition was flagged 19 my $w = AnyEvent->condvar; # stores wether a condition was flagged
20 $w->wait; # enters "main loop" till $condvar gets ->broadcast 20 $w->wait; # enters "main loop" till $condvar gets ->broadcast
21 $w->broadcast; # wake up current and all future wait's 21 $w->broadcast; # wake up current and all future wait's
22
23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24
25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26nowadays. So what is different about AnyEvent?
27
28Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
29policy> and AnyEvent is I<small and efficient>.
30
31First and foremost, I<AnyEvent is not an event model> itself, it only
32interfaces to whatever event model the main program happens to use in a
33pragmatic way. For event models and certain classes of immortals alike,
34the statement "there can only be one" is a bitter reality, and AnyEvent
35helps hiding the differences.
36
37The goal of AnyEvent is to offer module authors the ability to do event
38programming (waiting for I/O or timer events) without subscribing to a
39religion, a way of living, and most importantly: without forcing your
40module users into the same thing by forcing them to use the same event
41model you use.
42
43For modules like POE or IO::Async (which is actually doing all I/O
44I<synchronously>...), using them in your module is like joining a
45cult: After you joined, you are dependent on them and you cannot use
46anything else, as it is simply incompatible to everything that isn't
47itself.
48
49AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk
50works fine etc. etc. but none of these work together with the rest: POE
51+ IO::Async? no go. Tk + Event? no go. If your module uses one of
52those, every user of your module has to use it, too. If your module
53uses AnyEvent, it works transparently with all event models it supports
54(including stuff like POE and IO::Async).
55
56In addition of being free of having to use I<the one and only true event
57model>, AnyEvent also is free of bloat and policy: with POE or similar
58modules, you get an enourmous amount of code and strict rules you have
59to follow. AnyEvent, on the other hand, is lean and to the point by only
60offering the functionality that is useful, in as thin as a wrapper as
61technically possible.
62
63Of course, if you want lots of policy (this is arguably somewhat useful
64in many cases) and you want to force your users to the one and only event
65model your module forces on them, you should I<not> use this module.
66
22 67
23=head1 DESCRIPTION 68=head1 DESCRIPTION
24 69
25L<AnyEvent> provides an identical interface to multiple event loops. This 70L<AnyEvent> provides an identical interface to multiple event loops. This
26allows module authors to utilise an event loop without forcing module 71allows module authors to utilise an event loop without forcing module
… …
70You can create I/O watcher by calling the C<< AnyEvent->io >> method with 115You can create I/O watcher by calling the C<< AnyEvent->io >> method with
71the following mandatory arguments: 116the following mandatory arguments:
72 117
73C<fh> the Perl I<filehandle> (not filedescriptor) to watch for 118C<fh> the Perl I<filehandle> (not filedescriptor) to watch for
74events. C<poll> must be a string that is either C<r> or C<w>, that creates 119events. C<poll> must be a string that is either C<r> or C<w>, that creates
75a watcher waiting for "r"eadable or "w"ritable events. C<cb> teh callback 120a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
76to invoke everytime the filehandle becomes ready. 121to invoke everytime the filehandle becomes ready.
77 122
78Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on 123Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on
79a socket you can have one r + one w, not any more (limitation comes from 124a socket you can have one r + one w, not any more (limitation comes from
80Tk - if you are sure you are not using Tk this limitation is gone). 125Tk - if you are sure you are not using Tk this limitation is gone).
… …
109 my $w = AnyEvent->timer (after => 7.7, cb => sub { 154 my $w = AnyEvent->timer (after => 7.7, cb => sub {
110 warn "timeout\n"; 155 warn "timeout\n";
111 }); 156 });
112 157
113 # to cancel the timer: 158 # to cancel the timer:
114 undef $w 159 undef $w;
115 160
116=head2 CONDITION WATCHERS 161=head2 CONDITION WATCHERS
117 162
118Condition watchers can be created by calling the C<< AnyEvent->condvar >> 163Condition watchers can be created by calling the C<< AnyEvent->condvar >>
119method without any arguments. 164method without any arguments.
120 165
121A condition watcher watches for a condition - precisely that the C<< 166A condition watcher watches for a condition - precisely that the C<<
122->broadcast >> method has been called. 167->broadcast >> method has been called.
168
169Note that condition watchers recurse into the event loop - if you have
170two watchers that call C<< ->wait >> in a round-robbin fashion, you
171lose. Therefore, condition watchers are good to export to your caller, but
172you should avoid making a blocking wait, at least in callbacks, as this
173usually asks for trouble.
123 174
124The watcher has only two methods: 175The watcher has only two methods:
125 176
126=over 4 177=over 4
127 178
… …
174 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 225 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
175 226
176=head2 CHILD PROCESS WATCHERS 227=head2 CHILD PROCESS WATCHERS
177 228
178You can also listen for the status of a child process specified by the 229You can also listen for the status of a child process specified by the
179C<pid> argument. The watcher will only trigger once. This works by 230C<pid> argument (or any child if the pid argument is 0). The watcher will
180installing a signal handler for C<SIGCHLD>. 231trigger as often as status change for the child are received. This works
232by installing a signal handler for C<SIGCHLD>. The callback will be called with
233the pid and exit status (as returned by waitpid).
181 234
182Example: wait for pid 1333 235Example: wait for pid 1333
183 236
184 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" }); 237 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
185 238
… …
195C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 248C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
196AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 249AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
197 250
198The known classes so far are: 251The known classes so far are:
199 252
200 AnyEvent::Impl::Coro based on Coro::Event, best choise. 253 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
254 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
255 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
201 AnyEvent::Impl::Event based on Event, also best choice :) 256 AnyEvent::Impl::Event based on Event, also second best choice :)
202 AnyEvent::Impl::Glib based on Glib, second-best choice. 257 AnyEvent::Impl::Glib based on Glib, second-best choice.
203 AnyEvent::Impl::Tk based on Tk, very bad choice. 258 AnyEvent::Impl::Tk based on Tk, very bad choice.
204 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 259 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
205 260
206=item AnyEvent::detect 261=item AnyEvent::detect
… …
245 300
246package AnyEvent; 301package AnyEvent;
247 302
248no warnings; 303no warnings;
249use strict; 304use strict;
305
250use Carp; 306use Carp;
251 307
252our $VERSION = '2.52'; 308our $VERSION = '3.0';
253our $MODEL; 309our $MODEL;
254 310
255our $AUTOLOAD; 311our $AUTOLOAD;
256our @ISA; 312our @ISA;
257 313
258our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 314our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
259 315
260our @REGISTRY; 316our @REGISTRY;
261 317
262my @models = ( 318my @models = (
319 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
320 [EV:: => AnyEvent::Impl::EV::],
263 [Coro::Event:: => AnyEvent::Impl::Coro::], 321 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
264 [Event:: => AnyEvent::Impl::Event::], 322 [Event:: => AnyEvent::Impl::Event::],
265 [Glib:: => AnyEvent::Impl::Glib::], 323 [Glib:: => AnyEvent::Impl::Glib::],
266 [Tk:: => AnyEvent::Impl::Tk::], 324 [Tk:: => AnyEvent::Impl::Tk::],
267 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 325 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
268); 326);
… …
298 last; 356 last;
299 } 357 }
300 } 358 }
301 359
302 $MODEL 360 $MODEL
303 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk."; 361 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event), Glib or Tk.";
304 } 362 }
305 363
306 unshift @ISA, $MODEL; 364 unshift @ISA, $MODEL;
307 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 365 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
308 } 366 }
… …
366 424
367# default implementation for ->child 425# default implementation for ->child
368 426
369our %PID_CB; 427our %PID_CB;
370our $CHLD_W; 428our $CHLD_W;
429our $CHLD_DELAY_W;
371our $PID_IDLE; 430our $PID_IDLE;
372our $WNOHANG; 431our $WNOHANG;
373 432
374sub _child_wait { 433sub _child_wait {
375 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 434 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
376 $_->() for values %{ (delete $PID_CB{$pid}) || {} }; 435 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
436 (values %{ $PID_CB{0} || {} });
377 } 437 }
378 438
379 undef $PID_IDLE; 439 undef $PID_IDLE;
440}
441
442sub _sigchld {
443 # make sure we deliver these changes "synchronous" with the event loop.
444 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub {
445 undef $CHLD_DELAY_W;
446 &_child_wait;
447 });
380} 448}
381 449
382sub child { 450sub child {
383 my (undef, %arg) = @_; 451 my (undef, %arg) = @_;
384 452
385 my $pid = uc $arg{pid} 453 defined (my $pid = $arg{pid} + 0)
386 or Carp::croak "required option 'pid' is missing"; 454 or Carp::croak "required option 'pid' is missing";
387 455
388 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 456 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
389 457
390 unless ($WNOHANG) { 458 unless ($WNOHANG) {
391 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 459 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
392 } 460 }
393 461
394 unless ($CHLD_W) { 462 unless ($CHLD_W) {
395 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait); 463 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
396 # child could be a zombie already 464 # child could be a zombie already, so make at least one round
397 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait); 465 &_sigchld;
398 } 466 }
399 467
400 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 468 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
401} 469}
402 470
… …
439I<rxvt-unicode> distribution. 507I<rxvt-unicode> distribution.
440 508
441I<rxvt-unicode> also cheats a bit by not providing blocking access to 509I<rxvt-unicode> also cheats a bit by not providing blocking access to
442condition variables: code blocking while waiting for a condition will 510condition variables: code blocking while waiting for a condition will
443C<die>. This still works with most modules/usages, and blocking calls must 511C<die>. This still works with most modules/usages, and blocking calls must
444not be in an interactive appliation, so it makes sense. 512not be in an interactive application, so it makes sense.
445 513
446=head1 ENVIRONMENT VARIABLES 514=head1 ENVIRONMENT VARIABLES
447 515
448The following environment variables are used by this module: 516The following environment variables are used by this module:
449 517

Diff Legend

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