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.49 by root, Mon Apr 14 19:11:15 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 can arguably be somewhat
64useful) and you want to force your users to use the one and only event
65model, 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.
123 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.
174
124The watcher has only two methods: 175The watcher has only two methods:
125 176
126=over 4 177=over 4
127 178
128=item $cv->wait 179=item $cv->wait
129 180
130Wait (blocking if necessary) until the C<< ->broadcast >> method has been 181Wait (blocking if necessary) until the C<< ->broadcast >> method has been
131called on c<$cv>, while servicing other watchers normally. 182called on c<$cv>, while servicing other watchers normally.
132 183
133Not all event models support a blocking wait - some die in that case, so
134if you are using this from a module, never require a blocking wait, but
135let the caller decide wether the call will block or not (for example,
136by coupling condition variables with some kind of request results and
137supporting callbacks so the caller knows that getting the result will not
138block, while still suppporting blockign waits if the caller so desires).
139
140You can only wait once on a condition - additional calls will return 184You can only wait once on a condition - additional calls will return
141immediately. 185immediately.
186
187Not all event models support a blocking wait - some die in that case
188(programs might want to do that so they stay interactive), so I<if you
189are using this from a module, never require a blocking wait>, but let the
190caller decide wether the call will block or not (for example, by coupling
191condition variables with some kind of request results and supporting
192callbacks so the caller knows that getting the result will not block,
193while still suppporting blocking waits if the caller so desires).
194
195Another reason I<never> to C<< ->wait >> in a module is that you cannot
196sensibly have two C<< ->wait >>'s in parallel, as that would require
197multiple interpreters or coroutines/threads, none of which C<AnyEvent>
198can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
199explicitly support concurrent C<< ->wait >>'s from different coroutines,
200however).
142 201
143=item $cv->broadcast 202=item $cv->broadcast
144 203
145Flag the condition as ready - a running C<< ->wait >> and all further 204Flag the condition as ready - a running C<< ->wait >> and all further
146calls to C<wait> will return after this method has been called. If nobody 205calls to C<wait> will return after this method has been called. If nobody
… …
197C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 256C<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>). 257AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
199 258
200The known classes so far are: 259The known classes so far are:
201 260
261 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
202 EV::AnyEvent based on EV (an interface to libev, best choice) 262 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
203 AnyEvent::Impl::Coro based on Coro::Event, second best choice. 263 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
204 AnyEvent::Impl::Event based on Event, also second best choice :) 264 AnyEvent::Impl::Event based on Event, also second best choice :)
205 AnyEvent::Impl::Glib based on Glib, second-best choice. 265 AnyEvent::Impl::Glib based on Glib, third-best choice.
206 AnyEvent::Impl::Tk based on Tk, very bad choice. 266 AnyEvent::Impl::Tk based on Tk, very bad choice.
207 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 267 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
208 268
209=item AnyEvent::detect 269=item AnyEvent::detect
210 270
211Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if 271Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
212necessary. You should only call this function right before you would have 272necessary. You should only call this function right before you would have
… …
251no warnings; 311no warnings;
252use strict; 312use strict;
253 313
254use Carp; 314use Carp;
255 315
256our $VERSION = '2.55'; 316our $VERSION = '3.0';
257our $MODEL; 317our $MODEL;
258 318
259our $AUTOLOAD; 319our $AUTOLOAD;
260our @ISA; 320our @ISA;
261 321
262our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 322our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
263 323
264our @REGISTRY; 324our @REGISTRY;
265 325
266my @models = ( 326my @models = (
327 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
328 [EV:: => AnyEvent::Impl::EV::],
267 [Coro::Event:: => AnyEvent::Impl::Coro::], 329 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
268 [EV:: => EV::AnyEvent::],
269 [Event:: => AnyEvent::Impl::Event::], 330 [Event:: => AnyEvent::Impl::Event::],
270 [Glib:: => AnyEvent::Impl::Glib::], 331 [Glib:: => AnyEvent::Impl::Glib::],
271 [Tk:: => AnyEvent::Impl::Tk::], 332 [Tk:: => AnyEvent::Impl::Tk::],
272 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 333 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
273); 334);
… …
303 last; 364 last;
304 } 365 }
305 } 366 }
306 367
307 $MODEL 368 $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."; 369 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 } 370 }
310 371
311 unshift @ISA, $MODEL; 372 unshift @ISA, $MODEL;
312 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 373 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
313 } 374 }
… …
371 432
372# default implementation for ->child 433# default implementation for ->child
373 434
374our %PID_CB; 435our %PID_CB;
375our $CHLD_W; 436our $CHLD_W;
437our $CHLD_DELAY_W;
376our $PID_IDLE; 438our $PID_IDLE;
377our $WNOHANG; 439our $WNOHANG;
378 440
379sub _child_wait { 441sub _child_wait {
380 while (0 <= (my $pid = waitpid -1, $WNOHANG)) { 442 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
381 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 443 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
382 (values %{ $PID_CB{0} || {} }); 444 (values %{ $PID_CB{0} || {} });
383 } 445 }
384 446
385 undef $PID_IDLE; 447 undef $PID_IDLE;
386} 448}
387 449
450sub _sigchld {
451 # make sure we deliver these changes "synchronous" with the event loop.
452 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub {
453 undef $CHLD_DELAY_W;
454 &_child_wait;
455 });
456}
457
388sub child { 458sub child {
389 my (undef, %arg) = @_; 459 my (undef, %arg) = @_;
390 460
391 defined (my $pid = $arg{pid} + 0) 461 defined (my $pid = $arg{pid} + 0)
392 or Carp::croak "required option 'pid' is missing"; 462 or Carp::croak "required option 'pid' is missing";
… …
396 unless ($WNOHANG) { 466 unless ($WNOHANG) {
397 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 467 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
398 } 468 }
399 469
400 unless ($CHLD_W) { 470 unless ($CHLD_W) {
401 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait); 471 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
402 # child could be a zombie already 472 # child could be a zombie already, so make at least one round
403 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait); 473 &_sigchld;
404 } 474 }
405 475
406 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 476 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
407} 477}
408 478
… …
572 642
5731. Blocking: 6431. Blocking:
574 644
575 my $data = $fcp->client_get ($url); 645 my $data = $fcp->client_get ($url);
576 646
5772. Blocking, but parallelizing: 6472. Blocking, but running in parallel:
578 648
579 my @datas = map $_->result, 649 my @datas = map $_->result,
580 map $fcp->txn_client_get ($_), 650 map $fcp->txn_client_get ($_),
581 @urls; 651 @urls;
582 652
583Both blocking examples work without the module user having to know 653Both blocking examples work without the module user having to know
584anything about events. 654anything about events.
585 655
5863a. Event-based in a main program, using any support Event module: 6563a. Event-based in a main program, using any supported event module:
587 657
588 use Event; 658 use EV;
589 659
590 $fcp->txn_client_get ($url)->cb (sub { 660 $fcp->txn_client_get ($url)->cb (sub {
591 my $txn = shift; 661 my $txn = shift;
592 my $data = $txn->result; 662 my $data = $txn->result;
593 ... 663 ...
594 }); 664 });
595 665
596 Event::loop; 666 EV::loop;
597 667
5983b. The module user could use AnyEvent, too: 6683b. The module user could use AnyEvent, too:
599 669
600 use AnyEvent; 670 use AnyEvent;
601 671
… …
608 678
609 $quit->wait; 679 $quit->wait;
610 680
611=head1 SEE ALSO 681=head1 SEE ALSO
612 682
613Event modules: L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>. 683Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
684L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>.
614 685
615Implementations: L<AnyEvent::Impl::Coro>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>. 686Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
687L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>,
688L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>.
616 689
617Nontrivial usage example: L<Net::FCP>. 690Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
618 691
619=head1 692=head1
620 693
621=cut 694=cut
622 695

Diff Legend

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