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

Diff Legend

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