ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/README
(Generate patch)

Comparing AnyEvent/README (file contents):
Revision 1.12 by root, Fri Nov 9 19:37:05 2007 UTC vs.
Revision 1.15 by root, Wed Apr 16 15:10:10 2008 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 Event, Coro, Glib, Tk, Perl - various supported event loops 4 EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl - various supported
5 event loops
5 6
6SYNOPSIS 7SYNOPSIS
7 use AnyEvent; 8 use AnyEvent;
8 9
9 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub {
… …
15 }); 16 });
16 17
17 my $w = AnyEvent->condvar; # stores wether a condition was flagged 18 my $w = AnyEvent->condvar; # stores wether a condition was flagged
18 $w->wait; # enters "main loop" till $condvar gets ->broadcast 19 $w->wait; # enters "main loop" till $condvar gets ->broadcast
19 $w->broadcast; # wake up current and all future wait's 20 $w->broadcast; # wake up current and all future wait's
21
22WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent?
25
26 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
27 policy* and AnyEvent is *small and efficient*.
28
29 First and foremost, *AnyEvent is not an event model* itself, it only
30 interfaces to whatever event model the main program happens to use in a
31 pragmatic way. For event models and certain classes of immortals alike,
32 the statement "there can only be one" is a bitter reality, and AnyEvent
33 helps hiding the differences.
34
35 The goal of AnyEvent is to offer module authors the ability to do event
36 programming (waiting for I/O or timer events) without subscribing to a
37 religion, a way of living, and most importantly: without forcing your
38 module users into the same thing by forcing them to use the same event
39 model you use.
40
41 For modules like POE or IO::Async (which is actually doing all I/O
42 *synchronously*...), using them in your module is like joining a cult:
43 After you joined, you are dependent on them and you cannot use anything
44 else, as it is simply incompatible to everything that isn't itself.
45
46 AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk
47 works fine etc. etc. but none of these work together with the rest: POE
48 + IO::Async? no go. Tk + Event? no go. If your module uses one of those,
49 every user of your module has to use it, too. If your module uses
50 AnyEvent, it works transparently with all event models it supports
51 (including stuff like POE and IO::Async).
52
53 In addition of being free of having to use *the one and only true event
54 model*, AnyEvent also is free of bloat and policy: with POE or similar
55 modules, you get an enourmous amount of code and strict rules you have
56 to follow. AnyEvent, on the other hand, is lean and to the point by only
57 offering the functionality that is useful, in as thin as a wrapper as
58 technically possible.
59
60 Of course, if you want lots of policy (this can arguably be somewhat
61 useful) and you want to force your users to use the one and only event
62 model, you should *not* use this module.
20 63
21DESCRIPTION 64DESCRIPTION
22 AnyEvent provides an identical interface to multiple event loops. This 65 AnyEvent provides an identical interface to multiple event loops. This
23 allows module authors to utilise an event loop without forcing module 66 allows module authors to utilise an event loop without forcing module
24 users to use the same event loop (as only a single event loop can 67 users to use the same event loop (as only a single event loop can
… …
27 The interface itself is vaguely similar but not identical to the Event 70 The interface itself is vaguely similar but not identical to the Event
28 module. 71 module.
29 72
30 On the first call of any method, the module tries to detect the 73 On the first call of any method, the module tries to detect the
31 currently loaded event loop by probing wether any of the following 74 currently loaded event loop by probing wether any of the following
32 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is 75 modules is loaded: Coro::EV, Coro::Event, EV, Event, Glib, Tk. The first
33 used. If none is found, the module tries to load these modules in the 76 one found is used. If none are found, the module tries to load these
34 order given. The first one that could be successfully loaded will be 77 modules in the order given. The first one that could be successfully
35 used. If still none could be found, AnyEvent will fall back to a 78 loaded will be used. If still none could be found, AnyEvent will fall
36 pure-perl event loop, which is also not very efficient. 79 back to a pure-perl event loop, which is also not very efficient.
37 80
38 Because AnyEvent first checks for modules that are already loaded, 81 Because AnyEvent first checks for modules that are already loaded,
39 loading an Event model explicitly before first using AnyEvent will 82 loading an Event model explicitly before first using AnyEvent will
40 likely make that model the default. For example: 83 likely make that model the default. For example:
41 84
… …
65 You can create I/O watcher by calling the "AnyEvent->io" method with the 108 You can create I/O watcher by calling the "AnyEvent->io" method with the
66 following mandatory arguments: 109 following mandatory arguments:
67 110
68 "fh" the Perl *filehandle* (not filedescriptor) to watch for events. 111 "fh" the Perl *filehandle* (not filedescriptor) to watch for events.
69 "poll" must be a string that is either "r" or "w", that creates a 112 "poll" must be a string that is either "r" or "w", that creates a
70 watcher waiting for "r"eadable or "w"ritable events. "cb" teh callback 113 watcher waiting for "r"eadable or "w"ritable events. "cb" the callback
71 to invoke everytime the filehandle becomes ready. 114 to invoke everytime the filehandle becomes ready.
72
73 Only one io watcher per "fh" and "poll" combination is allowed (i.e. on
74 a socket you can have one r + one w, not any more (limitation comes from
75 Tk - if you are sure you are not using Tk this limitation is gone).
76 115
77 Filehandles will be kept alive, so as long as the watcher exists, the 116 Filehandles will be kept alive, so as long as the watcher exists, the
78 filehandle exists, too. 117 filehandle exists, too.
79 118
80 Example: 119 Example:
… …
103 my $w = AnyEvent->timer (after => 7.7, cb => sub { 142 my $w = AnyEvent->timer (after => 7.7, cb => sub {
104 warn "timeout\n"; 143 warn "timeout\n";
105 }); 144 });
106 145
107 # to cancel the timer: 146 # to cancel the timer:
108 undef $w 147 undef $w;
109 148
110 CONDITION WATCHERS 149 CONDITION WATCHERS
111 Condition watchers can be created by calling the "AnyEvent->condvar" 150 Condition watchers can be created by calling the "AnyEvent->condvar"
112 method without any arguments. 151 method without any arguments.
113 152
114 A condition watcher watches for a condition - precisely that the 153 A condition watcher watches for a condition - precisely that the
115 "->broadcast" method has been called. 154 "->broadcast" method has been called.
116 155
156 Note that condition watchers recurse into the event loop - if you have
157 two watchers that call "->wait" in a round-robbin fashion, you lose.
158 Therefore, condition watchers are good to export to your caller, but you
159 should avoid making a blocking wait, at least in callbacks, as this
160 usually asks for trouble.
161
117 The watcher has only two methods: 162 The watcher has only two methods:
118 163
119 $cv->wait 164 $cv->wait
120 Wait (blocking if necessary) until the "->broadcast" method has been 165 Wait (blocking if necessary) until the "->broadcast" method has been
121 called on c<$cv>, while servicing other watchers normally. 166 called on c<$cv>, while servicing other watchers normally.
122 167
123 Not all event models support a blocking wait - some die in that
124 case, so if you are using this from a module, never require a
125 blocking wait, but let the caller decide wether the call will block
126 or not (for example, by coupling condition variables with some kind
127 of request results and supporting callbacks so the caller knows that
128 getting the result will not block, while still suppporting blockign
129 waits if the caller so desires).
130
131 You can only wait once on a condition - additional calls will return 168 You can only wait once on a condition - additional calls will return
132 immediately. 169 immediately.
170
171 Not all event models support a blocking wait - some die in that case
172 (programs might want to do that so they stay interactive), so *if
173 you are using this from a module, never require a blocking wait*,
174 but let the caller decide wether the call will block or not (for
175 example, by coupling condition variables with some kind of request
176 results and supporting callbacks so the caller knows that getting
177 the result will not block, while still suppporting blocking waits if
178 the caller so desires).
179
180 Another reason *never* to "->wait" in a module is that you cannot
181 sensibly have two "->wait"'s in parallel, as that would require
182 multiple interpreters or coroutines/threads, none of which
183 "AnyEvent" can supply (the coroutine-aware backends "Coro::EV" and
184 "Coro::Event" explicitly support concurrent "->wait"'s from
185 different coroutines, however).
133 186
134 $cv->broadcast 187 $cv->broadcast
135 Flag the condition as ready - a running "->wait" and all further 188 Flag the condition as ready - a running "->wait" and all further
136 calls to "wait" will return after this method has been called. If 189 calls to "wait" will return after this method has been called. If
137 nobody is waiting the broadcast will be remembered.. 190 nobody is waiting the broadcast will be remembered..
… …
180 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 233 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
181 234
182 The known classes so far are: 235 The known classes so far are:
183 236
184 AnyEvent::Impl::CoroEV based on Coro::EV, best choice. 237 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
238 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
185 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 239 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
186 AnyEvent::Impl::Coro based on Coro::Event, second best choice.
187 AnyEvent::Impl::Event based on Event, also second best choice :) 240 AnyEvent::Impl::Event based on Event, also second best choice :)
188 AnyEvent::Impl::Glib based on Glib, second-best choice. 241 AnyEvent::Impl::Glib based on Glib, third-best choice.
189 AnyEvent::Impl::Tk based on Tk, very bad choice. 242 AnyEvent::Impl::Tk based on Tk, very bad choice.
190 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 243 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
191 244
192 AnyEvent::detect 245 AnyEvent::detect
193 Returns $AnyEvent::MODEL, forcing autodetection of the event model 246 Returns $AnyEvent::MODEL, forcing autodetection of the event model
194 if necessary. You should only call this function right before you 247 if necessary. You should only call this function right before you
195 would have created an AnyEvent watcher anyway, that is, very late at 248 would have created an AnyEvent watcher anyway, that is, very late at
… …
377 430
378 1. Blocking: 431 1. Blocking:
379 432
380 my $data = $fcp->client_get ($url); 433 my $data = $fcp->client_get ($url);
381 434
382 2. Blocking, but parallelizing: 435 2. Blocking, but running in parallel:
383 436
384 my @datas = map $_->result, 437 my @datas = map $_->result,
385 map $fcp->txn_client_get ($_), 438 map $fcp->txn_client_get ($_),
386 @urls; 439 @urls;
387 440
388 Both blocking examples work without the module user having to know 441 Both blocking examples work without the module user having to know
389 anything about events. 442 anything about events.
390 443
391 3a. Event-based in a main program, using any support Event module: 444 3a. Event-based in a main program, using any supported event module:
392 445
393 use Event; 446 use EV;
394 447
395 $fcp->txn_client_get ($url)->cb (sub { 448 $fcp->txn_client_get ($url)->cb (sub {
396 my $txn = shift; 449 my $txn = shift;
397 my $data = $txn->result; 450 my $data = $txn->result;
398 ... 451 ...
399 }); 452 });
400 453
401 Event::loop; 454 EV::loop;
402 455
403 3b. The module user could use AnyEvent, too: 456 3b. The module user could use AnyEvent, too:
404 457
405 use AnyEvent; 458 use AnyEvent;
406 459
… …
412 }); 465 });
413 466
414 $quit->wait; 467 $quit->wait;
415 468
416SEE ALSO 469SEE ALSO
417 Event modules: Coro::Event, Coro, Event, Glib::Event, Glib. 470 Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event,
471 Glib::Event, Glib, Coro, Tk.
418 472
419 Implementations: AnyEvent::Impl::Coro, AnyEvent::Impl::Event, 473 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV,
420 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk. 474 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib,
475 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl.
421 476
422 Nontrivial usage example: Net::FCP. 477 Nontrivial usage examples: Net::FCP, Net::XMPP2.
423 478
424 479

Diff Legend

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