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

Comparing AnyEvent/README (file contents):
Revision 1.10 by root, Mon Jul 16 19:36:36 2007 UTC vs.
Revision 1.17 by root, Tue Apr 22 05:12:19 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 {
… …
12 13
13 my $w = AnyEvent->timer (after => $seconds, cb => sub { 14 my $w = AnyEvent->timer (after => $seconds, cb => sub {
14 ... 15 ...
15 }); 16 });
16 17
17 my $w = AnyEvent->condvar; # stores wether a condition was flagged 18 my $w = AnyEvent->condvar; # stores whether 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: In general,
33 only one event loop can be active at the same time in a process.
34 AnyEvent helps hiding the differences between those event loops.
35
36 The goal of AnyEvent is to offer module authors the ability to do event
37 programming (waiting for I/O or timer events) without subscribing to a
38 religion, a way of living, and most importantly: without forcing your
39 module users into the same thing by forcing them to use the same event
40 model you use.
41
42 For modules like POE or IO::Async (which is a total misnomer as it is
43 actually doing all I/O *synchronously*...), using them in your module is
44 like joining a cult: After you joined, you are dependent on them and you
45 cannot use anything else, as it is simply incompatible to everything
46 that isn't itself. What's worse, all the potential users of your module
47 are *also* forced to use the same event loop you use.
48
49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
50 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
51 with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if your
52 module uses one of those, every user of your module has to use it, too.
53 But if your module uses AnyEvent, it works transparently with all event
54 models it supports (including stuff like POE and IO::Async, as long as
55 those use one of the supported event loops. It is trivial to add new
56 event loops to AnyEvent, too, so it is future-proof).
57
58 In addition to being free of having to use *the one and only true event
59 model*, AnyEvent also is free of bloat and policy: with POE or similar
60 modules, you get an enourmous amount of code and strict rules you have
61 to follow. AnyEvent, on the other hand, is lean and up to the point, by
62 only offering the functionality that is necessary, in as thin as a
63 wrapper as technically possible.
64
65 Of course, if you want lots of policy (this can arguably be somewhat
66 useful) and you want to force your users to use the one and only event
67 model, you should *not* use this module.
20 68
21DESCRIPTION 69DESCRIPTION
22 AnyEvent provides an identical interface to multiple event loops. This 70 AnyEvent provides an identical interface to multiple event loops. This
23 allows module authors to utilise an event loop without forcing module 71 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 72 users to use the same event loop (as only a single event loop can
25 coexist peacefully at any one time). 73 coexist peacefully at any one time).
26 74
27 The interface itself is vaguely similar but not identical to the Event 75 The interface itself is vaguely similar, but not identical to the Event
28 module. 76 module.
29 77
30 On the first call of any method, the module tries to detect the 78 During the first call of any watcher-creation method, the module tries
31 currently loaded event loop by probing wether any of the following 79 to detect the currently loaded event loop by probing whether one of the
32 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is 80 following modules is already loaded: Coro::EV, Coro::Event, EV, Event,
33 used. If none is found, the module tries to load these modules in the 81 Glib, Tk. The first one found is used. If none are found, the module
34 order given. The first one that could be successfully loaded will be 82 tries to load these modules in the stated order. The first one that can
35 used. If still none could be found, AnyEvent will fall back to a 83 be successfully loaded will be used. If, after this, still none could be
36 pure-perl event loop, which is also not very efficient. 84 found, AnyEvent will fall back to a pure-perl event loop, which is not
85 very efficient, but should work everywhere.
37 86
38 Because AnyEvent first checks for modules that are already loaded, 87 Because AnyEvent first checks for modules that are already loaded,
39 loading an Event model explicitly before first using AnyEvent will 88 loading an event model explicitly before first using AnyEvent will
40 likely make that model the default. For example: 89 likely make that model the default. For example:
41 90
42 use Tk; 91 use Tk;
43 use AnyEvent; 92 use AnyEvent;
44 93
45 # .. AnyEvent will likely default to Tk 94 # .. AnyEvent will likely default to Tk
95
96 The *likely* means that, if any module loads another event model and
97 starts using it, all bets are off. Maybe you should tell their authors
98 to use AnyEvent so their modules work together with others seamlessly...
46 99
47 The pure-perl implementation of AnyEvent is called 100 The pure-perl implementation of AnyEvent is called
48 "AnyEvent::Impl::Perl". Like other event modules you can load it 101 "AnyEvent::Impl::Perl". Like other event modules you can load it
49 explicitly. 102 explicitly.
50 103
… …
53 stores relevant data for each kind of event you are waiting for, such as 106 stores relevant data for each kind of event you are waiting for, such as
54 the callback to call, the filehandle to watch, etc. 107 the callback to call, the filehandle to watch, etc.
55 108
56 These watchers are normal Perl objects with normal Perl lifetime. After 109 These watchers are normal Perl objects with normal Perl lifetime. After
57 creating a watcher it will immediately "watch" for events and invoke the 110 creating a watcher it will immediately "watch" for events and invoke the
111 callback when the event occurs (of course, only when the event model is
112 in control).
113
58 callback. To disable the watcher you have to destroy it (e.g. by setting 114 To disable the watcher you have to destroy it (e.g. by setting the
59 the variable that stores it to "undef" or otherwise deleting all 115 variable you store it in to "undef" or otherwise deleting all references
60 references to it). 116 to it).
61 117
62 All watchers are created by calling a method on the "AnyEvent" class. 118 All watchers are created by calling a method on the "AnyEvent" class.
63 119
120 Many watchers either are used with "recursion" (repeating timers for
121 example), or need to refer to their watcher object in other ways.
122
123 An any way to achieve that is this pattern:
124
125 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
126 # you can use $w here, for example to undef it
127 undef $w;
128 });
129
130 Note that "my $w; $w =" combination. This is necessary because in Perl,
131 my variables are only visible after the statement in which they are
132 declared.
133
64 IO WATCHERS 134 IO WATCHERS
65 You can create I/O watcher by calling the "AnyEvent->io" method with the 135 You can create an I/O watcher by calling the "AnyEvent->io" method with
66 following mandatory arguments: 136 the following mandatory key-value pairs as arguments:
67 137
68 "fh" the Perl *filehandle* (not filedescriptor) to watch for events. 138 "fh" the Perl *file handle* (*not* file descriptor) to watch for events.
69 "poll" must be a string that is either "r" or "w", that creates a 139 "poll" must be a string that is either "r" or "w", which creates a
70 watcher waiting for "r"eadable or "w"ritable events. "cb" teh callback 140 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"
71 to invoke everytime the filehandle becomes ready. 141 is the callback to invoke each time the file handle becomes ready.
72 142
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
77 Filehandles will be kept alive, so as long as the watcher exists, the 143 File handles will be kept alive, so as long as the watcher exists, the
78 filehandle exists, too. 144 file handle exists, too.
145
146 It is not allowed to close a file handle as long as any watcher is
147 active on the underlying file descriptor.
148
149 Some event loops issue spurious readyness notifications, so you should
150 always use non-blocking calls when reading/writing from/to your file
151 handles.
79 152
80 Example: 153 Example:
81 154
82 # wait for readability of STDIN, then read a line and disable the watcher 155 # wait for readability of STDIN, then read a line and disable the watcher
83 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 156 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
… …
88 161
89 TIME WATCHERS 162 TIME WATCHERS
90 You can create a time watcher by calling the "AnyEvent->timer" method 163 You can create a time watcher by calling the "AnyEvent->timer" method
91 with the following mandatory arguments: 164 with the following mandatory arguments:
92 165
93 "after" after how many seconds (fractions are supported) should the 166 "after" specifies after how many seconds (fractional values are
94 timer activate. "cb" the callback to invoke. 167 supported) should the timer activate. "cb" the callback to invoke in
168 that case.
95 169
96 The timer callback will be invoked at most once: if you want a repeating 170 The timer callback will be invoked at most once: if you want a repeating
97 timer you have to create a new watcher (this is a limitation by both Tk 171 timer you have to create a new watcher (this is a limitation by both Tk
98 and Glib). 172 and Glib).
99 173
… …
103 my $w = AnyEvent->timer (after => 7.7, cb => sub { 177 my $w = AnyEvent->timer (after => 7.7, cb => sub {
104 warn "timeout\n"; 178 warn "timeout\n";
105 }); 179 });
106 180
107 # to cancel the timer: 181 # to cancel the timer:
108 undef $w 182 undef $w;
109 183
110 CONDITION WATCHERS 184 Example 2:
185
186 # fire an event after 0.5 seconds, then roughly every second
187 my $w;
188
189 my $cb = sub {
190 # cancel the old timer while creating a new one
191 $w = AnyEvent->timer (after => 1, cb => $cb);
192 };
193
194 # start the "loop" by creating the first watcher
195 $w = AnyEvent->timer (after => 0.5, cb => $cb);
196
197 TIMING ISSUES
198 There are two ways to handle timers: based on real time (relative, "fire
199 in 10 seconds") and based on wallclock time (absolute, "fire at 12
200 o'clock").
201
202 While most event loops expect timers to specified in a relative way,
203 they use absolute time internally. This makes a difference when your
204 clock "jumps", for example, when ntp decides to set your clock backwards
205 from the wrong 2014-01-01 to 2008-01-01, a watcher that you created to
206 fire "after" a second might actually take six years to finally fire.
207
208 AnyEvent cannot compensate for this. The only event loop that is
209 conscious about these issues is EV, which offers both relative
210 (ev_timer) and absolute (ev_periodic) timers.
211
212 AnyEvent always prefers relative timers, if available, matching the
213 AnyEvent API.
214
215 SIGNAL WATCHERS
216 You can watch for signals using a signal watcher, "signal" is the signal
217 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked
218 whenever a signal occurs.
219
220 Multiple signals occurances can be clumped together into one callback
221 invocation, and callback invocation will be synchronous. synchronous
222 means that it might take a while until the signal gets handled by the
223 process, but it is guarenteed not to interrupt any other callbacks.
224
225 The main advantage of using these watchers is that you can share a
226 signal between multiple watchers.
227
228 This watcher might use %SIG, so programs overwriting those signals
229 directly will likely not work correctly.
230
231 Example: exit on SIGINT
232
233 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
234
235 CHILD PROCESS WATCHERS
236 You can also watch on a child process exit and catch its exit status.
237
238 The child process is specified by the "pid" argument (if set to 0, it
239 watches for any child process exit). The watcher will trigger as often
240 as status change for the child are received. This works by installing a
241 signal handler for "SIGCHLD". The callback will be called with the pid
242 and exit status (as returned by waitpid).
243
244 Example: wait for pid 1333
245
246 my $w = AnyEvent->child (
247 pid => 1333,
248 cb => sub {
249 my ($pid, $status) = @_;
250 warn "pid $pid exited with status $status";
251 },
252 );
253
254 CONDITION VARIABLES
111 Condition watchers can be created by calling the "AnyEvent->condvar" 255 Condition variables can be created by calling the "AnyEvent->condvar"
112 method without any arguments. 256 method without any arguments.
113 257
114 A condition watcher watches for a condition - precisely that the 258 A condition variable waits for a condition - precisely that the
115 "->broadcast" method has been called. 259 "->broadcast" method has been called.
116 260
117 The watcher has only two methods: 261 They are very useful to signal that a condition has been fulfilled, for
262 example, if you write a module that does asynchronous http requests,
263 then a condition variable would be the ideal candidate to signal the
264 availability of results.
265
266 You can also use condition variables to block your main program until an
267 event occurs - for example, you could "->wait" in your main program
268 until the user clicks the Quit button in your app, which would
269 "->broadcast" the "quit" event.
270
271 Note that condition variables recurse into the event loop - if you have
272 two pirces of code that call "->wait" in a round-robbin fashion, you
273 lose. Therefore, condition variables are good to export to your caller,
274 but you should avoid making a blocking wait yourself, at least in
275 callbacks, as this asks for trouble.
276
277 This object has two methods:
118 278
119 $cv->wait 279 $cv->wait
120 Wait (blocking if necessary) until the "->broadcast" method has been 280 Wait (blocking if necessary) until the "->broadcast" method has been
121 called on c<$cv>, while servicing other watchers normally. 281 called on c<$cv>, while servicing other watchers normally.
122 282
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 283 You can only wait once on a condition - additional calls will return
132 immediately. 284 immediately.
133 285
286 Not all event models support a blocking wait - some die in that case
287 (programs might want to do that to stay interactive), so *if you are
288 using this from a module, never require a blocking wait*, but let
289 the caller decide whether the call will block or not (for example,
290 by coupling condition variables with some kind of request results
291 and supporting callbacks so the caller knows that getting the result
292 will not block, while still suppporting blocking waits if the caller
293 so desires).
294
295 Another reason *never* to "->wait" in a module is that you cannot
296 sensibly have two "->wait"'s in parallel, as that would require
297 multiple interpreters or coroutines/threads, none of which
298 "AnyEvent" can supply (the coroutine-aware backends
299 AnyEvent::Impl::CoroEV and AnyEvent::Impl::CoroEvent explicitly
300 support concurrent "->wait"'s from different coroutines, however).
301
134 $cv->broadcast 302 $cv->broadcast
135 Flag the condition as ready - a running "->wait" and all further 303 Flag the condition as ready - a running "->wait" and all further
136 calls to "wait" will return after this method has been called. If 304 calls to "wait" will (eventually) return after this method has been
137 nobody is waiting the broadcast will be remembered.. 305 called. If nobody is waiting the broadcast will be remembered..
138 306
139 Example: 307 Example:
140 308
141 # wait till the result is ready 309 # wait till the result is ready
142 my $result_ready = AnyEvent->condvar; 310 my $result_ready = AnyEvent->condvar;
143 311
144 # do something such as adding a timer 312 # do something such as adding a timer
145 # or socket watcher the calls $result_ready->broadcast 313 # or socket watcher the calls $result_ready->broadcast
146 # when the "result" is ready. 314 # when the "result" is ready.
315 # in this case, we simply use a timer:
316 my $w = AnyEvent->timer (
317 after => 1,
318 cb => sub { $result_ready->broadcast },
319 );
147 320
321 # this "blocks" (while handling events) till the watcher
322 # calls broadcast
148 $result_ready->wait; 323 $result_ready->wait;
149 324
150 SIGNAL WATCHERS 325GLOBAL VARIABLES AND FUNCTIONS
151 You can listen for signals using a signal watcher, "signal" is the
152 signal *name* without any "SIG" prefix. Multiple signals events can be
153 clumped together into one callback invocation, and callback invocation
154 might or might not be asynchronous.
155
156 These watchers might use %SIG, so programs overwriting those signals
157 directly will likely not work correctly.
158
159 Example: exit on SIGINT
160
161 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
162
163 CHILD PROCESS WATCHERS
164 You can also listen for the status of a child process specified by the
165 "pid" argument. The watcher will only trigger once. This works by
166 installing a signal handler for "SIGCHLD".
167
168 Example: wait for pid 1333
169
170 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
171
172GLOBALS
173 $AnyEvent::MODEL 326 $AnyEvent::MODEL
174 Contains "undef" until the first watcher is being created. Then it 327 Contains "undef" until the first watcher is being created. Then it
175 contains the event model that is being used, which is the name of 328 contains the event model that is being used, which is the name of
176 the Perl class implementing the model. This class is usually one of 329 the Perl class implementing the model. This class is usually one of
177 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 330 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
178 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 331 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
179 332
180 The known classes so far are: 333 The known classes so far are:
181 334
182 AnyEvent::Impl::Coro based on Coro::Event, best choise. 335 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
336 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
337 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
183 AnyEvent::Impl::Event based on Event, also best choice :) 338 AnyEvent::Impl::Event based on Event, also second best choice :)
184 AnyEvent::Impl::Glib based on Glib, second-best choice. 339 AnyEvent::Impl::Glib based on Glib, third-best choice.
185 AnyEvent::Impl::Tk based on Tk, very bad choice. 340 AnyEvent::Impl::Tk based on Tk, very bad choice.
186 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 341 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
187 342
188 AnyEvent::detect 343 AnyEvent::detect
189 Returns $AnyEvent::MODEL, forcing autodetection of the event model 344 Returns $AnyEvent::MODEL, forcing autodetection of the event model
190 if necessary. You should only call this function right before you 345 if necessary. You should only call this function right before you
191 would have created an AnyEvent watcher anyway, that is, very late at 346 would have created an AnyEvent watcher anyway, that is, as late as
192 runtime. 347 possible at runtime.
193 348
194WHAT TO DO IN A MODULE 349WHAT TO DO IN A MODULE
195 As a module author, you should "use AnyEvent" and call AnyEvent methods 350 As a module author, you should "use AnyEvent" and call AnyEvent methods
196 freely, but you should not load a specific event module or rely on it. 351 freely, but you should not load a specific event module or rely on it.
197 352
198 Be careful when you create watchers in the module body - Anyevent will 353 Be careful when you create watchers in the module body - AnyEvent will
199 decide which event module to use as soon as the first method is called, 354 decide which event module to use as soon as the first method is called,
200 so by calling AnyEvent in your module body you force the user of your 355 so by calling AnyEvent in your module body you force the user of your
201 module to load the event module first. 356 module to load the event module first.
202 357
358 Never call "->wait" on a condition variable unless you *know* that the
359 "->broadcast" method has been called on it already. This is because it
360 will stall the whole program, and the whole point of using events is to
361 stay interactive.
362
363 It is fine, however, to call "->wait" when the user of your module
364 requests it (i.e. if you create a http request object ad have a method
365 called "results" that returns the results, it should call "->wait"
366 freely, as the user of your module knows what she is doing. always).
367
203WHAT TO DO IN THE MAIN PROGRAM 368WHAT TO DO IN THE MAIN PROGRAM
204 There will always be a single main program - the only place that should 369 There will always be a single main program - the only place that should
205 dictate which event model to use. 370 dictate which event model to use.
206 371
207 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 372 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
208 do anything special and let AnyEvent decide which implementation to 373 do anything special (it does not need to be event-based) and let
209 chose. 374 AnyEvent decide which implementation to chose if some module relies on
375 it.
210 376
211 If the main program relies on a specific event model (for example, in 377 If the main program relies on a specific event model. For example, in
212 Gtk2 programs you have to rely on either Glib or Glib::Event), you 378 Gtk2 programs you have to rely on the Glib module. You should load the
213 should load it before loading AnyEvent or any module that uses it, 379 event module before loading AnyEvent or any module that uses it:
214 generally, as early as possible. The reason is that modules might create 380 generally speaking, you should load it as early as possible. The reason
215 watchers when they are loaded, and AnyEvent will decide on the event 381 is that modules might create watchers when they are loaded, and AnyEvent
216 model to use as soon as it creates watchers, and it might chose the 382 will decide on the event model to use as soon as it creates watchers,
217 wrong one unless you load the correct one yourself. 383 and it might chose the wrong one unless you load the correct one
384 yourself.
218 385
219 You can chose to use a rather inefficient pure-perl implementation by 386 You can chose to use a rather inefficient pure-perl implementation by
220 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is 387 loading the "AnyEvent::Impl::Perl" module, which gives you similar
221 generally better. 388 behaviour everywhere, but letting AnyEvent chose is generally better.
222 389
223SUPPLYING YOUR OWN EVENT MODEL INTERFACE 390SUPPLYING YOUR OWN EVENT MODEL INTERFACE
391 This is an advanced topic that you do not normally need to use AnyEvent
392 in a module. This section is only of use to event loop authors who want
393 to provide AnyEvent compatibility.
394
224 If you need to support another event library which isn't directly 395 If you need to support another event library which isn't directly
225 supported by AnyEvent, you can supply your own interface to it by 396 supported by AnyEvent, you can supply your own interface to it by
226 pushing, before the first watcher gets created, the package name of the 397 pushing, before the first watcher gets created, the package name of the
227 event module and the package name of the interface to use onto 398 event module and the package name of the interface to use onto
228 @AnyEvent::REGISTRY. You can do that before and even without loading 399 @AnyEvent::REGISTRY. You can do that before and even without loading
229 AnyEvent. 400 AnyEvent, so it is reasonably cheap.
230 401
231 Example: 402 Example:
232 403
233 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 404 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
234 405
235 This tells AnyEvent to (literally) use the "urxvt::anyevent::" 406 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
236 package/class when it finds the "urxvt" package/module is loaded. When 407 package/class when it finds the "urxvt" package/module is already
408 loaded.
409
237 AnyEvent is loaded and asked to find a suitable event model, it will 410 When AnyEvent is loaded and asked to find a suitable event model, it
238 first check for the presence of urxvt. 411 will first check for the presence of urxvt by trying to "use" the
412 "urxvt::anyevent" module.
239 413
240 The class should provide implementations for all watcher types (see 414 The class should provide implementations for all watcher types. See
241 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code) 415 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
242 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to 416 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
243 see the sources). 417 the sources.
244 418
419 If you don't provide "signal" and "child" watchers than AnyEvent will
420 provide suitable (hopefully) replacements.
421
245 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the 422 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
246 above line as-is. An interface isn't included in AnyEvent because it 423 terminal emulator uses the above line as-is. An interface isn't included
247 doesn't make sense outside the embedded interpreter inside 424 in AnyEvent because it doesn't make sense outside the embedded
248 *rxvt-unicode*, and it is updated and maintained as part of the 425 interpreter inside *rxvt-unicode*, and it is updated and maintained as
249 *rxvt-unicode* distribution. 426 part of the *rxvt-unicode* distribution.
250 427
251 *rxvt-unicode* also cheats a bit by not providing blocking access to 428 *rxvt-unicode* also cheats a bit by not providing blocking access to
252 condition variables: code blocking while waiting for a condition will 429 condition variables: code blocking while waiting for a condition will
253 "die". This still works with most modules/usages, and blocking calls 430 "die". This still works with most modules/usages, and blocking calls
254 must not be in an interactive application, so it makes sense. 431 must not be done in an interactive application, so it makes sense.
255 432
256ENVIRONMENT VARIABLES 433ENVIRONMENT VARIABLES
257 The following environment variables are used by this module: 434 The following environment variables are used by this module:
258 435
259 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event 436 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, cause AnyEvent to
260 model gets used. 437 report to STDERR which event model it chooses.
261 438
262EXAMPLE 439EXAMPLE PROGRAM
263 The following program uses an io watcher to read data from stdin, a 440 The following program uses an IO watcher to read data from STDIN, a
264 timer to display a message once per second, and a condvar to exit the 441 timer to display a message once per second, and a condition variable to
265 program when the user enters quit: 442 quit the program when the user enters quit:
266 443
267 use AnyEvent; 444 use AnyEvent;
268 445
269 my $cv = AnyEvent->condvar; 446 my $cv = AnyEvent->condvar;
270 447
271 my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 448 my $io_watcher = AnyEvent->io (
449 fh => \*STDIN,
450 poll => 'r',
451 cb => sub {
272 warn "io event <$_[0]>\n"; # will always output <r> 452 warn "io event <$_[0]>\n"; # will always output <r>
273 chomp (my $input = <STDIN>); # read a line 453 chomp (my $input = <STDIN>); # read a line
274 warn "read: $input\n"; # output what has been read 454 warn "read: $input\n"; # output what has been read
275 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 455 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i
456 },
276 }); 457 );
277 458
278 my $time_watcher; # can only be used once 459 my $time_watcher; # can only be used once
279 460
280 sub new_timer { 461 sub new_timer {
281 $timer = AnyEvent->timer (after => 1, cb => sub { 462 $timer = AnyEvent->timer (after => 1, cb => sub {
… …
362 $txn->{finished}->wait; 543 $txn->{finished}->wait;
363 return $txn->{result}; 544 return $txn->{result};
364 545
365 The actual code goes further and collects all errors ("die"s, 546 The actual code goes further and collects all errors ("die"s,
366 exceptions) that occured during request processing. The "result" method 547 exceptions) that occured during request processing. The "result" method
367 detects wether an exception as thrown (it is stored inside the $txn 548 detects whether an exception as thrown (it is stored inside the $txn
368 object) and just throws the exception, which means connection errors and 549 object) and just throws the exception, which means connection errors and
369 other problems get reported tot he code that tries to use the result, 550 other problems get reported tot he code that tries to use the result,
370 not in a random callback. 551 not in a random callback.
371 552
372 All of this enables the following usage styles: 553 All of this enables the following usage styles:
373 554
374 1. Blocking: 555 1. Blocking:
375 556
376 my $data = $fcp->client_get ($url); 557 my $data = $fcp->client_get ($url);
377 558
378 2. Blocking, but parallelizing: 559 2. Blocking, but running in parallel:
379 560
380 my @datas = map $_->result, 561 my @datas = map $_->result,
381 map $fcp->txn_client_get ($_), 562 map $fcp->txn_client_get ($_),
382 @urls; 563 @urls;
383 564
384 Both blocking examples work without the module user having to know 565 Both blocking examples work without the module user having to know
385 anything about events. 566 anything about events.
386 567
387 3a. Event-based in a main program, using any support Event module: 568 3a. Event-based in a main program, using any supported event module:
388 569
389 use Event; 570 use EV;
390 571
391 $fcp->txn_client_get ($url)->cb (sub { 572 $fcp->txn_client_get ($url)->cb (sub {
392 my $txn = shift; 573 my $txn = shift;
393 my $data = $txn->result; 574 my $data = $txn->result;
394 ... 575 ...
395 }); 576 });
396 577
397 Event::loop; 578 EV::loop;
398 579
399 3b. The module user could use AnyEvent, too: 580 3b. The module user could use AnyEvent, too:
400 581
401 use AnyEvent; 582 use AnyEvent;
402 583
… …
408 }); 589 });
409 590
410 $quit->wait; 591 $quit->wait;
411 592
412SEE ALSO 593SEE ALSO
413 Event modules: Coro::Event, Coro, Event, Glib::Event, Glib. 594 Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event,
595 Glib::Event, Glib, Coro, Tk.
414 596
415 Implementations: AnyEvent::Impl::Coro, AnyEvent::Impl::Event, 597 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV,
416 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk. 598 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib,
599 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl.
417 600
418 Nontrivial usage example: Net::FCP. 601 Nontrivial usage examples: Net::FCP, Net::XMPP2.
419 602
603AUTHOR
604 Marc Lehmann <schmorp@schmorp.de>
605 http://home.schmorp.de/
420 606

Diff Legend

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