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

Comparing AnyEvent/README (file contents):
Revision 1.5 by root, Sun Jan 8 04:41:08 2006 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 - 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 => ..., poll => "[rw]+", cb => sub { 10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub {
10 my ($poll_got) = @_;
11 ... 11 ...
12 }); 12 });
13
14 * only one io watcher per $fh and $poll type is allowed (i.e. on a
15 socket you can have one r + one w or one rw watcher, not any more
16 (limitation by Tk).
17
18 * the $poll_got passed to the handler needs to be checked by looking for
19 single characters (e.g. with a regex), as it can contain more event
20 types than were requested (e.g. a 'w' watcher might generate 'rw'
21 events, limitation by Glib).
22
23 * AnyEvent will keep filehandles alive, so as long as the watcher
24 exists, the filehandle exists.
25 13
26 my $w = AnyEvent->timer (after => $seconds, cb => sub { 14 my $w = AnyEvent->timer (after => $seconds, cb => sub {
27 ... 15 ...
28 }); 16 });
29 17
30 * io and time watchers get canceled whenever $w is destroyed, so keep a 18 my $w = AnyEvent->condvar; # stores wether a condition was flagged
31 copy
32
33 * timers can only be used once and must be recreated for repeated
34 operation (limitation by Glib and Tk).
35
36 my $w = AnyEvent->condvar; # kind of main loop replacement
37 $w->wait; # enters main loop till $condvar gets ->broadcast 19 $w->wait; # enters "main loop" till $condvar gets ->broadcast
38 $w->broadcast; # wake up current and all future wait's 20 $w->broadcast; # wake up current and all future wait's
39 21
40 * condvars are used to give blocking behaviour when neccessary. Create a 22WHY YOU SHOULD USE THIS MODULE (OR NOT)
41 condvar for any "request" or "event" your module might create, 23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
42 "->broadcast" it when the event happens and provide a function that 24 nowadays. So what is different about AnyEvent?
43 calls "->wait" for it. See the examples below. 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.
44 63
45DESCRIPTION 64DESCRIPTION
46 AnyEvent provides an identical interface to multiple event loops. This 65 AnyEvent provides an identical interface to multiple event loops. This
47 allows module authors to utilizy an event loop without forcing module 66 allows module authors to utilise an event loop without forcing module
48 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
49 coexist peacefully at any one time). 68 coexist peacefully at any one time).
50 69
51 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
52 module. 71 module.
53 72
54 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
55 currently loaded event loop by probing wether any of the following 74 currently loaded event loop by probing wether any of the following
56 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
57 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
58 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
59 used. If still none could be found, it will issue an error. 78 loaded will be used. If still none could be found, AnyEvent will fall
79 back to a pure-perl event loop, which is also not very efficient.
80
81 Because AnyEvent first checks for modules that are already loaded,
82 loading an Event model explicitly before first using AnyEvent will
83 likely make that model the default. For example:
84
85 use Tk;
86 use AnyEvent;
87
88 # .. AnyEvent will likely default to Tk
89
90 The pure-perl implementation of AnyEvent is called
91 "AnyEvent::Impl::Perl". Like other event modules you can load it
92 explicitly.
93
94WATCHERS
95 AnyEvent has the central concept of a *watcher*, which is an object that
96 stores relevant data for each kind of event you are waiting for, such as
97 the callback to call, the filehandle to watch, etc.
98
99 These watchers are normal Perl objects with normal Perl lifetime. After
100 creating a watcher it will immediately "watch" for events and invoke the
101 callback. To disable the watcher you have to destroy it (e.g. by setting
102 the variable that stores it to "undef" or otherwise deleting all
103 references to it).
104
105 All watchers are created by calling a method on the "AnyEvent" class.
106
107 IO WATCHERS
108 You can create I/O watcher by calling the "AnyEvent->io" method with the
109 following mandatory arguments:
110
111 "fh" the Perl *filehandle* (not filedescriptor) to watch for events.
112 "poll" must be a string that is either "r" or "w", that creates a
113 watcher waiting for "r"eadable or "w"ritable events. "cb" the callback
114 to invoke everytime the filehandle becomes ready.
115
116 Filehandles will be kept alive, so as long as the watcher exists, the
117 filehandle exists, too.
118
119 Example:
120
121 # wait for readability of STDIN, then read a line and disable the watcher
122 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
123 chomp (my $input = <STDIN>);
124 warn "read: $input\n";
125 undef $w;
126 });
127
128 TIME WATCHERS
129 You can create a time watcher by calling the "AnyEvent->timer" method
130 with the following mandatory arguments:
131
132 "after" after how many seconds (fractions are supported) should the
133 timer activate. "cb" the callback to invoke.
134
135 The timer callback will be invoked at most once: if you want a repeating
136 timer you have to create a new watcher (this is a limitation by both Tk
137 and Glib).
138
139 Example:
140
141 # fire an event after 7.7 seconds
142 my $w = AnyEvent->timer (after => 7.7, cb => sub {
143 warn "timeout\n";
144 });
145
146 # to cancel the timer:
147 undef $w;
148
149 CONDITION WATCHERS
150 Condition watchers can be created by calling the "AnyEvent->condvar"
151 method without any arguments.
152
153 A condition watcher watches for a condition - precisely that the
154 "->broadcast" method has been called.
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
162 The watcher has only two methods:
163
164 $cv->wait
165 Wait (blocking if necessary) until the "->broadcast" method has been
166 called on c<$cv>, while servicing other watchers normally.
167
168 You can only wait once on a condition - additional calls will return
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).
186
187 $cv->broadcast
188 Flag the condition as ready - a running "->wait" and all further
189 calls to "wait" will return after this method has been called. If
190 nobody is waiting the broadcast will be remembered..
191
192 Example:
193
194 # wait till the result is ready
195 my $result_ready = AnyEvent->condvar;
196
197 # do something such as adding a timer
198 # or socket watcher the calls $result_ready->broadcast
199 # when the "result" is ready.
200
201 $result_ready->wait;
202
203 SIGNAL WATCHERS
204 You can listen for signals using a signal watcher, "signal" is the
205 signal *name* without any "SIG" prefix. Multiple signals events can be
206 clumped together into one callback invocation, and callback invocation
207 might or might not be asynchronous.
208
209 These watchers might use %SIG, so programs overwriting those signals
210 directly will likely not work correctly.
211
212 Example: exit on SIGINT
213
214 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
215
216 CHILD PROCESS WATCHERS
217 You can also listen for the status of a child process specified by the
218 "pid" argument (or any child if the pid argument is 0). The watcher will
219 trigger as often as status change for the child are received. This works
220 by installing a signal handler for "SIGCHLD". The callback will be
221 called with the pid and exit status (as returned by waitpid).
222
223 Example: wait for pid 1333
224
225 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
226
227GLOBALS
228 $AnyEvent::MODEL
229 Contains "undef" until the first watcher is being created. Then it
230 contains the event model that is being used, which is the name of
231 the Perl class implementing the model. This class is usually one of
232 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
233 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
234
235 The known classes so far are:
236
237 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
238 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
239 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
240 AnyEvent::Impl::Event based on Event, also second best choice :)
241 AnyEvent::Impl::Glib based on Glib, third-best choice.
242 AnyEvent::Impl::Tk based on Tk, very bad choice.
243 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
244
245 AnyEvent::detect
246 Returns $AnyEvent::MODEL, forcing autodetection of the event model
247 if necessary. You should only call this function right before you
248 would have created an AnyEvent watcher anyway, that is, very late at
249 runtime.
250
251WHAT TO DO IN A MODULE
252 As a module author, you should "use AnyEvent" and call AnyEvent methods
253 freely, but you should not load a specific event module or rely on it.
254
255 Be careful when you create watchers in the module body - Anyevent will
256 decide which event module to use as soon as the first method is called,
257 so by calling AnyEvent in your module body you force the user of your
258 module to load the event module first.
259
260WHAT TO DO IN THE MAIN PROGRAM
261 There will always be a single main program - the only place that should
262 dictate which event model to use.
263
264 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
265 do anything special and let AnyEvent decide which implementation to
266 chose.
267
268 If the main program relies on a specific event model (for example, in
269 Gtk2 programs you have to rely on either Glib or Glib::Event), you
270 should load it before loading AnyEvent or any module that uses it,
271 generally, as early as possible. The reason is that modules might create
272 watchers when they are loaded, and AnyEvent will decide on the event
273 model to use as soon as it creates watchers, and it might chose the
274 wrong one unless you load the correct one yourself.
275
276 You can chose to use a rather inefficient pure-perl implementation by
277 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is
278 generally better.
60 279
61SUPPLYING YOUR OWN EVENT MODEL INTERFACE 280SUPPLYING YOUR OWN EVENT MODEL INTERFACE
62 If you need to support another event library which isn't directly 281 If you need to support another event library which isn't directly
63 supported by AnyEvent, you can supply your own interface to it by 282 supported by AnyEvent, you can supply your own interface to it by
64 pushing, before the first watch gets created, the package name of the 283 pushing, before the first watcher gets created, the package name of the
65 event module and the package name of the interface to use onto 284 event module and the package name of the interface to use onto
66 @AnyEvent::REGISTRY. You can do that before and even without loading 285 @AnyEvent::REGISTRY. You can do that before and even without loading
67 AnyEvent. 286 AnyEvent.
68 287
69 Example: 288 Example:
70 289
71 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 290 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
72 291
73 This tells AnyEvent to (literally) use the "urxvt::anyevent::" module 292 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
74 when it finds the "urxvt" module is loaded. When AnyEvent is loaded and 293 package/class when it finds the "urxvt" package/module is loaded. When
75 requested to find a suitable event model, it will first check for the 294 AnyEvent is loaded and asked to find a suitable event model, it will
76 urxvt module. 295 first check for the presence of urxvt.
296
297 The class should provide implementations for all watcher types (see
298 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code)
299 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to
300 see the sources).
77 301
78 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the 302 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the
79 above line exactly. An interface isn't included in AnyEvent because it 303 above line as-is. An interface isn't included in AnyEvent because it
80 doesn't make sense outside the embedded interpreter inside 304 doesn't make sense outside the embedded interpreter inside
81 *rxvt-unicode*, and it is updated and maintained as part of the 305 *rxvt-unicode*, and it is updated and maintained as part of the
82 *rxvt-unicode* distribution. 306 *rxvt-unicode* distribution.
307
308 *rxvt-unicode* also cheats a bit by not providing blocking access to
309 condition variables: code blocking while waiting for a condition will
310 "die". This still works with most modules/usages, and blocking calls
311 must not be in an interactive application, so it makes sense.
83 312
84ENVIRONMENT VARIABLES 313ENVIRONMENT VARIABLES
85 The following environment variables are used by this module: 314 The following environment variables are used by this module:
86 315
87 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event 316 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event
… …
201 430
202 1. Blocking: 431 1. Blocking:
203 432
204 my $data = $fcp->client_get ($url); 433 my $data = $fcp->client_get ($url);
205 434
206 2. Blocking, but parallelizing: 435 2. Blocking, but running in parallel:
207 436
208 my @datas = map $_->result, 437 my @datas = map $_->result,
209 map $fcp->txn_client_get ($_), 438 map $fcp->txn_client_get ($_),
210 @urls; 439 @urls;
211 440
212 Both blocking examples work without the module user having to know 441 Both blocking examples work without the module user having to know
213 anything about events. 442 anything about events.
214 443
215 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:
216 445
217 use Event; 446 use EV;
218 447
219 $fcp->txn_client_get ($url)->cb (sub { 448 $fcp->txn_client_get ($url)->cb (sub {
220 my $txn = shift; 449 my $txn = shift;
221 my $data = $txn->result; 450 my $data = $txn->result;
222 ... 451 ...
223 }); 452 });
224 453
225 Event::loop; 454 EV::loop;
226 455
227 3b. The module user could use AnyEvent, too: 456 3b. The module user could use AnyEvent, too:
228 457
229 use AnyEvent; 458 use AnyEvent;
230 459
… …
236 }); 465 });
237 466
238 $quit->wait; 467 $quit->wait;
239 468
240SEE ALSO 469SEE ALSO
241 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.
242 472
243 Implementations: AnyEvent::Impl::Coro, AnyEvent::Impl::Event, 473 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV,
244 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk. 474 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib,
475 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl.
245 476
246 Nontrivial usage example: Net::FCP. 477 Nontrivial usage examples: Net::FCP, Net::XMPP2.
247 478
248 479

Diff Legend

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