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

Diff Legend

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