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.42 by root, Mon Apr 7 19:40:12 2008 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 22
23=head1 WHY YOU SHOULD USE THIS MODULE 23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24 24
25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26nowadays. So what is different about AnyEvent? 26nowadays. So what is different about AnyEvent?
27 27
28Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of 28Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
… …
58modules, you get an enourmous amount of code and strict rules you have 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 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 60offering the functionality that is useful, in as thin as a wrapper as
61technically possible. 61technically possible.
62 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
63 67
64=head1 DESCRIPTION 68=head1 DESCRIPTION
65 69
66L<AnyEvent> provides an identical interface to multiple event loops. This 70L<AnyEvent> provides an identical interface to multiple event loops. This
67allows module authors to utilise an event loop without forcing module 71allows module authors to utilise an event loop without forcing module
… …
70 74
71The interface itself is vaguely similar but not identical to the Event 75The interface itself is vaguely similar but not identical to the Event
72module. 76module.
73 77
74On 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
75loaded event loop by probing wether any of the following modules is 79loaded event loop by probing whether any of the following modules is
76loaded: 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
77used. 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
78order given. The first one that could be successfully loaded will be 82modules in the order given. The first one that could be successfully
79used. 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
80event loop, which is also not very efficient. 84to a pure-perl event loop, which is also not very efficient.
81 85
82Because AnyEvent first checks for modules that are already loaded, loading 86Because AnyEvent first checks for modules that are already loaded, loading
83an Event model explicitly before first using AnyEvent will likely make 87an Event model explicitly before first using AnyEvent will likely make
84that model the default. For example: 88that model the default. For example:
85 89
… …
114C<fh> the Perl I<filehandle> (not filedescriptor) to watch for 118C<fh> the Perl I<filehandle> (not filedescriptor) to watch for
115events. 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
116a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback 120a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
117to invoke everytime the filehandle becomes ready. 121to invoke everytime the filehandle becomes ready.
118 122
119Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on
120a socket you can have one r + one w, not any more (limitation comes from
121Tk - if you are sure you are not using Tk this limitation is gone).
122
123Filehandles 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
124filehandle exists, too. 124filehandle exists, too.
125 125
126Example: 126Example:
127 127
… …
175=item $cv->wait 175=item $cv->wait
176 176
177Wait (blocking if necessary) until the C<< ->broadcast >> method has been 177Wait (blocking if necessary) until the C<< ->broadcast >> method has been
178called on c<$cv>, while servicing other watchers normally. 178called on c<$cv>, while servicing other watchers normally.
179 179
180Not all event models support a blocking wait - some die in that case, so
181if you are using this from a module, never require a blocking wait, but
182let the caller decide wether the call will block or not (for example,
183by coupling condition variables with some kind of request results and
184supporting callbacks so the caller knows that getting the result will not
185block, while still suppporting blockign waits if the caller so desires).
186
187You can only wait once on a condition - additional calls will return 180You can only wait once on a condition - additional calls will return
188immediately. 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).
189 197
190=item $cv->broadcast 198=item $cv->broadcast
191 199
192Flag the condition as ready - a running C<< ->wait >> and all further 200Flag the condition as ready - a running C<< ->wait >> and all further
193calls 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
… …
245AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 253AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
246 254
247The known classes so far are: 255The known classes so far are:
248 256
249 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 257 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
258 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
250 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 259 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
251 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
252 AnyEvent::Impl::Event based on Event, also second best choice :) 260 AnyEvent::Impl::Event based on Event, also second best choice :)
253 AnyEvent::Impl::Glib based on Glib, second-best choice. 261 AnyEvent::Impl::Glib based on Glib, third-best choice.
254 AnyEvent::Impl::Tk based on Tk, very bad choice. 262 AnyEvent::Impl::Tk based on Tk, very bad choice.
255 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 263 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
256 264
257=item AnyEvent::detect 265=item AnyEvent::detect
258 266
259Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if 267Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
260necessary. You should only call this function right before you would have 268necessary. You should only call this function right before you would have
… …
299no warnings; 307no warnings;
300use strict; 308use strict;
301 309
302use Carp; 310use Carp;
303 311
304our $VERSION = '3.0'; 312our $VERSION = '3.1';
305our $MODEL; 313our $MODEL;
306 314
307our $AUTOLOAD; 315our $AUTOLOAD;
308our @ISA; 316our @ISA;
309 317
… …
311 319
312our @REGISTRY; 320our @REGISTRY;
313 321
314my @models = ( 322my @models = (
315 [Coro::EV:: => AnyEvent::Impl::CoroEV::], 323 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
324 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
316 [EV:: => AnyEvent::Impl::EV::], 325 [EV:: => AnyEvent::Impl::EV::],
317 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
318 [Event:: => AnyEvent::Impl::Event::], 326 [Event:: => AnyEvent::Impl::Event::],
319 [Glib:: => AnyEvent::Impl::Glib::], 327 [Glib:: => AnyEvent::Impl::Glib::],
320 [Tk:: => AnyEvent::Impl::Tk::], 328 [Tk:: => AnyEvent::Impl::Tk::],
321 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 329 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
322); 330);
… …
619 $txn->{finished}->wait; 627 $txn->{finished}->wait;
620 return $txn->{result}; 628 return $txn->{result};
621 629
622The 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)
623that occured during request processing. The C<result> method detects 631that occured during request processing. The C<result> method detects
624wether an exception as thrown (it is stored inside the $txn object) 632whether an exception as thrown (it is stored inside the $txn object)
625and just throws the exception, which means connection errors and other 633and just throws the exception, which means connection errors and other
626problems 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
627random callback. 635random callback.
628 636
629All of this enables the following usage styles: 637All of this enables the following usage styles:
630 638
6311. Blocking: 6391. Blocking:
632 640
633 my $data = $fcp->client_get ($url); 641 my $data = $fcp->client_get ($url);
634 642
6352. Blocking, but parallelizing: 6432. Blocking, but running in parallel:
636 644
637 my @datas = map $_->result, 645 my @datas = map $_->result,
638 map $fcp->txn_client_get ($_), 646 map $fcp->txn_client_get ($_),
639 @urls; 647 @urls;
640 648
641Both blocking examples work without the module user having to know 649Both blocking examples work without the module user having to know
642anything about events. 650anything about events.
643 651
6443a. Event-based in a main program, using any support Event module: 6523a. Event-based in a main program, using any supported event module:
645 653
646 use Event; 654 use EV;
647 655
648 $fcp->txn_client_get ($url)->cb (sub { 656 $fcp->txn_client_get ($url)->cb (sub {
649 my $txn = shift; 657 my $txn = shift;
650 my $data = $txn->result; 658 my $data = $txn->result;
651 ... 659 ...
652 }); 660 });
653 661
654 Event::loop; 662 EV::loop;
655 663
6563b. The module user could use AnyEvent, too: 6643b. The module user could use AnyEvent, too:
657 665
658 use AnyEvent; 666 use AnyEvent;
659 667
… …
666 674
667 $quit->wait; 675 $quit->wait;
668 676
669=head1 SEE ALSO 677=head1 SEE ALSO
670 678
671Event 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>.
672 681
673Implementations: 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>.
674 685
675Nontrivial usage example: L<Net::FCP>. 686Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
676 687
677=head1 688=head1
678 689
679=cut 690=cut
680 691

Diff Legend

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