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.39 by root, Mon Jan 28 12:32:20 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
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
… …
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> the 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
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
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:
86 127
… …
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
… …
198AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 253AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
199 254
200The known classes so far are: 255The known classes so far are:
201 256
202 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.
203 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).
204 AnyEvent::Impl::Coro based on Coro::Event, second best choice.
205 AnyEvent::Impl::Event based on Event, also second best choice :) 260 AnyEvent::Impl::Event based on Event, also second best choice :)
206 AnyEvent::Impl::Glib based on Glib, second-best choice. 261 AnyEvent::Impl::Glib based on Glib, third-best choice.
207 AnyEvent::Impl::Tk based on Tk, very bad choice. 262 AnyEvent::Impl::Tk based on Tk, very bad choice.
208 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 263 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
209 264
210=item AnyEvent::detect 265=item AnyEvent::detect
211 266
212Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if 267Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
213necessary. You should only call this function right before you would have 268necessary. You should only call this function right before you would have
… …
252no warnings; 307no warnings;
253use strict; 308use strict;
254 309
255use Carp; 310use Carp;
256 311
257our $VERSION = '2.9'; 312our $VERSION = '3.1';
258our $MODEL; 313our $MODEL;
259 314
260our $AUTOLOAD; 315our $AUTOLOAD;
261our @ISA; 316our @ISA;
262 317
… …
264 319
265our @REGISTRY; 320our @REGISTRY;
266 321
267my @models = ( 322my @models = (
268 [Coro::EV:: => AnyEvent::Impl::CoroEV::], 323 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
324 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
269 [EV:: => AnyEvent::Impl::EV::], 325 [EV:: => AnyEvent::Impl::EV::],
270 [Coro::Event:: => AnyEvent::Impl::Coro::],
271 [Event:: => AnyEvent::Impl::Event::], 326 [Event:: => AnyEvent::Impl::Event::],
272 [Glib:: => AnyEvent::Impl::Glib::], 327 [Glib:: => AnyEvent::Impl::Glib::],
273 [Tk:: => AnyEvent::Impl::Tk::], 328 [Tk:: => AnyEvent::Impl::Tk::],
274 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 329 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
275); 330);
… …
572 $txn->{finished}->wait; 627 $txn->{finished}->wait;
573 return $txn->{result}; 628 return $txn->{result};
574 629
575The 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)
576that occured during request processing. The C<result> method detects 631that occured during request processing. The C<result> method detects
577wether an exception as thrown (it is stored inside the $txn object) 632whether an exception as thrown (it is stored inside the $txn object)
578and just throws the exception, which means connection errors and other 633and just throws the exception, which means connection errors and other
579problems 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
580random callback. 635random callback.
581 636
582All of this enables the following usage styles: 637All of this enables the following usage styles:
583 638
5841. Blocking: 6391. Blocking:
585 640
586 my $data = $fcp->client_get ($url); 641 my $data = $fcp->client_get ($url);
587 642
5882. Blocking, but parallelizing: 6432. Blocking, but running in parallel:
589 644
590 my @datas = map $_->result, 645 my @datas = map $_->result,
591 map $fcp->txn_client_get ($_), 646 map $fcp->txn_client_get ($_),
592 @urls; 647 @urls;
593 648
594Both blocking examples work without the module user having to know 649Both blocking examples work without the module user having to know
595anything about events. 650anything about events.
596 651
5973a. Event-based in a main program, using any support Event module: 6523a. Event-based in a main program, using any supported event module:
598 653
599 use Event; 654 use EV;
600 655
601 $fcp->txn_client_get ($url)->cb (sub { 656 $fcp->txn_client_get ($url)->cb (sub {
602 my $txn = shift; 657 my $txn = shift;
603 my $data = $txn->result; 658 my $data = $txn->result;
604 ... 659 ...
605 }); 660 });
606 661
607 Event::loop; 662 EV::loop;
608 663
6093b. The module user could use AnyEvent, too: 6643b. The module user could use AnyEvent, too:
610 665
611 use AnyEvent; 666 use AnyEvent;
612 667
… …
619 674
620 $quit->wait; 675 $quit->wait;
621 676
622=head1 SEE ALSO 677=head1 SEE ALSO
623 678
624Event 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>.
625 681
626Implementations: 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>.
627 685
628Nontrivial usage example: L<Net::FCP>. 686Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
629 687
630=head1 688=head1
631 689
632=cut 690=cut
633 691

Diff Legend

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