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.49 by root, Mon Apr 14 19:11:15 2008 UTC

… …
18 18
19 my $w = AnyEvent->condvar; # stores wether a condition was flagged 19 my $w = AnyEvent->condvar; # stores wether 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
… …
58model>, AnyEvent also is free of bloat and policy: with POE or similar 57model>, AnyEvent also is free of bloat and policy: with POE or similar
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.
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.
63 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
… …
176=item $cv->wait 179=item $cv->wait
177 180
178Wait (blocking if necessary) until the C<< ->broadcast >> method has been 181Wait (blocking if necessary) until the C<< ->broadcast >> method has been
179called on c<$cv>, while servicing other watchers normally. 182called on c<$cv>, while servicing other watchers normally.
180 183
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 184You can only wait once on a condition - additional calls will return
189immediately. 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).
190 201
191=item $cv->broadcast 202=item $cv->broadcast
192 203
193Flag the condition as ready - a running C<< ->wait >> and all further 204Flag 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 205calls to C<wait> will return after this method has been called. If nobody
… …
249 260
250 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 261 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
251 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).
252 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. 263 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
253 AnyEvent::Impl::Event based on Event, also second best choice :) 264 AnyEvent::Impl::Event based on Event, also second best choice :)
254 AnyEvent::Impl::Glib based on Glib, second-best choice. 265 AnyEvent::Impl::Glib based on Glib, third-best choice.
255 AnyEvent::Impl::Tk based on Tk, very bad choice. 266 AnyEvent::Impl::Tk based on Tk, very bad choice.
256 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 267 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
257 268
258=item AnyEvent::detect 269=item AnyEvent::detect
259 270
260Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if 271Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
261necessary. You should only call this function right before you would have 272necessary. You should only call this function right before you would have
… …
631 642
6321. Blocking: 6431. Blocking:
633 644
634 my $data = $fcp->client_get ($url); 645 my $data = $fcp->client_get ($url);
635 646
6362. Blocking, but parallelizing: 6472. Blocking, but running in parallel:
637 648
638 my @datas = map $_->result, 649 my @datas = map $_->result,
639 map $fcp->txn_client_get ($_), 650 map $fcp->txn_client_get ($_),
640 @urls; 651 @urls;
641 652
642Both blocking examples work without the module user having to know 653Both blocking examples work without the module user having to know
643anything about events. 654anything about events.
644 655
6453a. Event-based in a main program, using any support Event module: 6563a. Event-based in a main program, using any supported event module:
646 657
647 use Event; 658 use EV;
648 659
649 $fcp->txn_client_get ($url)->cb (sub { 660 $fcp->txn_client_get ($url)->cb (sub {
650 my $txn = shift; 661 my $txn = shift;
651 my $data = $txn->result; 662 my $data = $txn->result;
652 ... 663 ...
653 }); 664 });
654 665
655 Event::loop; 666 EV::loop;
656 667
6573b. The module user could use AnyEvent, too: 6683b. The module user could use AnyEvent, too:
658 669
659 use AnyEvent; 670 use AnyEvent;
660 671
… …
667 678
668 $quit->wait; 679 $quit->wait;
669 680
670=head1 SEE ALSO 681=head1 SEE ALSO
671 682
672Event 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>.
673 685
674Implementations: 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>.
675 689
676Nontrivial usage example: L<Net::FCP>. 690Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
677 691
678=head1 692=head1
679 693
680=cut 694=cut
681 695

Diff Legend

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