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.28 by root, Sat Oct 27 15:10:09 2007 UTC vs.
Revision 1.41 by root, Mon Apr 7 19:23:59 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
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 (the latter of which is actually
44named confusingly, as it does neither do I/O nor does it do anything
45asynchronously...), using them in your module is like joining a
46cult: After you joined, you are dependent on them and you cannot use
47anything else, as it is simply incompatible to everything that isn't
48itself.
49
50AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk
51works fine etc. etc. but none of these work together with the rest: POE
52+ IO::Async? no go. Tk + Event? no go. If your module uses one of
53those, every user of your module has to use it, too. If your module
54uses AnyEvent, it works transparently with all event models it supports
55(including stuff like POE and IO::Async).
56
57In addition of being free of having to use I<the one and only true event
58model>, AnyEvent also is free of bloat and policy: with POE or similar
59modules, you get an enourmous amount of code and strict rules you have
60to follow. AnyEvent, on the other hand, is lean and to the point by only
61offering the functionality that is useful, in as thin as a wrapper as
62technically possible.
63
22 64
23=head1 DESCRIPTION 65=head1 DESCRIPTION
24 66
25L<AnyEvent> provides an identical interface to multiple event loops. This 67L<AnyEvent> provides an identical interface to multiple event loops. This
26allows module authors to utilise an event loop without forcing module 68allows module authors to utilise an event loop without forcing module
… …
70You can create I/O watcher by calling the C<< AnyEvent->io >> method with 112You can create I/O watcher by calling the C<< AnyEvent->io >> method with
71the following mandatory arguments: 113the following mandatory arguments:
72 114
73C<fh> the Perl I<filehandle> (not filedescriptor) to watch for 115C<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 116events. 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 117a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
76to invoke everytime the filehandle becomes ready. 118to invoke everytime the filehandle becomes ready.
77 119
78Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on 120Only 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 121a 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). 122Tk - if you are sure you are not using Tk this limitation is gone).
… …
109 my $w = AnyEvent->timer (after => 7.7, cb => sub { 151 my $w = AnyEvent->timer (after => 7.7, cb => sub {
110 warn "timeout\n"; 152 warn "timeout\n";
111 }); 153 });
112 154
113 # to cancel the timer: 155 # to cancel the timer:
114 undef $w 156 undef $w;
115 157
116=head2 CONDITION WATCHERS 158=head2 CONDITION WATCHERS
117 159
118Condition watchers can be created by calling the C<< AnyEvent->condvar >> 160Condition watchers can be created by calling the C<< AnyEvent->condvar >>
119method without any arguments. 161method without any arguments.
120 162
121A condition watcher watches for a condition - precisely that the C<< 163A condition watcher watches for a condition - precisely that the C<<
122->broadcast >> method has been called. 164->broadcast >> method has been called.
165
166Note that condition watchers recurse into the event loop - if you have
167two watchers that call C<< ->wait >> in a round-robbin fashion, you
168lose. Therefore, condition watchers are good to export to your caller, but
169you should avoid making a blocking wait, at least in callbacks, as this
170usually asks for trouble.
123 171
124The watcher has only two methods: 172The watcher has only two methods:
125 173
126=over 4 174=over 4
127 175
… …
174 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 222 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
175 223
176=head2 CHILD PROCESS WATCHERS 224=head2 CHILD PROCESS WATCHERS
177 225
178You can also listen for the status of a child process specified by the 226You 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 227C<pid> argument (or any child if the pid argument is 0). The watcher will
180installing a signal handler for C<SIGCHLD>. 228trigger as often as status change for the child are received. This works
229by installing a signal handler for C<SIGCHLD>. The callback will be called with
230the pid and exit status (as returned by waitpid).
181 231
182Example: wait for pid 1333 232Example: wait for pid 1333
183 233
184 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" }); 234 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
185 235
… …
195C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 245C<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>). 246AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
197 247
198The known classes so far are: 248The known classes so far are:
199 249
200 AnyEvent::Impl::Coro based on Coro::Event, best choice. 250 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
201 EV::AnyEvent based on EV (an interface to libevent) 251 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
252 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
202 AnyEvent::Impl::Event based on Event, also best choice :) 253 AnyEvent::Impl::Event based on Event, also second best choice :)
203 AnyEvent::Impl::Glib based on Glib, second-best choice. 254 AnyEvent::Impl::Glib based on Glib, second-best choice.
204 AnyEvent::Impl::Tk based on Tk, very bad choice. 255 AnyEvent::Impl::Tk based on Tk, very bad choice.
205 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 256 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
206 257
207=item AnyEvent::detect 258=item AnyEvent::detect
… …
249no warnings; 300no warnings;
250use strict; 301use strict;
251 302
252use Carp; 303use Carp;
253 304
254our $VERSION = '2.55'; 305our $VERSION = '3.0';
255our $MODEL; 306our $MODEL;
256 307
257our $AUTOLOAD; 308our $AUTOLOAD;
258our @ISA; 309our @ISA;
259 310
260our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 311our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
261 312
262our @REGISTRY; 313our @REGISTRY;
263 314
264my @models = ( 315my @models = (
316 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
317 [EV:: => AnyEvent::Impl::EV::],
265 [Coro::Event:: => AnyEvent::Impl::Coro::], 318 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
266 [EV:: => EV::AnyEvent::],
267 [Event:: => AnyEvent::Impl::Event::], 319 [Event:: => AnyEvent::Impl::Event::],
268 [Glib:: => AnyEvent::Impl::Glib::], 320 [Glib:: => AnyEvent::Impl::Glib::],
269 [Tk:: => AnyEvent::Impl::Tk::], 321 [Tk:: => AnyEvent::Impl::Tk::],
270 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 322 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
271); 323);
… …
301 last; 353 last;
302 } 354 }
303 } 355 }
304 356
305 $MODEL 357 $MODEL
306 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk."; 358 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.";
307 } 359 }
308 360
309 unshift @ISA, $MODEL; 361 unshift @ISA, $MODEL;
310 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 362 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
311 } 363 }
… …
369 421
370# default implementation for ->child 422# default implementation for ->child
371 423
372our %PID_CB; 424our %PID_CB;
373our $CHLD_W; 425our $CHLD_W;
426our $CHLD_DELAY_W;
374our $PID_IDLE; 427our $PID_IDLE;
375our $WNOHANG; 428our $WNOHANG;
376 429
377sub _child_wait { 430sub _child_wait {
378 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 431 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
379 $_->() for values %{ (delete $PID_CB{$pid}) || {} }; 432 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
433 (values %{ $PID_CB{0} || {} });
380 } 434 }
381 435
382 undef $PID_IDLE; 436 undef $PID_IDLE;
437}
438
439sub _sigchld {
440 # make sure we deliver these changes "synchronous" with the event loop.
441 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub {
442 undef $CHLD_DELAY_W;
443 &_child_wait;
444 });
383} 445}
384 446
385sub child { 447sub child {
386 my (undef, %arg) = @_; 448 my (undef, %arg) = @_;
387 449
388 my $pid = uc $arg{pid} 450 defined (my $pid = $arg{pid} + 0)
389 or Carp::croak "required option 'pid' is missing"; 451 or Carp::croak "required option 'pid' is missing";
390 452
391 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 453 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
392 454
393 unless ($WNOHANG) { 455 unless ($WNOHANG) {
394 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 456 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
395 } 457 }
396 458
397 unless ($CHLD_W) { 459 unless ($CHLD_W) {
398 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait); 460 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
399 # child could be a zombie already 461 # child could be a zombie already, so make at least one round
400 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait); 462 &_sigchld;
401 } 463 }
402 464
403 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 465 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
404} 466}
405 467

Diff Legend

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