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.31 by root, Fri Nov 2 19:20:36 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
… …
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 (or any child if the pid argument is 0). The watcher will 227C<pid> argument (or any child if the pid argument is 0). The watcher will
180trigger as often as status change for the child are received. This works 228trigger as often as status change for the child are received. This works
181by installing a signal handler for C<SIGCHLD>. 229by installing a signal handler for C<SIGCHLD>. The callback will be called with
230the pid and exit status (as returned by waitpid).
182 231
183Example: wait for pid 1333 232Example: wait for pid 1333
184 233
185 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" }); 234 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
186 235
… …
196C<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
197AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 246AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
198 247
199The known classes so far are: 248The known classes so far are:
200 249
250 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
201 EV::AnyEvent based on EV (an interface to libev, best choice) 251 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
202 AnyEvent::Impl::Coro based on Coro::Event, second best choice. 252 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
203 AnyEvent::Impl::Event based on Event, also second best choice :) 253 AnyEvent::Impl::Event based on Event, also second best choice :)
204 AnyEvent::Impl::Glib based on Glib, second-best choice. 254 AnyEvent::Impl::Glib based on Glib, second-best choice.
205 AnyEvent::Impl::Tk based on Tk, very bad choice. 255 AnyEvent::Impl::Tk based on Tk, very bad choice.
206 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 256 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
207 257
… …
250no warnings; 300no warnings;
251use strict; 301use strict;
252 302
253use Carp; 303use Carp;
254 304
255our $VERSION = '2.55'; 305our $VERSION = '3.0';
256our $MODEL; 306our $MODEL;
257 307
258our $AUTOLOAD; 308our $AUTOLOAD;
259our @ISA; 309our @ISA;
260 310
261our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 311our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
262 312
263our @REGISTRY; 313our @REGISTRY;
264 314
265my @models = ( 315my @models = (
316 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
317 [EV:: => AnyEvent::Impl::EV::],
266 [Coro::Event:: => AnyEvent::Impl::Coro::], 318 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
267 [EV:: => EV::AnyEvent::],
268 [Event:: => AnyEvent::Impl::Event::], 319 [Event:: => AnyEvent::Impl::Event::],
269 [Glib:: => AnyEvent::Impl::Glib::], 320 [Glib:: => AnyEvent::Impl::Glib::],
270 [Tk:: => AnyEvent::Impl::Tk::], 321 [Tk:: => AnyEvent::Impl::Tk::],
271 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 322 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
272); 323);
… …
302 last; 353 last;
303 } 354 }
304 } 355 }
305 356
306 $MODEL 357 $MODEL
307 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.";
308 } 359 }
309 360
310 unshift @ISA, $MODEL; 361 unshift @ISA, $MODEL;
311 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 362 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
312 } 363 }
… …
370 421
371# default implementation for ->child 422# default implementation for ->child
372 423
373our %PID_CB; 424our %PID_CB;
374our $CHLD_W; 425our $CHLD_W;
426our $CHLD_DELAY_W;
375our $PID_IDLE; 427our $PID_IDLE;
376our $WNOHANG; 428our $WNOHANG;
377 429
378sub _child_wait { 430sub _child_wait {
379 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 431 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
380 $_->() for (values %{ $PID_CB{$pid} || {} }), 432 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
381 (values %{ $PID_CB{0} || {} }); 433 (values %{ $PID_CB{0} || {} });
382 } 434 }
383 435
384 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 });
385} 445}
386 446
387sub child { 447sub child {
388 my (undef, %arg) = @_; 448 my (undef, %arg) = @_;
389 449
… …
395 unless ($WNOHANG) { 455 unless ($WNOHANG) {
396 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 456 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
397 } 457 }
398 458
399 unless ($CHLD_W) { 459 unless ($CHLD_W) {
400 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait); 460 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
401 # child could be a zombie already 461 # child could be a zombie already, so make at least one round
402 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait); 462 &_sigchld;
403 } 463 }
404 464
405 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 465 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
406} 466}
407 467

Diff Legend

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