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.44 by root, Mon Apr 7 19:42:18 2008 UTC vs.
Revision 1.49 by root, Mon Apr 14 19:11:15 2008 UTC

… …
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 is arguably somewhat useful 63Of course, if you want lots of policy (this can arguably be somewhat
64in many cases) and you want to force your users to the one and only event 64useful) and you want to force your users to use the one and only event
65model your module forces on them, you should I<not> use this module. 65model, you should I<not> use this module.
66 66
67 67
68=head1 DESCRIPTION 68=head1 DESCRIPTION
69 69
70L<AnyEvent> provides an identical interface to multiple event loops. This 70L<AnyEvent> provides an identical interface to multiple event loops. This
… …
179=item $cv->wait 179=item $cv->wait
180 180
181Wait (blocking if necessary) until the C<< ->broadcast >> method has been 181Wait (blocking if necessary) until the C<< ->broadcast >> method has been
182called on c<$cv>, while servicing other watchers normally. 182called on c<$cv>, while servicing other watchers normally.
183 183
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 184You can only wait once on a condition - additional calls will return
192immediately. 185immediately.
186
187Not 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
189are 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
191condition variables with some kind of request results and supporting
192callbacks so the caller knows that getting the result will not block,
193while still suppporting blocking waits if the caller so desires).
194
195Another reason I<never> to C<< ->wait >> in a module is that you cannot
196sensibly have two C<< ->wait >>'s in parallel, as that would require
197multiple interpreters or coroutines/threads, none of which C<AnyEvent>
198can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
199explicitly support concurrent C<< ->wait >>'s from different coroutines,
200however).
193 201
194=item $cv->broadcast 202=item $cv->broadcast
195 203
196Flag the condition as ready - a running C<< ->wait >> and all further 204Flag 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 205calls to C<wait> will return after this method has been called. If nobody
… …
252 260
253 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 261 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
254 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 262 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
255 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. 263 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
256 AnyEvent::Impl::Event based on Event, also second best choice :) 264 AnyEvent::Impl::Event based on Event, also second best choice :)
257 AnyEvent::Impl::Glib based on Glib, second-best choice. 265 AnyEvent::Impl::Glib based on Glib, third-best choice.
258 AnyEvent::Impl::Tk based on Tk, very bad choice. 266 AnyEvent::Impl::Tk based on Tk, very bad choice.
259 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 267 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
260 268
261=item AnyEvent::detect 269=item AnyEvent::detect
262 270
263Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if 271Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
264necessary. You should only call this function right before you would have 272necessary. You should only call this function right before you would have
… …
634 642
6351. Blocking: 6431. Blocking:
636 644
637 my $data = $fcp->client_get ($url); 645 my $data = $fcp->client_get ($url);
638 646
6392. Blocking, but parallelizing: 6472. Blocking, but running in parallel:
640 648
641 my @datas = map $_->result, 649 my @datas = map $_->result,
642 map $fcp->txn_client_get ($_), 650 map $fcp->txn_client_get ($_),
643 @urls; 651 @urls;
644 652
645Both blocking examples work without the module user having to know 653Both blocking examples work without the module user having to know
646anything about events. 654anything about events.
647 655
6483a. Event-based in a main program, using any support Event module: 6563a. Event-based in a main program, using any supported event module:
649 657
650 use Event; 658 use EV;
651 659
652 $fcp->txn_client_get ($url)->cb (sub { 660 $fcp->txn_client_get ($url)->cb (sub {
653 my $txn = shift; 661 my $txn = shift;
654 my $data = $txn->result; 662 my $data = $txn->result;
655 ... 663 ...
656 }); 664 });
657 665
658 Event::loop; 666 EV::loop;
659 667
6603b. The module user could use AnyEvent, too: 6683b. The module user could use AnyEvent, too:
661 669
662 use AnyEvent; 670 use AnyEvent;
663 671
… …
670 678
671 $quit->wait; 679 $quit->wait;
672 680
673=head1 SEE ALSO 681=head1 SEE ALSO
674 682
675Event modules: L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>. 683Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
684L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>.
676 685
677Implementations: L<AnyEvent::Impl::Coro>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>. 686Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
687L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>,
688L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>.
678 689
679Nontrivial usage example: L<Net::FCP>. 690Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
680 691
681=head1 692=head1
682 693
683=cut 694=cut
684 695

Diff Legend

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