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.34 by root, Fri Nov 9 19:37:05 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
… …
199 247
200The known classes so far are: 248The known classes so far are:
201 249
202 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 250 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
203 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 251 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
204 AnyEvent::Impl::Coro based on Coro::Event, second best choice. 252 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
205 AnyEvent::Impl::Event based on Event, also second best choice :) 253 AnyEvent::Impl::Event based on Event, also second best choice :)
206 AnyEvent::Impl::Glib based on Glib, second-best choice. 254 AnyEvent::Impl::Glib based on Glib, second-best choice.
207 AnyEvent::Impl::Tk based on Tk, very bad choice. 255 AnyEvent::Impl::Tk based on Tk, very bad choice.
208 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 256 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
209 257
… …
252no warnings; 300no warnings;
253use strict; 301use strict;
254 302
255use Carp; 303use Carp;
256 304
257our $VERSION = '2.6'; 305our $VERSION = '3.0';
258our $MODEL; 306our $MODEL;
259 307
260our $AUTOLOAD; 308our $AUTOLOAD;
261our @ISA; 309our @ISA;
262 310
… …
265our @REGISTRY; 313our @REGISTRY;
266 314
267my @models = ( 315my @models = (
268 [Coro::EV:: => AnyEvent::Impl::CoroEV::], 316 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
269 [EV:: => AnyEvent::Impl::EV::], 317 [EV:: => AnyEvent::Impl::EV::],
270 [Coro::Event:: => AnyEvent::Impl::Coro::], 318 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
271 [Event:: => AnyEvent::Impl::Event::], 319 [Event:: => AnyEvent::Impl::Event::],
272 [Glib:: => AnyEvent::Impl::Glib::], 320 [Glib:: => AnyEvent::Impl::Glib::],
273 [Tk:: => AnyEvent::Impl::Tk::], 321 [Tk:: => AnyEvent::Impl::Tk::],
274 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 322 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
275); 323);
… …
305 last; 353 last;
306 } 354 }
307 } 355 }
308 356
309 $MODEL 357 $MODEL
310 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.";
311 } 359 }
312 360
313 unshift @ISA, $MODEL; 361 unshift @ISA, $MODEL;
314 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 362 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
315 } 363 }
… …
373 421
374# default implementation for ->child 422# default implementation for ->child
375 423
376our %PID_CB; 424our %PID_CB;
377our $CHLD_W; 425our $CHLD_W;
426our $CHLD_DELAY_W;
378our $PID_IDLE; 427our $PID_IDLE;
379our $WNOHANG; 428our $WNOHANG;
380 429
381sub _child_wait { 430sub _child_wait {
382 while (0 <= (my $pid = waitpid -1, $WNOHANG)) { 431 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
383 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 432 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
384 (values %{ $PID_CB{0} || {} }); 433 (values %{ $PID_CB{0} || {} });
385 } 434 }
386 435
387 undef $PID_IDLE; 436 undef $PID_IDLE;
388} 437}
389 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 });
445}
446
390sub child { 447sub child {
391 my (undef, %arg) = @_; 448 my (undef, %arg) = @_;
392 449
393 defined (my $pid = $arg{pid} + 0) 450 defined (my $pid = $arg{pid} + 0)
394 or Carp::croak "required option 'pid' is missing"; 451 or Carp::croak "required option 'pid' is missing";
… …
398 unless ($WNOHANG) { 455 unless ($WNOHANG) {
399 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 456 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
400 } 457 }
401 458
402 unless ($CHLD_W) { 459 unless ($CHLD_W) {
403 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait); 460 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
404 # child could be a zombie already 461 # child could be a zombie already, so make at least one round
405 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait); 462 &_sigchld;
406 } 463 }
407 464
408 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 465 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
409} 466}
410 467

Diff Legend

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