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.48 by root, Mon Apr 14 19:00:23 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 (OR NOT) 23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24 24
… …
74 74
75The interface itself is vaguely similar but not identical to the Event 75The interface itself is vaguely similar but not identical to the Event
76module. 76module.
77 77
78On 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
79loaded event loop by probing wether any of the following modules is 79loaded event loop by probing whether any of the following modules is
80loaded: 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
81used. 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
82order given. The first one that could be successfully loaded will be 82modules in the order given. The first one that could be successfully
83used. 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
84event loop, which is also not very efficient. 84to a pure-perl event loop, which is also not very efficient.
85 85
86Because AnyEvent first checks for modules that are already loaded, loading 86Because AnyEvent first checks for modules that are already loaded, loading
87an Event model explicitly before first using AnyEvent will likely make 87an Event model explicitly before first using AnyEvent will likely make
88that model the default. For example: 88that model the default. For example:
89 89
… …
118C<fh> the Perl I<filehandle> (not filedescriptor) to watch for 118C<fh> the Perl I<filehandle> (not filedescriptor) to watch for
119events. 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
120a 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
121to invoke everytime the filehandle becomes ready. 121to invoke everytime the filehandle becomes ready.
122 122
123Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on
124a socket you can have one r + one w, not any more (limitation comes from
125Tk - if you are sure you are not using Tk this limitation is gone).
126
127Filehandles 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
128filehandle exists, too. 124filehandle exists, too.
129 125
130Example: 126Example:
131 127
… …
185immediately. 181immediately.
186 182
187Not all event models support a blocking wait - some die in that case 183Not all event models support a blocking wait - some die in that case
188(programs might want to do that so they stay interactive), so I<if you 184(programs might want to do that so they stay interactive), so I<if you
189are using this from a module, never require a blocking wait>, but let the 185are using this from a module, never require a blocking wait>, but let the
190caller decide wether the call will block or not (for example, by coupling 186caller decide whether the call will block or not (for example, by coupling
191condition variables with some kind of request results and supporting 187condition variables with some kind of request results and supporting
192callbacks so the caller knows that getting the result will not block, 188callbacks so the caller knows that getting the result will not block,
193while still suppporting blocking waits if the caller so desires). 189while still suppporting blocking waits if the caller so desires).
194 190
195Another reason I<never> to C<< ->wait >> in a module is that you cannot 191Another reason I<never> to C<< ->wait >> in a module is that you cannot
… …
257AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 253AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
258 254
259The known classes so far are: 255The known classes so far are:
260 256
261 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.
262 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).
263 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
264 AnyEvent::Impl::Event based on Event, also second best choice :) 260 AnyEvent::Impl::Event based on Event, also second best choice :)
265 AnyEvent::Impl::Glib based on Glib, third-best choice. 261 AnyEvent::Impl::Glib based on Glib, third-best choice.
266 AnyEvent::Impl::Tk based on Tk, very bad choice. 262 AnyEvent::Impl::Tk based on Tk, very bad choice.
267 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. 263 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
268 264
… …
311no warnings; 307no warnings;
312use strict; 308use strict;
313 309
314use Carp; 310use Carp;
315 311
316our $VERSION = '3.0'; 312our $VERSION = '3.1';
317our $MODEL; 313our $MODEL;
318 314
319our $AUTOLOAD; 315our $AUTOLOAD;
320our @ISA; 316our @ISA;
321 317
… …
323 319
324our @REGISTRY; 320our @REGISTRY;
325 321
326my @models = ( 322my @models = (
327 [Coro::EV:: => AnyEvent::Impl::CoroEV::], 323 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
324 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
328 [EV:: => AnyEvent::Impl::EV::], 325 [EV:: => AnyEvent::Impl::EV::],
329 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
330 [Event:: => AnyEvent::Impl::Event::], 326 [Event:: => AnyEvent::Impl::Event::],
331 [Glib:: => AnyEvent::Impl::Glib::], 327 [Glib:: => AnyEvent::Impl::Glib::],
332 [Tk:: => AnyEvent::Impl::Tk::], 328 [Tk:: => AnyEvent::Impl::Tk::],
333 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 329 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
334); 330);
… …
631 $txn->{finished}->wait; 627 $txn->{finished}->wait;
632 return $txn->{result}; 628 return $txn->{result};
633 629
634The 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)
635that occured during request processing. The C<result> method detects 631that occured during request processing. The C<result> method detects
636wether an exception as thrown (it is stored inside the $txn object) 632whether an exception as thrown (it is stored inside the $txn object)
637and just throws the exception, which means connection errors and other 633and just throws the exception, which means connection errors and other
638problems 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
639random callback. 635random callback.
640 636
641All of this enables the following usage styles: 637All of this enables the following usage styles:
642 638
6431. Blocking: 6391. Blocking:
644 640
645 my $data = $fcp->client_get ($url); 641 my $data = $fcp->client_get ($url);
646 642
6472. Blocking, but parallelizing: 6432. Blocking, but running in parallel:
648 644
649 my @datas = map $_->result, 645 my @datas = map $_->result,
650 map $fcp->txn_client_get ($_), 646 map $fcp->txn_client_get ($_),
651 @urls; 647 @urls;
652 648
653Both blocking examples work without the module user having to know 649Both blocking examples work without the module user having to know
654anything about events. 650anything about events.
655 651
6563a. Event-based in a main program, using any support Event module: 6523a. Event-based in a main program, using any supported event module:
657 653
658 use Event; 654 use EV;
659 655
660 $fcp->txn_client_get ($url)->cb (sub { 656 $fcp->txn_client_get ($url)->cb (sub {
661 my $txn = shift; 657 my $txn = shift;
662 my $data = $txn->result; 658 my $data = $txn->result;
663 ... 659 ...
664 }); 660 });
665 661
666 Event::loop; 662 EV::loop;
667 663
6683b. The module user could use AnyEvent, too: 6643b. The module user could use AnyEvent, too:
669 665
670 use AnyEvent; 666 use AnyEvent;
671 667
… …
678 674
679 $quit->wait; 675 $quit->wait;
680 676
681=head1 SEE ALSO 677=head1 SEE ALSO
682 678
683Event 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>.
684 681
685Implementations: 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>.
686 685
687Nontrivial usage example: L<Net::FCP>. 686Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
688 687
689=head1 688=head1
690 689
691=cut 690=cut
692 691

Diff Legend

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