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.46 by root, Mon Apr 7 19:46:24 2008 UTC vs.
Revision 1.51 by root, Wed Apr 16 15:10:10 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
… …
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 wether 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
… …
179=item $cv->wait 175=item $cv->wait
180 176
181Wait (blocking if necessary) until the C<< ->broadcast >> method has been 177Wait (blocking if necessary) until the C<< ->broadcast >> method has been
182called on c<$cv>, while servicing other watchers normally. 178called on c<$cv>, while servicing other watchers normally.
183 179
184Not all event models support a blocking wait - some die in that case, so
185if you are using this from a module, never require a blocking wait, but
186let the caller decide wether the call will block or not (for example,
187by coupling condition variables with some kind of request results and
188supporting callbacks so the caller knows that getting the result will not
189block, while still suppporting blockign waits if the caller so desires).
190
191You can only wait once on a condition - additional calls will return 180You can only wait once on a condition - additional calls will return
192immediately. 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 wether 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).
193 197
194=item $cv->broadcast 198=item $cv->broadcast
195 199
196Flag the condition as ready - a running C<< ->wait >> and all further 200Flag the condition as ready - a running C<< ->wait >> and all further
197calls 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
… …
249AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 253AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
250 254
251The known classes so far are: 255The known classes so far are:
252 256
253 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.
254 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).
255 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
256 AnyEvent::Impl::Event based on Event, also second best choice :) 260 AnyEvent::Impl::Event based on Event, also second best choice :)
257 AnyEvent::Impl::Glib based on Glib, second-best choice. 261 AnyEvent::Impl::Glib based on Glib, third-best choice.
258 AnyEvent::Impl::Tk based on Tk, very bad choice. 262 AnyEvent::Impl::Tk based on Tk, very bad choice.
259 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 263 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
260 264
261=item AnyEvent::detect 265=item AnyEvent::detect
262 266
263Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if 267Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
264necessary. You should only call this function right before you would have 268necessary. You should only call this function right before you would have
… …
303no warnings; 307no warnings;
304use strict; 308use strict;
305 309
306use Carp; 310use Carp;
307 311
308our $VERSION = '3.0'; 312our $VERSION = '3.1';
309our $MODEL; 313our $MODEL;
310 314
311our $AUTOLOAD; 315our $AUTOLOAD;
312our @ISA; 316our @ISA;
313 317
… …
315 319
316our @REGISTRY; 320our @REGISTRY;
317 321
318my @models = ( 322my @models = (
319 [Coro::EV:: => AnyEvent::Impl::CoroEV::], 323 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
324 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
320 [EV:: => AnyEvent::Impl::EV::], 325 [EV:: => AnyEvent::Impl::EV::],
321 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
322 [Event:: => AnyEvent::Impl::Event::], 326 [Event:: => AnyEvent::Impl::Event::],
323 [Glib:: => AnyEvent::Impl::Glib::], 327 [Glib:: => AnyEvent::Impl::Glib::],
324 [Tk:: => AnyEvent::Impl::Tk::], 328 [Tk:: => AnyEvent::Impl::Tk::],
325 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 329 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
326); 330);
… …
634 638
6351. Blocking: 6391. Blocking:
636 640
637 my $data = $fcp->client_get ($url); 641 my $data = $fcp->client_get ($url);
638 642
6392. Blocking, but parallelizing: 6432. Blocking, but running in parallel:
640 644
641 my @datas = map $_->result, 645 my @datas = map $_->result,
642 map $fcp->txn_client_get ($_), 646 map $fcp->txn_client_get ($_),
643 @urls; 647 @urls;
644 648
645Both blocking examples work without the module user having to know 649Both blocking examples work without the module user having to know
646anything about events. 650anything about events.
647 651
6483a. Event-based in a main program, using any support Event module: 6523a. Event-based in a main program, using any supported event module:
649 653
650 use Event; 654 use EV;
651 655
652 $fcp->txn_client_get ($url)->cb (sub { 656 $fcp->txn_client_get ($url)->cb (sub {
653 my $txn = shift; 657 my $txn = shift;
654 my $data = $txn->result; 658 my $data = $txn->result;
655 ... 659 ...
656 }); 660 });
657 661
658 Event::loop; 662 EV::loop;
659 663
6603b. The module user could use AnyEvent, too: 6643b. The module user could use AnyEvent, too:
661 665
662 use AnyEvent; 666 use AnyEvent;
663 667
… …
670 674
671 $quit->wait; 675 $quit->wait;
672 676
673=head1 SEE ALSO 677=head1 SEE ALSO
674 678
675Event 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>.
676 681
677Implementations: 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>.
678 685
679Nontrivial usage example: L<Net::FCP>. 686Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
680 687
681=head1 688=head1
682 689
683=cut 690=cut
684 691

Diff Legend

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