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.19 by root, Sun Dec 10 23:59:15 2006 UTC vs.
Revision 1.52 by root, Sat Apr 19 03:47:24 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
… …
14 14
15 my $w = AnyEvent->timer (after => $seconds, cb => sub { 15 my $w = AnyEvent->timer (after => $seconds, cb => sub {
16 ... 16 ...
17 }); 17 });
18 18
19 my $w = AnyEvent->condvar; # stores wether a condition was flagged 19 my $w = AnyEvent->condvar; # stores whether 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
… …
29 74
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 whether 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 whether 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
… …
160=back 215=back
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. 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.
166 223
167These watchers might use C<%SIG>, so programs overwriting those signals 224These watchers might use C<%SIG>, so programs overwriting those signals
168directly will likely not work correctly. 225directly will likely not work correctly.
169 226
170Example: exit on SIGINT 227Example: exit on SIGINT
171 228
172 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 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 $?" });
173 242
174=head1 GLOBALS 243=head1 GLOBALS
175 244
176=over 4 245=over 4
177 246
… …
183C<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
184AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 253AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
185 254
186The known classes so far are: 255The known classes so far are:
187 256
188 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).
189 AnyEvent::Impl::Event based on Event, also best choice :) 260 AnyEvent::Impl::Event based on Event, also second best choice :)
190 AnyEvent::Impl::Glib based on Glib, second-best choice. 261 AnyEvent::Impl::Glib based on Glib, third-best choice.
191 AnyEvent::Impl::Tk based on Tk, very bad choice. 262 AnyEvent::Impl::Tk based on Tk, very bad choice.
192 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 263 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
193 264
194=item AnyEvent::detect 265=item AnyEvent::detect
195 266
196Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if 267Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
197necessary. You should only call this function right before you would have 268necessary. You should only call this function right before you would have
… …
233 304
234package AnyEvent; 305package AnyEvent;
235 306
236no warnings; 307no warnings;
237use strict; 308use strict;
309
238use Carp; 310use Carp;
239 311
240our $VERSION = '2.5'; 312our $VERSION = '3.1';
241our $MODEL; 313our $MODEL;
242 314
243our $AUTOLOAD; 315our $AUTOLOAD;
244our @ISA; 316our @ISA;
245 317
246our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 318our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
247 319
248our @REGISTRY; 320our @REGISTRY;
249 321
250my @models = ( 322my @models = (
323 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
251 [Coro::Event:: => AnyEvent::Impl::Coro::], 324 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
325 [EV:: => AnyEvent::Impl::EV::],
252 [Event:: => AnyEvent::Impl::Event::], 326 [Event:: => AnyEvent::Impl::Event::],
253 [Glib:: => AnyEvent::Impl::Glib::], 327 [Glib:: => AnyEvent::Impl::Glib::],
254 [Tk:: => AnyEvent::Impl::Tk::], 328 [Tk:: => AnyEvent::Impl::Tk::],
255 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 329 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
256); 330);
… …
276 unless ($MODEL) { 350 unless ($MODEL) {
277 # try to load a model 351 # try to load a model
278 352
279 for (@REGISTRY, @models) { 353 for (@REGISTRY, @models) {
280 my ($package, $model) = @$_; 354 my ($package, $model) = @$_;
355 if (eval "require $package"
356 and ${"$package\::VERSION"} > 0
281 if (eval "require $model") { 357 and eval "require $model") {
282 $MODEL = $model; 358 $MODEL = $model;
283 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;
284 last; 360 last;
285 } 361 }
286 } 362 }
287 363
288 $MODEL 364 $MODEL
289 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.";
290 } 366 }
291 367
292 unshift @ISA, $MODEL; 368 unshift @ISA, $MODEL;
293 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 369 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
294 } 370 }
… …
308 $class->$func (@_); 384 $class->$func (@_);
309} 385}
310 386
311package AnyEvent::Base; 387package AnyEvent::Base;
312 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
313# default implementation for signal 403# default implementation for ->signal
314 404
315our %SIG_CB; 405our %SIG_CB;
316 406
317sub signal { 407sub signal {
318 my (undef, %arg) = @_; 408 my (undef, %arg) = @_;
319 409
320 my $signal = uc $arg{signal} 410 my $signal = uc $arg{signal}
321 or Carp::croak "required option 'signal' is missing"; 411 or Carp::croak "required option 'signal' is missing";
322 412
323 my $w = bless [$signal, $arg{cb}], "AnyEvent::Base::Signal";
324
325 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 413 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
326 $SIG{$signal} ||= sub { 414 $SIG{$signal} ||= sub {
327 $_->() for values %{ $SIG_CB{$signal} }; 415 $_->() for values %{ $SIG_CB{$signal} || {} };
328 }; 416 };
329 417
330 $w 418 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
331} 419}
332 420
333sub AnyEvent::Base::Signal::DESTROY { 421sub AnyEvent::Base::Signal::DESTROY {
334 my ($signal, $cb) = @{$_[0]}; 422 my ($signal, $cb) = @{$_[0]};
335 423
336 delete $SIG_CB{$signal}{$cb}; 424 delete $SIG_CB{$signal}{$cb};
337 425
338 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} }; 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;
339} 482}
340 483
341=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 484=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
342 485
343If you need to support another event library which isn't directly 486If you need to support another event library which isn't directly
… …
368I<rxvt-unicode> distribution. 511I<rxvt-unicode> distribution.
369 512
370I<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
371condition variables: code blocking while waiting for a condition will 514condition variables: code blocking while waiting for a condition will
372C<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
373not be in an interactive appliation, so it makes sense. 516not be in an interactive application, so it makes sense.
374 517
375=head1 ENVIRONMENT VARIABLES 518=head1 ENVIRONMENT VARIABLES
376 519
377The following environment variables are used by this module: 520The following environment variables are used by this module:
378 521
… …
484 $txn->{finished}->wait; 627 $txn->{finished}->wait;
485 return $txn->{result}; 628 return $txn->{result};
486 629
487The actual code goes further and collects all errors (C<die>s, exceptions) 630The actual code goes further and collects all errors (C<die>s, exceptions)
488that occured during request processing. The C<result> method detects 631that occured during request processing. The C<result> method detects
489wether an exception as thrown (it is stored inside the $txn object) 632whether an exception as thrown (it is stored inside the $txn object)
490and just throws the exception, which means connection errors and other 633and just throws the exception, which means connection errors and other
491problems get reported tot he code that tries to use the result, not in a 634problems get reported tot he code that tries to use the result, not in a
492random callback. 635random callback.
493 636
494All of this enables the following usage styles: 637All of this enables the following usage styles:
495 638
4961. Blocking: 6391. Blocking:
497 640
498 my $data = $fcp->client_get ($url); 641 my $data = $fcp->client_get ($url);
499 642
5002. Blocking, but parallelizing: 6432. Blocking, but running in parallel:
501 644
502 my @datas = map $_->result, 645 my @datas = map $_->result,
503 map $fcp->txn_client_get ($_), 646 map $fcp->txn_client_get ($_),
504 @urls; 647 @urls;
505 648
506Both blocking examples work without the module user having to know 649Both blocking examples work without the module user having to know
507anything about events. 650anything about events.
508 651
5093a. Event-based in a main program, using any support Event module: 6523a. Event-based in a main program, using any supported event module:
510 653
511 use Event; 654 use EV;
512 655
513 $fcp->txn_client_get ($url)->cb (sub { 656 $fcp->txn_client_get ($url)->cb (sub {
514 my $txn = shift; 657 my $txn = shift;
515 my $data = $txn->result; 658 my $data = $txn->result;
516 ... 659 ...
517 }); 660 });
518 661
519 Event::loop; 662 EV::loop;
520 663
5213b. The module user could use AnyEvent, too: 6643b. The module user could use AnyEvent, too:
522 665
523 use AnyEvent; 666 use AnyEvent;
524 667
… …
531 674
532 $quit->wait; 675 $quit->wait;
533 676
534=head1 SEE ALSO 677=head1 SEE ALSO
535 678
536Event 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>.
537 681
538Implementations: 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>.
539 685
540Nontrivial usage example: L<Net::FCP>. 686Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
541 687
542=head1 688=head1
543 689
544=cut 690=cut
545 691

Diff Legend

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