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.20 by root, Mon Dec 11 01:16:09 2006 UTC vs.
Revision 1.51 by root, Wed Apr 16 15:10:10 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - provide framework for multiple event loops
4 4
5Event, Coro, Glib, Tk, Perl - various supported event loops 5EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl - various supported event loops
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 use AnyEvent; 9 use AnyEvent;
10 10
… …
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
… …
30The interface itself is vaguely similar but not identical to the Event 75The interface itself is vaguely similar but not identical to the Event
31module. 76module.
32 77
33On the first call of any method, the module tries to detect the currently 78On the first call of any method, the module tries to detect the currently
34loaded event loop by probing wether any of the following modules is 79loaded event loop by probing wether any of the following modules is
35loaded: L<Coro::Event>, L<Event>, L<Glib>, L<Tk>. The first one found is 80loaded: L<Coro::EV>, L<Coro::Event>, L<EV>, L<Event>, L<Glib>, L<Tk>. The
36used. If none is found, the module tries to load these modules in the 81first one found is used. If none are found, the module tries to load these
37order given. The first one that could be successfully loaded will be 82modules in the order given. The first one that could be successfully
38used. If still none could be found, AnyEvent will fall back to a pure-perl 83loaded will be used. If still none could be found, AnyEvent will fall back
39event loop, which is also not very efficient. 84to a pure-perl event loop, which is also not very efficient.
40 85
41Because AnyEvent first checks for modules that are already loaded, loading 86Because AnyEvent first checks for modules that are already loaded, loading
42an Event model explicitly before first using AnyEvent will likely make 87an Event model explicitly before first using AnyEvent will likely make
43that model the default. For example: 88that model the default. For example:
44 89
… …
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
78Only 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
80Tk - if you are sure you are not using Tk this limitation is gone).
81 122
82Filehandles will be kept alive, so as long as the watcher exists, the 123Filehandles will be kept alive, so as long as the watcher exists, the
83filehandle exists, too. 124filehandle exists, too.
84 125
85Example: 126Example:
… …
109 my $w = AnyEvent->timer (after => 7.7, cb => sub { 150 my $w = AnyEvent->timer (after => 7.7, cb => sub {
110 warn "timeout\n"; 151 warn "timeout\n";
111 }); 152 });
112 153
113 # to cancel the timer: 154 # to cancel the timer:
114 undef $w 155 undef $w;
115 156
116=head2 CONDITION WATCHERS 157=head2 CONDITION WATCHERS
117 158
118Condition watchers can be created by calling the C<< AnyEvent->condvar >> 159Condition watchers can be created by calling the C<< AnyEvent->condvar >>
119method without any arguments. 160method without any arguments.
120 161
121A condition watcher watches for a condition - precisely that the C<< 162A condition watcher watches for a condition - precisely that the C<<
122->broadcast >> method has been called. 163->broadcast >> method has been called.
123 164
165Note that condition watchers recurse into the event loop - if you have
166two watchers that call C<< ->wait >> in a round-robbin fashion, you
167lose. Therefore, condition watchers are good to export to your caller, but
168you should avoid making a blocking wait, at least in callbacks, as this
169usually asks for trouble.
170
124The watcher has only two methods: 171The watcher has only two methods:
125 172
126=over 4 173=over 4
127 174
128=item $cv->wait 175=item $cv->wait
129 176
130Wait (blocking if necessary) until the C<< ->broadcast >> method has been 177Wait (blocking if necessary) until the C<< ->broadcast >> method has been
131called on c<$cv>, while servicing other watchers normally. 178called on c<$cv>, while servicing other watchers normally.
132 179
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 180You can only wait once on a condition - additional calls will return
141immediately. 181immediately.
182
183Not all event models support a blocking wait - some die in that case
184(programs might want to do that so they stay interactive), so I<if you
185are using this from a module, never require a blocking wait>, but let the
186caller decide wether the call will block or not (for example, by coupling
187condition variables with some kind of request results and supporting
188callbacks so the caller knows that getting the result will not block,
189while still suppporting blocking waits if the caller so desires).
190
191Another reason I<never> to C<< ->wait >> in a module is that you cannot
192sensibly have two C<< ->wait >>'s in parallel, as that would require
193multiple interpreters or coroutines/threads, none of which C<AnyEvent>
194can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
195explicitly support concurrent C<< ->wait >>'s from different coroutines,
196however).
142 197
143=item $cv->broadcast 198=item $cv->broadcast
144 199
145Flag the condition as ready - a running C<< ->wait >> and all further 200Flag 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 201calls to C<wait> will return after this method has been called. If nobody
… …
161 216
162=head2 SIGNAL WATCHERS 217=head2 SIGNAL WATCHERS
163 218
164You can listen for signals using a signal watcher, C<signal> is the signal 219You can listen for signals using a signal watcher, C<signal> is the signal
165I<name> without any C<SIG> prefix. Multiple signals events can be clumped 220I<name> without any C<SIG> prefix. Multiple signals events can be clumped
166together into one callback invocation, and callbakc invocation might or 221together into one callback invocation, and callback invocation might or
167might not be asynchronous. 222might not be asynchronous.
168 223
169These watchers might use C<%SIG>, so programs overwriting those signals 224These watchers might use C<%SIG>, so programs overwriting those signals
170directly will likely not work correctly. 225directly will likely not work correctly.
171 226
… …
174 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 229 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
175 230
176=head2 CHILD PROCESS WATCHERS 231=head2 CHILD PROCESS WATCHERS
177 232
178You can also listen for the status of a child process specified by the 233You 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 234C<pid> argument (or any child if the pid argument is 0). The watcher will
180installing a signal handler for C<SIGCHLD>. 235trigger as often as status change for the child are received. This works
236by installing a signal handler for C<SIGCHLD>. The callback will be called with
237the pid and exit status (as returned by waitpid).
181 238
182Example: wait for pid 1333 239Example: wait for pid 1333
183 240
184 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" }); 241 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
185 242
… …
195C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 252C<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>). 253AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
197 254
198The known classes so far are: 255The known classes so far are:
199 256
200 AnyEvent::Impl::Coro based on Coro::Event, best choise. 257 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
258 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
259 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
201 AnyEvent::Impl::Event based on Event, also best choice :) 260 AnyEvent::Impl::Event based on Event, also second best choice :)
202 AnyEvent::Impl::Glib based on Glib, second-best choice. 261 AnyEvent::Impl::Glib based on Glib, third-best choice.
203 AnyEvent::Impl::Tk based on Tk, very bad choice. 262 AnyEvent::Impl::Tk based on Tk, very bad choice.
204 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 263 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
205 264
206=item AnyEvent::detect 265=item AnyEvent::detect
207 266
208Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if 267Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
209necessary. You should only call this function right before you would have 268necessary. You should only call this function right before you would have
… …
245 304
246package AnyEvent; 305package AnyEvent;
247 306
248no warnings; 307no warnings;
249use strict; 308use strict;
309
250use Carp; 310use Carp;
251 311
252our $VERSION = '2.5'; 312our $VERSION = '3.1';
253our $MODEL; 313our $MODEL;
254 314
255our $AUTOLOAD; 315our $AUTOLOAD;
256our @ISA; 316our @ISA;
257 317
258our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 318our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
259 319
260our @REGISTRY; 320our @REGISTRY;
261 321
262my @models = ( 322my @models = (
323 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
263 [Coro::Event:: => AnyEvent::Impl::Coro::], 324 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
325 [EV:: => AnyEvent::Impl::EV::],
264 [Event:: => AnyEvent::Impl::Event::], 326 [Event:: => AnyEvent::Impl::Event::],
265 [Glib:: => AnyEvent::Impl::Glib::], 327 [Glib:: => AnyEvent::Impl::Glib::],
266 [Tk:: => AnyEvent::Impl::Tk::], 328 [Tk:: => AnyEvent::Impl::Tk::],
267 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 329 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
268); 330);
… …
288 unless ($MODEL) { 350 unless ($MODEL) {
289 # try to load a model 351 # try to load a model
290 352
291 for (@REGISTRY, @models) { 353 for (@REGISTRY, @models) {
292 my ($package, $model) = @$_; 354 my ($package, $model) = @$_;
355 if (eval "require $package"
356 and ${"$package\::VERSION"} > 0
293 if (eval "require $model") { 357 and eval "require $model") {
294 $MODEL = $model; 358 $MODEL = $model;
295 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1; 359 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
296 last; 360 last;
297 } 361 }
298 } 362 }
299 363
300 $MODEL 364 $MODEL
301 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk."; 365 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.";
302 } 366 }
303 367
304 unshift @ISA, $MODEL; 368 unshift @ISA, $MODEL;
305 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 369 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
306 } 370 }
… …
364 428
365# default implementation for ->child 429# default implementation for ->child
366 430
367our %PID_CB; 431our %PID_CB;
368our $CHLD_W; 432our $CHLD_W;
433our $CHLD_DELAY_W;
369our $PID_IDLE; 434our $PID_IDLE;
370our $WNOHANG; 435our $WNOHANG;
371 436
372sub _child_wait { 437sub _child_wait {
373 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 438 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
374 $_->() for values %{ (delete $PID_CB{$pid}) || {} }; 439 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
440 (values %{ $PID_CB{0} || {} });
375 } 441 }
376 442
377 undef $PID_IDLE; 443 undef $PID_IDLE;
444}
445
446sub _sigchld {
447 # make sure we deliver these changes "synchronous" with the event loop.
448 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub {
449 undef $CHLD_DELAY_W;
450 &_child_wait;
451 });
378} 452}
379 453
380sub child { 454sub child {
381 my (undef, %arg) = @_; 455 my (undef, %arg) = @_;
382 456
383 my $pid = uc $arg{pid} 457 defined (my $pid = $arg{pid} + 0)
384 or Carp::croak "required option 'pid' is missing"; 458 or Carp::croak "required option 'pid' is missing";
385 459
386 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 460 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
387 461
388 unless ($WNOHANG) { 462 unless ($WNOHANG) {
389 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait);
390 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 463 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
391 } 464 }
392 465
393 # child could be a zombie already 466 unless ($CHLD_W) {
394 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait); 467 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
468 # child could be a zombie already, so make at least one round
469 &_sigchld;
470 }
395 471
396 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 472 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
397} 473}
398 474
399sub AnyEvent::Base::Child::DESTROY { 475sub AnyEvent::Base::Child::DESTROY {
… …
435I<rxvt-unicode> distribution. 511I<rxvt-unicode> distribution.
436 512
437I<rxvt-unicode> also cheats a bit by not providing blocking access to 513I<rxvt-unicode> also cheats a bit by not providing blocking access to
438condition variables: code blocking while waiting for a condition will 514condition variables: code blocking while waiting for a condition will
439C<die>. This still works with most modules/usages, and blocking calls must 515C<die>. This still works with most modules/usages, and blocking calls must
440not be in an interactive appliation, so it makes sense. 516not be in an interactive application, so it makes sense.
441 517
442=head1 ENVIRONMENT VARIABLES 518=head1 ENVIRONMENT VARIABLES
443 519
444The following environment variables are used by this module: 520The following environment variables are used by this module:
445 521
… …
562 638
5631. Blocking: 6391. Blocking:
564 640
565 my $data = $fcp->client_get ($url); 641 my $data = $fcp->client_get ($url);
566 642
5672. Blocking, but parallelizing: 6432. Blocking, but running in parallel:
568 644
569 my @datas = map $_->result, 645 my @datas = map $_->result,
570 map $fcp->txn_client_get ($_), 646 map $fcp->txn_client_get ($_),
571 @urls; 647 @urls;
572 648
573Both blocking examples work without the module user having to know 649Both blocking examples work without the module user having to know
574anything about events. 650anything about events.
575 651
5763a. Event-based in a main program, using any support Event module: 6523a. Event-based in a main program, using any supported event module:
577 653
578 use Event; 654 use EV;
579 655
580 $fcp->txn_client_get ($url)->cb (sub { 656 $fcp->txn_client_get ($url)->cb (sub {
581 my $txn = shift; 657 my $txn = shift;
582 my $data = $txn->result; 658 my $data = $txn->result;
583 ... 659 ...
584 }); 660 });
585 661
586 Event::loop; 662 EV::loop;
587 663
5883b. The module user could use AnyEvent, too: 6643b. The module user could use AnyEvent, too:
589 665
590 use AnyEvent; 666 use AnyEvent;
591 667
… …
598 674
599 $quit->wait; 675 $quit->wait;
600 676
601=head1 SEE ALSO 677=head1 SEE ALSO
602 678
603Event modules: L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>. 679Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
680L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>.
604 681
605Implementations: L<AnyEvent::Impl::Coro>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>. 682Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
683L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>,
684L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>.
606 685
607Nontrivial usage example: L<Net::FCP>. 686Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
608 687
609=head1 688=head1
610 689
611=cut 690=cut
612 691

Diff Legend

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