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.14 by root, Mon Oct 30 20:52:24 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:
… …
89 chomp (my $input = <STDIN>); 130 chomp (my $input = <STDIN>);
90 warn "read: $input\n"; 131 warn "read: $input\n";
91 undef $w; 132 undef $w;
92 }); 133 });
93 134
94=head2 TIMER WATCHERS 135=head2 TIME WATCHERS
95 136
96You can create a timer watcher by calling the C<< AnyEvent->timer >> 137You can create a time watcher by calling the C<< AnyEvent->timer >>
97method with the following mandatory arguments: 138method with the following mandatory arguments:
98 139
99C<after> after how many seconds (fractions are supported) should the timer 140C<after> after how many seconds (fractions are supported) should the timer
100activate. C<cb> the callback to invoke. 141activate. C<cb> the callback to invoke.
101 142
… …
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
… …
154 # do something such as adding a timer 209 # do something such as adding a timer
155 # or socket watcher the calls $result_ready->broadcast 210 # or socket watcher the calls $result_ready->broadcast
156 # when the "result" is ready. 211 # when the "result" is ready.
157 212
158 $result_ready->wait; 213 $result_ready->wait;
214
215=back
216
217=head2 SIGNAL WATCHERS
218
219You can listen for signals using a signal watcher, C<signal> is the signal
220I<name> without any C<SIG> prefix. Multiple signals events can be clumped
221together into one callback invocation, and callback invocation might or
222might not be asynchronous.
223
224These watchers might use C<%SIG>, so programs overwriting those signals
225directly will likely not work correctly.
226
227Example: exit on SIGINT
228
229 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
230
231=head2 CHILD PROCESS WATCHERS
232
233You can also listen for the status of a child process specified by the
234C<pid> argument (or any child if the pid argument is 0). The watcher will
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).
238
239Example: wait for pid 1333
240
241 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
242
243=head1 GLOBALS
244
245=over 4
246
247=item $AnyEvent::MODEL
248
249Contains C<undef> until the first watcher is being created. Then it
250contains the event model that is being used, which is the name of the
251Perl class implementing the model. This class is usually one of the
252C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
253AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
254
255The known classes so far are:
256
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).
260 AnyEvent::Impl::Event based on Event, also second best choice :)
261 AnyEvent::Impl::Glib based on Glib, third-best choice.
262 AnyEvent::Impl::Tk based on Tk, very bad choice.
263 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
264
265=item AnyEvent::detect
266
267Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
268necessary. You should only call this function right before you would have
269created an AnyEvent watcher anyway, that is, very late at runtime.
159 270
160=back 271=back
161 272
162=head1 WHAT TO DO IN A MODULE 273=head1 WHAT TO DO IN A MODULE
163 274
… …
192=cut 303=cut
193 304
194package AnyEvent; 305package AnyEvent;
195 306
196no warnings; 307no warnings;
197use strict 'vars'; 308use strict;
309
198use Carp; 310use Carp;
199 311
200our $VERSION = '1.02'; 312our $VERSION = '3.1';
201our $MODEL; 313our $MODEL;
202 314
203our $AUTOLOAD; 315our $AUTOLOAD;
204our @ISA; 316our @ISA;
205 317
206our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 318our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
207 319
208our @REGISTRY; 320our @REGISTRY;
209 321
210my @models = ( 322my @models = (
323 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
211 [Coro::Event:: => AnyEvent::Impl::Coro::], 324 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
325 [EV:: => AnyEvent::Impl::EV::],
212 [Event:: => AnyEvent::Impl::Event::], 326 [Event:: => AnyEvent::Impl::Event::],
213 [Glib:: => AnyEvent::Impl::Glib::], 327 [Glib:: => AnyEvent::Impl::Glib::],
214 [Tk:: => AnyEvent::Impl::Tk::], 328 [Tk:: => AnyEvent::Impl::Tk::],
215 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 329 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
216); 330);
217 331
218our %method = map +($_ => 1), qw(io timer condvar broadcast wait DESTROY); 332our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
219 333
220sub AUTOLOAD { 334sub detect() {
221 $AUTOLOAD =~ s/.*://;
222
223 $method{$AUTOLOAD}
224 or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
225
226 unless ($MODEL) { 335 unless ($MODEL) {
336 no strict 'refs';
337
227 # check for already loaded models 338 # check for already loaded models
228 for (@REGISTRY, @models) { 339 for (@REGISTRY, @models) {
229 my ($package, $model) = @$_; 340 my ($package, $model) = @$_;
230 if (${"$package\::VERSION"} > 0) { 341 if (${"$package\::VERSION"} > 0) {
231 if (eval "require $model") { 342 if (eval "require $model") {
… …
239 unless ($MODEL) { 350 unless ($MODEL) {
240 # try to load a model 351 # try to load a model
241 352
242 for (@REGISTRY, @models) { 353 for (@REGISTRY, @models) {
243 my ($package, $model) = @$_; 354 my ($package, $model) = @$_;
355 if (eval "require $package"
356 and ${"$package\::VERSION"} > 0
244 if (eval "require $model") { 357 and eval "require $model") {
245 $MODEL = $model; 358 $MODEL = $model;
246 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;
247 last; 360 last;
248 } 361 }
249 } 362 }
250 363
251 $MODEL 364 $MODEL
252 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: 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.";
253 } 366 }
367
368 unshift @ISA, $MODEL;
369 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
254 } 370 }
255 371
256 @ISA = $MODEL; 372 $MODEL
373}
374
375sub AUTOLOAD {
376 (my $func = $AUTOLOAD) =~ s/.*://;
377
378 $method{$func}
379 or croak "$func: not a valid method for AnyEvent objects";
380
381 detect unless $MODEL;
257 382
258 my $class = shift; 383 my $class = shift;
259 $class->$AUTOLOAD (@_); 384 $class->$func (@_);
385}
386
387package AnyEvent::Base;
388
389# default implementation for ->condvar, ->wait, ->broadcast
390
391sub condvar {
392 bless \my $flag, "AnyEvent::Base::CondVar"
393}
394
395sub AnyEvent::Base::CondVar::broadcast {
396 ${$_[0]}++;
397}
398
399sub AnyEvent::Base::CondVar::wait {
400 AnyEvent->one_event while !${$_[0]};
401}
402
403# default implementation for ->signal
404
405our %SIG_CB;
406
407sub signal {
408 my (undef, %arg) = @_;
409
410 my $signal = uc $arg{signal}
411 or Carp::croak "required option 'signal' is missing";
412
413 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
414 $SIG{$signal} ||= sub {
415 $_->() for values %{ $SIG_CB{$signal} || {} };
416 };
417
418 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
419}
420
421sub AnyEvent::Base::Signal::DESTROY {
422 my ($signal, $cb) = @{$_[0]};
423
424 delete $SIG_CB{$signal}{$cb};
425
426 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
427}
428
429# default implementation for ->child
430
431our %PID_CB;
432our $CHLD_W;
433our $CHLD_DELAY_W;
434our $PID_IDLE;
435our $WNOHANG;
436
437sub _child_wait {
438 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
439 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
440 (values %{ $PID_CB{0} || {} });
441 }
442
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 });
452}
453
454sub child {
455 my (undef, %arg) = @_;
456
457 defined (my $pid = $arg{pid} + 0)
458 or Carp::croak "required option 'pid' is missing";
459
460 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
461
462 unless ($WNOHANG) {
463 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
464 }
465
466 unless ($CHLD_W) {
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 }
471
472 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
473}
474
475sub AnyEvent::Base::Child::DESTROY {
476 my ($pid, $cb) = @{$_[0]};
477
478 delete $PID_CB{$pid}{$cb};
479 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
480
481 undef $CHLD_W unless keys %PID_CB;
260} 482}
261 483
262=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 484=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
263 485
264If you need to support another event library which isn't directly 486If you need to support another event library which isn't directly
… …
275This tells AnyEvent to (literally) use the C<urxvt::anyevent::> 497This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
276package/class when it finds the C<urxvt> package/module is loaded. When 498package/class when it finds the C<urxvt> package/module is loaded. When
277AnyEvent is loaded and asked to find a suitable event model, it will 499AnyEvent is loaded and asked to find a suitable event model, it will
278first check for the presence of urxvt. 500first check for the presence of urxvt.
279 501
280The class should prove implementations for all watcher types (see 502The class should provide implementations for all watcher types (see
281L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib> 503L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
282(Source code) and so on for actual examples, use C<perldoc -m 504(Source code) and so on for actual examples, use C<perldoc -m
283AnyEvent::Impl::Glib> to see the sources). 505AnyEvent::Impl::Glib> to see the sources).
284 506
285The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt) 507The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
… …
289I<rxvt-unicode> distribution. 511I<rxvt-unicode> distribution.
290 512
291I<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
292condition variables: code blocking while waiting for a condition will 514condition variables: code blocking while waiting for a condition will
293C<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
294not be in an interactive appliation, so it makes sense. 516not be in an interactive application, so it makes sense.
295 517
296=head1 ENVIRONMENT VARIABLES 518=head1 ENVIRONMENT VARIABLES
297 519
298The following environment variables are used by this module: 520The following environment variables are used by this module:
299 521
… …
416 638
4171. Blocking: 6391. Blocking:
418 640
419 my $data = $fcp->client_get ($url); 641 my $data = $fcp->client_get ($url);
420 642
4212. Blocking, but parallelizing: 6432. Blocking, but running in parallel:
422 644
423 my @datas = map $_->result, 645 my @datas = map $_->result,
424 map $fcp->txn_client_get ($_), 646 map $fcp->txn_client_get ($_),
425 @urls; 647 @urls;
426 648
427Both blocking examples work without the module user having to know 649Both blocking examples work without the module user having to know
428anything about events. 650anything about events.
429 651
4303a. Event-based in a main program, using any support Event module: 6523a. Event-based in a main program, using any supported event module:
431 653
432 use Event; 654 use EV;
433 655
434 $fcp->txn_client_get ($url)->cb (sub { 656 $fcp->txn_client_get ($url)->cb (sub {
435 my $txn = shift; 657 my $txn = shift;
436 my $data = $txn->result; 658 my $data = $txn->result;
437 ... 659 ...
438 }); 660 });
439 661
440 Event::loop; 662 EV::loop;
441 663
4423b. The module user could use AnyEvent, too: 6643b. The module user could use AnyEvent, too:
443 665
444 use AnyEvent; 666 use AnyEvent;
445 667
… …
452 674
453 $quit->wait; 675 $quit->wait;
454 676
455=head1 SEE ALSO 677=head1 SEE ALSO
456 678
457Event 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>.
458 681
459Implementations: 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>.
460 685
461Nontrivial usage example: L<Net::FCP>. 686Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
462 687
463=head1 688=head1
464 689
465=cut 690=cut
466 691

Diff Legend

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