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

Comparing AnyEvent/README (file contents):
Revision 1.23 by root, Mon May 26 06:04:38 2008 UTC vs.
Revision 1.37 by root, Mon Apr 20 14:34:18 2009 UTC

1=> NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event
5 loops 5 loops
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... });
11 ...
12 });
13 11
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 12 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
13 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
14
15 print AnyEvent->now; # prints current event loop time
16 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
17
18 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
19
20 my $w = AnyEvent->child (pid => $pid, cb => sub {
21 my ($pid, $status) = @_;
15 ... 22 ...
16 }); 23 });
17 24
18 my $w = AnyEvent->condvar; # stores whether a condition was flagged 25 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's 26 $w->send; # wake up current and all future recv's
20 $w->recv; # enters "main loop" till $condvar gets ->send 27 $w->recv; # enters "main loop" till $condvar gets ->send
28 # use a condvar in callback mode:
29 $w->cb (sub { $_[0]->recv });
30
31INTRODUCTION/TUTORIAL
32 This manpage is mainly a reference manual. If you are interested in a
33 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
34 manpage.
21 35
22WHY YOU SHOULD USE THIS MODULE (OR NOT) 36WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 37 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent? 38 nowadays. So what is different about AnyEvent?
25 39
26 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of 40 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
27 policy* and AnyEvent is *small and efficient*. 41 policy* and AnyEvent is *small and efficient*.
28 42
29 First and foremost, *AnyEvent is not an event model* itself, it only 43 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 44 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, 45 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, 46 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. 47 only one event loop can be active at the same time in a process.
34 AnyEvent helps hiding the differences between those event loops. 48 AnyEvent cannot change this, but it can hide the differences between
49 those event loops.
35 50
36 The goal of AnyEvent is to offer module authors the ability to do event 51 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 52 programming (waiting for I/O or timer events) without subscribing to a
38 religion, a way of living, and most importantly: without forcing your 53 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 54 module users into the same thing by forcing them to use the same event
40 model you use. 55 model you use.
41 56
42 For modules like POE or IO::Async (which is a total misnomer as it is 57 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 58 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 59 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 60 cannot use anything else, as they are simply incompatible to everything
46 that isn't itself. What's worse, all the potential users of your module 61 that isn't them. What's worse, all the potential users of your module
47 are *also* forced to use the same event loop you use. 62 are *also* forced to use the same event loop you use.
48 63
49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 64 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
50 fine. AnyEvent + Tk works fine etc. etc. but none of these work together 65 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 66 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. 67 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 68 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 69 models it supports (including stuff like IO::Async, as long as those use
55 those use one of the supported event loops. It is trivial to add new 70 one of the supported event loops. It is trivial to add new event loops
56 event loops to AnyEvent, too, so it is future-proof). 71 to AnyEvent, too, so it is future-proof).
57 72
58 In addition to being free of having to use *the one and only true event 73 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 74 model*, AnyEvent also is free of bloat and policy: with POE or similar
60 modules, you get an enormous amount of code and strict rules you have to 75 modules, you get an enormous amount of code and strict rules you have to
61 follow. AnyEvent, on the other hand, is lean and up to the point, by 76 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 77 only offering the functionality that is necessary, in as thin as a
63 wrapper as technically possible. 78 wrapper as technically possible.
64 79
80 Of course, AnyEvent comes with a big (and fully optional!) toolbox of
81 useful functionality, such as an asynchronous DNS resolver, 100%
82 non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
83 such as Windows) and lots of real-world knowledge and workarounds for
84 platform bugs and differences.
85
65 Of course, if you want lots of policy (this can arguably be somewhat 86 Now, if you *do 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 87 useful) and you want to force your users to use the one and only event
67 model, you should *not* use this module. 88 model, you should *not* use this module.
68 89
69DESCRIPTION 90DESCRIPTION
70 AnyEvent provides an identical interface to multiple event loops. This 91 AnyEvent provides an identical interface to multiple event loops. This
… …
99 starts using it, all bets are off. Maybe you should tell their authors 120 starts using it, all bets are off. Maybe you should tell their authors
100 to use AnyEvent so their modules work together with others seamlessly... 121 to use AnyEvent so their modules work together with others seamlessly...
101 122
102 The pure-perl implementation of AnyEvent is called 123 The pure-perl implementation of AnyEvent is called
103 "AnyEvent::Impl::Perl". Like other event modules you can load it 124 "AnyEvent::Impl::Perl". Like other event modules you can load it
104 explicitly. 125 explicitly and enjoy the high availability of that event loop :)
105 126
106WATCHERS 127WATCHERS
107 AnyEvent has the central concept of a *watcher*, which is an object that 128 AnyEvent has the central concept of a *watcher*, which is an object that
108 stores relevant data for each kind of event you are waiting for, such as 129 stores relevant data for each kind of event you are waiting for, such as
109 the callback to call, the file handle to watch, etc. 130 the callback to call, the file handle to watch, etc.
… …
111 These watchers are normal Perl objects with normal Perl lifetime. After 132 These watchers are normal Perl objects with normal Perl lifetime. After
112 creating a watcher it will immediately "watch" for events and invoke the 133 creating a watcher it will immediately "watch" for events and invoke the
113 callback when the event occurs (of course, only when the event model is 134 callback when the event occurs (of course, only when the event model is
114 in control). 135 in control).
115 136
137 Note that callbacks must not permanently change global variables
138 potentially in use by the event loop (such as $_ or $[) and that
139 callbacks must not "die". The former is good programming practise in
140 Perl and the latter stems from the fact that exception handling differs
141 widely between event loops.
142
116 To disable the watcher you have to destroy it (e.g. by setting the 143 To disable the watcher you have to destroy it (e.g. by setting the
117 variable you store it in to "undef" or otherwise deleting all references 144 variable you store it in to "undef" or otherwise deleting all references
118 to it). 145 to it).
119 146
120 All watchers are created by calling a method on the "AnyEvent" class. 147 All watchers are created by calling a method on the "AnyEvent" class.
… …
122 Many watchers either are used with "recursion" (repeating timers for 149 Many watchers either are used with "recursion" (repeating timers for
123 example), or need to refer to their watcher object in other ways. 150 example), or need to refer to their watcher object in other ways.
124 151
125 An any way to achieve that is this pattern: 152 An any way to achieve that is this pattern:
126 153
127 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 154 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
128 # you can use $w here, for example to undef it 155 # you can use $w here, for example to undef it
129 undef $w; 156 undef $w;
130 }); 157 });
131 158
132 Note that "my $w; $w =" combination. This is necessary because in Perl, 159 Note that "my $w; $w =" combination. This is necessary because in Perl,
133 my variables are only visible after the statement in which they are 160 my variables are only visible after the statement in which they are
134 declared. 161 declared.
135 162
136 I/O WATCHERS 163 I/O WATCHERS
137 You can create an I/O watcher by calling the "AnyEvent->io" method with 164 You can create an I/O watcher by calling the "AnyEvent->io" method with
138 the following mandatory key-value pairs as arguments: 165 the following mandatory key-value pairs as arguments:
139 166
140 "fh" the Perl *file handle* (*not* file descriptor) to watch for events. 167 "fh" is the Perl *file handle* (*not* file descriptor) to watch for
168 events (AnyEvent might or might not keep a reference to this file
169 handle). Note that only file handles pointing to things for which
170 non-blocking operation makes sense are allowed. This includes sockets,
171 most character devices, pipes, fifos and so on, but not for example
172 files or block devices.
173
141 "poll" must be a string that is either "r" or "w", which creates a 174 "poll" must be a string that is either "r" or "w", which creates a
142 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 175 watcher waiting for "r"eadable or "w"ritable events, respectively.
176
143 is the callback to invoke each time the file handle becomes ready. 177 "cb" is the callback to invoke each time the file handle becomes ready.
144 178
145 Although the callback might get passed parameters, their value and 179 Although the callback might get passed parameters, their value and
146 presence is undefined and you cannot rely on them. Portable AnyEvent 180 presence is undefined and you cannot rely on them. Portable AnyEvent
147 callbacks cannot use arguments passed to I/O watcher callbacks. 181 callbacks cannot use arguments passed to I/O watcher callbacks.
148 182
… …
152 186
153 Some event loops issue spurious readyness notifications, so you should 187 Some event loops issue spurious readyness notifications, so you should
154 always use non-blocking calls when reading/writing from/to your file 188 always use non-blocking calls when reading/writing from/to your file
155 handles. 189 handles.
156 190
157 Example:
158
159 # wait for readability of STDIN, then read a line and disable the watcher 191 Example: wait for readability of STDIN, then read a line and disable the
192 watcher.
193
160 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 194 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
161 chomp (my $input = <STDIN>); 195 chomp (my $input = <STDIN>);
162 warn "read: $input\n"; 196 warn "read: $input\n";
163 undef $w; 197 undef $w;
164 }); 198 });
… …
173 207
174 Although the callback might get passed parameters, their value and 208 Although the callback might get passed parameters, their value and
175 presence is undefined and you cannot rely on them. Portable AnyEvent 209 presence is undefined and you cannot rely on them. Portable AnyEvent
176 callbacks cannot use arguments passed to time watcher callbacks. 210 callbacks cannot use arguments passed to time watcher callbacks.
177 211
178 The timer callback will be invoked at most once: if you want a repeating 212 The callback will normally be invoked once only. If you specify another
179 timer you have to create a new watcher (this is a limitation by both Tk 213 parameter, "interval", as a strictly positive number (> 0), then the
180 and Glib). 214 callback will be invoked regularly at that interval (in fractional
215 seconds) after the first invocation. If "interval" is specified with a
216 false value, then it is treated as if it were missing.
181 217
182 Example: 218 The callback will be rescheduled before invoking the callback, but no
219 attempt is done to avoid timer drift in most backends, so the interval
220 is only approximate.
183 221
184 # fire an event after 7.7 seconds 222 Example: fire an event after 7.7 seconds.
223
185 my $w = AnyEvent->timer (after => 7.7, cb => sub { 224 my $w = AnyEvent->timer (after => 7.7, cb => sub {
186 warn "timeout\n"; 225 warn "timeout\n";
187 }); 226 });
188 227
189 # to cancel the timer: 228 # to cancel the timer:
190 undef $w; 229 undef $w;
191 230
192 Example 2:
193
194 # fire an event after 0.5 seconds, then roughly every second 231 Example 2: fire an event after 0.5 seconds, then roughly every second.
195 my $w;
196 232
197 my $cb = sub {
198 # cancel the old timer while creating a new one
199 $w = AnyEvent->timer (after => 1, cb => $cb); 233 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
234 warn "timeout\n";
200 }; 235 };
201
202 # start the "loop" by creating the first watcher
203 $w = AnyEvent->timer (after => 0.5, cb => $cb);
204 236
205 TIMING ISSUES 237 TIMING ISSUES
206 There are two ways to handle timers: based on real time (relative, "fire 238 There are two ways to handle timers: based on real time (relative, "fire
207 in 10 seconds") and based on wallclock time (absolute, "fire at 12 239 in 10 seconds") and based on wallclock time (absolute, "fire at 12
208 o'clock"). 240 o'clock").
… …
220 on wallclock time) timers. 252 on wallclock time) timers.
221 253
222 AnyEvent always prefers relative timers, if available, matching the 254 AnyEvent always prefers relative timers, if available, matching the
223 AnyEvent API. 255 AnyEvent API.
224 256
257 AnyEvent has two additional methods that return the "current time":
258
259 AnyEvent->time
260 This returns the "current wallclock time" as a fractional number of
261 seconds since the Epoch (the same thing as "time" or
262 "Time::HiRes::time" return, and the result is guaranteed to be
263 compatible with those).
264
265 It progresses independently of any event loop processing, i.e. each
266 call will check the system clock, which usually gets updated
267 frequently.
268
269 AnyEvent->now
270 This also returns the "current wallclock time", but unlike "time",
271 above, this value might change only once per event loop iteration,
272 depending on the event loop (most return the same time as "time",
273 above). This is the time that AnyEvent's timers get scheduled
274 against.
275
276 *In almost all cases (in all cases if you don't care), this is the
277 function to call when you want to know the current time.*
278
279 This function is also often faster then "AnyEvent->time", and thus
280 the preferred method if you want some timestamp (for example,
281 AnyEvent::Handle uses this to update it's activity timeouts).
282
283 The rest of this section is only of relevance if you try to be very
284 exact with your timing, you can skip it without bad conscience.
285
286 For a practical example of when these times differ, consider
287 Event::Lib and EV and the following set-up:
288
289 The event loop is running and has just invoked one of your callback
290 at time=500 (assume no other callbacks delay processing). In your
291 callback, you wait a second by executing "sleep 1" (blocking the
292 process for a second) and then (at time=501) you create a relative
293 timer that fires after three seconds.
294
295 With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both
296 return 501, because that is the current time, and the timer will be
297 scheduled to fire at time=504 (501 + 3).
298
299 With EV, "AnyEvent->time" returns 501 (as that is the current time),
300 but "AnyEvent->now" returns 500, as that is the time the last event
301 processing phase started. With EV, your timer gets scheduled to run
302 at time=503 (500 + 3).
303
304 In one sense, Event::Lib is more exact, as it uses the current time
305 regardless of any delays introduced by event processing. However,
306 most callbacks do not expect large delays in processing, so this
307 causes a higher drift (and a lot more system calls to get the
308 current time).
309
310 In another sense, EV is more exact, as your timer will be scheduled
311 at the same time, regardless of how long event processing actually
312 took.
313
314 In either case, if you care (and in most cases, you don't), then you
315 can get whatever behaviour you want with any event loop, by taking
316 the difference between "AnyEvent->time" and "AnyEvent->now" into
317 account.
318
319 AnyEvent->now_update
320 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
321 current time for each loop iteration (see the discussion of
322 AnyEvent->now, above).
323
324 When a callback runs for a long time (or when the process sleeps),
325 then this "current" time will differ substantially from the real
326 time, which might affect timers and time-outs.
327
328 When this is the case, you can call this method, which will update
329 the event loop's idea of "current time".
330
331 Note that updating the time *might* cause some events to be handled.
332
225 SIGNAL WATCHERS 333 SIGNAL WATCHERS
226 You can watch for signals using a signal watcher, "signal" is the signal 334 You can watch for signals using a signal watcher, "signal" is the signal
227 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked 335 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
228 whenever a signal occurs. 336 callback to be invoked whenever a signal occurs.
229 337
230 Although the callback might get passed parameters, their value and 338 Although the callback might get passed parameters, their value and
231 presence is undefined and you cannot rely on them. Portable AnyEvent 339 presence is undefined and you cannot rely on them. Portable AnyEvent
232 callbacks cannot use arguments passed to signal watcher callbacks. 340 callbacks cannot use arguments passed to signal watcher callbacks.
233 341
… …
248 356
249 CHILD PROCESS WATCHERS 357 CHILD PROCESS WATCHERS
250 You can also watch on a child process exit and catch its exit status. 358 You can also watch on a child process exit and catch its exit status.
251 359
252 The child process is specified by the "pid" argument (if set to 0, it 360 The child process is specified by the "pid" argument (if set to 0, it
253 watches for any child process exit). The watcher will trigger as often 361 watches for any child process exit). The watcher will triggered only
254 as status change for the child are received. This works by installing a 362 when the child process has finished and an exit status is available, not
255 signal handler for "SIGCHLD". The callback will be called with the pid 363 on any trace events (stopped/continued).
256 and exit status (as returned by waitpid), so unlike other watcher types, 364
257 you *can* rely on child watcher callback arguments. 365 The callback will be called with the pid and exit status (as returned by
366 waitpid), so unlike other watcher types, you *can* rely on child watcher
367 callback arguments.
368
369 This watcher type works by installing a signal handler for "SIGCHLD",
370 and since it cannot be shared, nothing else should use SIGCHLD or reap
371 random child processes (waiting for specific child processes, e.g.
372 inside "system", is just fine).
258 373
259 There is a slight catch to child watchers, however: you usually start 374 There is a slight catch to child watchers, however: you usually start
260 them *after* the child process was created, and this means the process 375 them *after* the child process was created, and this means the process
261 could have exited already (and no SIGCHLD will be sent anymore). 376 could have exited already (and no SIGCHLD will be sent anymore).
262 377
… …
269 an AnyEvent program, you *have* to create at least one watcher before 384 an AnyEvent program, you *have* to create at least one watcher before
270 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 385 you "fork" the child (alternatively, you can call "AnyEvent::detect").
271 386
272 Example: fork a process and wait for it 387 Example: fork a process and wait for it
273 388
274 my $done = AnyEvent->condvar; 389 my $done = AnyEvent->condvar;
275 390
276 my $pid = fork or exit 5; 391 my $pid = fork or exit 5;
277 392
278 my $w = AnyEvent->child ( 393 my $w = AnyEvent->child (
279 pid => $pid, 394 pid => $pid,
280 cb => sub { 395 cb => sub {
281 my ($pid, $status) = @_; 396 my ($pid, $status) = @_;
282 warn "pid $pid exited with status $status"; 397 warn "pid $pid exited with status $status";
283 $done->send; 398 $done->send;
284 }, 399 },
285 ); 400 );
286 401
287 # do something else, then wait for process exit 402 # do something else, then wait for process exit
288 $done->recv; 403 $done->recv;
289 404
290 CONDITION VARIABLES 405 CONDITION VARIABLES
291 If you are familiar with some event loops you will know that all of them 406 If you are familiar with some event loops you will know that all of them
292 require you to run some blocking "loop", "run" or similar function that 407 require you to run some blocking "loop", "run" or similar function that
293 will actively watch for new events and call your callbacks. 408 will actively watch for new events and call your callbacks.
… …
298 The instrument to do that is called a "condition variable", so called 413 The instrument to do that is called a "condition variable", so called
299 because they represent a condition that must become true. 414 because they represent a condition that must become true.
300 415
301 Condition variables can be created by calling the "AnyEvent->condvar" 416 Condition variables can be created by calling the "AnyEvent->condvar"
302 method, usually without arguments. The only argument pair allowed is 417 method, usually without arguments. The only argument pair allowed is
418
303 "cb", which specifies a callback to be called when the condition 419 "cb", which specifies a callback to be called when the condition
304 variable becomes true. 420 variable becomes true, with the condition variable as the first argument
421 (but not the results).
305 422
306 After creation, the condition variable is "false" until it becomes 423 After creation, the condition variable is "false" until it becomes
307 "true" by calling the "send" method (or calling the condition variable 424 "true" by calling the "send" method (or calling the condition variable
308 as if it were a callback, read about the caveats in the description for 425 as if it were a callback, read about the caveats in the description for
309 the "->send" method). 426 the "->send" method).
… …
365 482
366 my $done = AnyEvent->condvar; 483 my $done = AnyEvent->condvar;
367 my $delay = AnyEvent->timer (after => 5, cb => $done); 484 my $delay = AnyEvent->timer (after => 5, cb => $done);
368 $done->recv; 485 $done->recv;
369 486
487 Example: Imagine an API that returns a condvar and doesn't support
488 callbacks. This is how you make a synchronous call, for example from the
489 main program:
490
491 use AnyEvent::CouchDB;
492
493 ...
494
495 my @info = $couchdb->info->recv;
496
497 And this is how you would just ste a callback to be called whenever the
498 results are available:
499
500 $couchdb->info->cb (sub {
501 my @info = $_[0]->recv;
502 });
503
370 METHODS FOR PRODUCERS 504 METHODS FOR PRODUCERS
371 These methods should only be used by the producing side, i.e. the 505 These methods should only be used by the producing side, i.e. the
372 code/module that eventually sends the signal. Note that it is also the 506 code/module that eventually sends the signal. Note that it is also the
373 producer side which creates the condvar in most cases, but it isn't 507 producer side which creates the condvar in most cases, but it isn't
374 uncommon for the consumer to create it as well. 508 uncommon for the consumer to create it as well.
… …
494 628
495 $bool = $cv->ready 629 $bool = $cv->ready
496 Returns true when the condition is "true", i.e. whether "send" or 630 Returns true when the condition is "true", i.e. whether "send" or
497 "croak" have been called. 631 "croak" have been called.
498 632
499 $cb = $cv->cb ([new callback]) 633 $cb = $cv->cb ($cb->($cv))
500 This is a mutator function that returns the callback set and 634 This is a mutator function that returns the callback set and
501 optionally replaces it before doing so. 635 optionally replaces it before doing so.
502 636
503 The callback will be called when the condition becomes "true", i.e. 637 The callback will be called when the condition becomes "true", i.e.
504 when "send" or "croak" are called. Calling "recv" inside the 638 when "send" or "croak" are called, with the only argument being the
639 condition variable itself. Calling "recv" inside the callback or at
505 callback or at any later time is guaranteed not to block. 640 any later time is guaranteed not to block.
506 641
507GLOBAL VARIABLES AND FUNCTIONS 642GLOBAL VARIABLES AND FUNCTIONS
508 $AnyEvent::MODEL 643 $AnyEvent::MODEL
509 Contains "undef" until the first watcher is being created. Then it 644 Contains "undef" until the first watcher is being created. Then it
510 contains the event model that is being used, which is the name of 645 contains the event model that is being used, which is the name of
… …
624 AnyEvent::Util 759 AnyEvent::Util
625 Contains various utility functions that replace often-used but 760 Contains various utility functions that replace often-used but
626 blocking functions such as "inet_aton" by event-/callback-based 761 blocking functions such as "inet_aton" by event-/callback-based
627 versions. 762 versions.
628 763
629 AnyEvent::Handle
630 Provide read and write buffers and manages watchers for reads and
631 writes.
632
633 AnyEvent::Socket 764 AnyEvent::Socket
634 Provides various utility functions for (internet protocol) sockets, 765 Provides various utility functions for (internet protocol) sockets,
635 addresses and name resolution. Also functions to create non-blocking 766 addresses and name resolution. Also functions to create non-blocking
636 tcp connections or tcp servers, with IPv6 and SRV record support and 767 tcp connections or tcp servers, with IPv6 and SRV record support and
637 more. 768 more.
638 769
770 AnyEvent::Handle
771 Provide read and write buffers, manages watchers for reads and
772 writes, supports raw and formatted I/O, I/O queued and fully
773 transparent and non-blocking SSL/TLS.
774
639 AnyEvent::DNS 775 AnyEvent::DNS
640 Provides rich asynchronous DNS resolver capabilities. 776 Provides rich asynchronous DNS resolver capabilities.
641 777
778 AnyEvent::HTTP
779 A simple-to-use HTTP library that is capable of making a lot of
780 concurrent HTTP requests.
781
642 AnyEvent::HTTPD 782 AnyEvent::HTTPD
643 Provides a simple web application server framework. 783 Provides a simple web application server framework.
644 784
645 AnyEvent::FastPing 785 AnyEvent::FastPing
646 The fastest ping in the west. 786 The fastest ping in the west.
647 787
788 AnyEvent::DBI
789 Executes DBI requests asynchronously in a proxy process.
790
791 AnyEvent::AIO
792 Truly asynchronous I/O, should be in the toolbox of every event
793 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
794 together.
795
796 AnyEvent::BDB
797 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
798 fuses BDB and AnyEvent together.
799
800 AnyEvent::GPSD
801 A non-blocking interface to gpsd, a daemon delivering GPS
802 information.
803
804 AnyEvent::IGS
805 A non-blocking interface to the Internet Go Server protocol (used by
806 App::IGS).
807
808 AnyEvent::IRC
809 AnyEvent based IRC client module family (replacing the older
648 Net::IRC3 810 Net::IRC3).
649 AnyEvent based IRC client module family.
650 811
651 Net::XMPP2 812 Net::XMPP2
652 AnyEvent based XMPP (Jabber protocol) module family. 813 AnyEvent based XMPP (Jabber protocol) module family.
653 814
654 Net::FCP 815 Net::FCP
… …
659 High level API for event-based execution flow control. 820 High level API for event-based execution flow control.
660 821
661 Coro 822 Coro
662 Has special support for AnyEvent via Coro::AnyEvent. 823 Has special support for AnyEvent via Coro::AnyEvent.
663 824
664 AnyEvent::AIO, IO::AIO
665 Truly asynchronous I/O, should be in the toolbox of every event
666 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
667 together.
668
669 AnyEvent::BDB, BDB
670 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
671 fuses IO::AIO and AnyEvent together.
672
673 IO::Lambda 825 IO::Lambda
674 The lambda approach to I/O - don't ask, look there. Can use 826 The lambda approach to I/O - don't ask, look there. Can use
675 AnyEvent. 827 AnyEvent.
676 828
677SUPPLYING YOUR OWN EVENT MODEL INTERFACE 829ERROR AND EXCEPTION HANDLING
678 This is an advanced topic that you do not normally need to use AnyEvent 830 In general, AnyEvent does not do any error handling - it relies on the
679 in a module. This section is only of use to event loop authors who want 831 caller to do that if required. The AnyEvent::Strict module (see also the
680 to provide AnyEvent compatibility. 832 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
833 checking of all AnyEvent methods, however, which is highly useful during
834 development.
681 835
682 If you need to support another event library which isn't directly 836 As for exception handling (i.e. runtime errors and exceptions thrown
683 supported by AnyEvent, you can supply your own interface to it by 837 while executing a callback), this is not only highly event-loop
684 pushing, before the first watcher gets created, the package name of the 838 specific, but also not in any way wrapped by this module, as this is the
685 event module and the package name of the interface to use onto 839 job of the main program.
686 @AnyEvent::REGISTRY. You can do that before and even without loading
687 AnyEvent, so it is reasonably cheap.
688 840
689 Example: 841 The pure perl event loop simply re-throws the exception (usually within
690 842 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
691 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 843 Glib uses "install_exception_handler" and so on.
692
693 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
694 package/class when it finds the "urxvt" package/module is already
695 loaded.
696
697 When AnyEvent is loaded and asked to find a suitable event model, it
698 will first check for the presence of urxvt by trying to "use" the
699 "urxvt::anyevent" module.
700
701 The class should provide implementations for all watcher types. See
702 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
703 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
704 the sources.
705
706 If you don't provide "signal" and "child" watchers than AnyEvent will
707 provide suitable (hopefully) replacements.
708
709 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
710 terminal emulator uses the above line as-is. An interface isn't included
711 in AnyEvent because it doesn't make sense outside the embedded
712 interpreter inside *rxvt-unicode*, and it is updated and maintained as
713 part of the *rxvt-unicode* distribution.
714
715 *rxvt-unicode* also cheats a bit by not providing blocking access to
716 condition variables: code blocking while waiting for a condition will
717 "die". This still works with most modules/usages, and blocking calls
718 must not be done in an interactive application, so it makes sense.
719 844
720ENVIRONMENT VARIABLES 845ENVIRONMENT VARIABLES
721 The following environment variables are used by this module: 846 The following environment variables are used by this module or its
847 submodules:
722 848
723 "PERL_ANYEVENT_VERBOSE" 849 "PERL_ANYEVENT_VERBOSE"
724 By default, AnyEvent will be completely silent except in fatal 850 By default, AnyEvent will be completely silent except in fatal
725 conditions. You can set this environment variable to make AnyEvent 851 conditions. You can set this environment variable to make AnyEvent
726 more talkative. 852 more talkative.
… …
729 conditions, such as not being able to load the event model specified 855 conditions, such as not being able to load the event model specified
730 by "PERL_ANYEVENT_MODEL". 856 by "PERL_ANYEVENT_MODEL".
731 857
732 When set to 2 or higher, cause AnyEvent to report to STDERR which 858 When set to 2 or higher, cause AnyEvent to report to STDERR which
733 event model it chooses. 859 event model it chooses.
860
861 "PERL_ANYEVENT_STRICT"
862 AnyEvent does not do much argument checking by default, as thorough
863 argument checking is very costly. Setting this variable to a true
864 value will cause AnyEvent to load "AnyEvent::Strict" and then to
865 thoroughly check the arguments passed to most method calls. If it
866 finds any problems it will croak.
867
868 In other words, enables "strict" mode.
869
870 Unlike "use strict", it is definitely recommended ot keep it off in
871 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
872 while developing programs can be very useful, however.
734 873
735 "PERL_ANYEVENT_MODEL" 874 "PERL_ANYEVENT_MODEL"
736 This can be used to specify the event model to be used by AnyEvent, 875 This can be used to specify the event model to be used by AnyEvent,
737 before auto detection and -probing kicks in. It must be a string 876 before auto detection and -probing kicks in. It must be a string
738 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 877 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
743 This functionality might change in future versions. 882 This functionality might change in future versions.
744 883
745 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 884 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
746 could start your program like this: 885 could start your program like this:
747 886
748 PERL_ANYEVENT_MODEL=Perl perl ... 887 PERL_ANYEVENT_MODEL=Perl perl ...
749 888
750 "PERL_ANYEVENT_PROTOCOLS" 889 "PERL_ANYEVENT_PROTOCOLS"
751 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 890 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
752 preferences for IPv4 or IPv6. The default is unspecified (and might 891 preferences for IPv4 or IPv6. The default is unspecified (and might
753 change, or be the result of auto probing). 892 change, or be the result of auto probing).
… …
757 mentioned will be used, and preference will be given to protocols 896 mentioned will be used, and preference will be given to protocols
758 mentioned earlier in the list. 897 mentioned earlier in the list.
759 898
760 This variable can effectively be used for denial-of-service attacks 899 This variable can effectively be used for denial-of-service attacks
761 against local programs (e.g. when setuid), although the impact is 900 against local programs (e.g. when setuid), although the impact is
762 likely small, as the program has to handle connection errors 901 likely small, as the program has to handle conenction and other
763 already- 902 failures anyways.
764 903
765 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 904 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
766 IPv6, but support both and try to use both. 905 IPv6, but support both and try to use both.
767 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 906 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
768 resolve or contact IPv6 addresses. 907 resolve or contact IPv6 addresses.
… …
775 but some (broken) firewalls drop such DNS packets, which is why it 914 but some (broken) firewalls drop such DNS packets, which is why it
776 is off by default. 915 is off by default.
777 916
778 Setting this variable to 1 will cause AnyEvent::DNS to announce 917 Setting this variable to 1 will cause AnyEvent::DNS to announce
779 EDNS0 in its DNS requests. 918 EDNS0 in its DNS requests.
919
920 "PERL_ANYEVENT_MAX_FORKS"
921 The maximum number of child processes that
922 "AnyEvent::Util::fork_call" will create in parallel.
923
924SUPPLYING YOUR OWN EVENT MODEL INTERFACE
925 This is an advanced topic that you do not normally need to use AnyEvent
926 in a module. This section is only of use to event loop authors who want
927 to provide AnyEvent compatibility.
928
929 If you need to support another event library which isn't directly
930 supported by AnyEvent, you can supply your own interface to it by
931 pushing, before the first watcher gets created, the package name of the
932 event module and the package name of the interface to use onto
933 @AnyEvent::REGISTRY. You can do that before and even without loading
934 AnyEvent, so it is reasonably cheap.
935
936 Example:
937
938 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
939
940 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
941 package/class when it finds the "urxvt" package/module is already
942 loaded.
943
944 When AnyEvent is loaded and asked to find a suitable event model, it
945 will first check for the presence of urxvt by trying to "use" the
946 "urxvt::anyevent" module.
947
948 The class should provide implementations for all watcher types. See
949 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
950 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
951 the sources.
952
953 If you don't provide "signal" and "child" watchers than AnyEvent will
954 provide suitable (hopefully) replacements.
955
956 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
957 terminal emulator uses the above line as-is. An interface isn't included
958 in AnyEvent because it doesn't make sense outside the embedded
959 interpreter inside *rxvt-unicode*, and it is updated and maintained as
960 part of the *rxvt-unicode* distribution.
961
962 *rxvt-unicode* also cheats a bit by not providing blocking access to
963 condition variables: code blocking while waiting for a condition will
964 "die". This still works with most modules/usages, and blocking calls
965 must not be done in an interactive application, so it makes sense.
780 966
781EXAMPLE PROGRAM 967EXAMPLE PROGRAM
782 The following program uses an I/O watcher to read data from STDIN, a 968 The following program uses an I/O watcher to read data from STDIN, a
783 timer to display a message once per second, and a condition variable to 969 timer to display a message once per second, and a condition variable to
784 quit the program when the user enters quit: 970 quit the program when the user enters quit:
… …
971 *destroy* is the time, in microseconds, that it takes to destroy a 1157 *destroy* is the time, in microseconds, that it takes to destroy a
972 single watcher. 1158 single watcher.
973 1159
974 Results 1160 Results
975 name watchers bytes create invoke destroy comment 1161 name watchers bytes create invoke destroy comment
976 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1162 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
977 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1163 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
978 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1164 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
979 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1165 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
980 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1166 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
981 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1167 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
982 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1168 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
983 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1169 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
984 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1170 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
985 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1171 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
986 1172
987 Discussion 1173 Discussion
988 The benchmark does *not* measure scalability of the event loop very 1174 The benchmark does *not* measure scalability of the event loop very
989 well. For example, a select-based event loop (such as the pure perl one) 1175 well. For example, a select-based event loop (such as the pure perl one)
990 can never compete with an event loop that uses epoll when the number of 1176 can never compete with an event loop that uses epoll when the number of
… …
1171 1357
1172 Summary 1358 Summary
1173 * C-based event loops perform very well with small number of watchers, 1359 * C-based event loops perform very well with small number of watchers,
1174 as the management overhead dominates. 1360 as the management overhead dominates.
1175 1361
1362SIGNALS
1363 AnyEvent currently installs handlers for these signals:
1364
1365 SIGCHLD
1366 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1367 emulation for event loops that do not support them natively. Also,
1368 some event loops install a similar handler.
1369
1370 SIGPIPE
1371 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1372 "undef" when AnyEvent gets loaded.
1373
1374 The rationale for this is that AnyEvent users usually do not really
1375 depend on SIGPIPE delivery (which is purely an optimisation for
1376 shell use, or badly-written programs), but "SIGPIPE" can cause
1377 spurious and rare program exits as a lot of people do not expect
1378 "SIGPIPE" when writing to some random socket.
1379
1380 The rationale for installing a no-op handler as opposed to ignoring
1381 it is that this way, the handler will be restored to defaults on
1382 exec.
1383
1384 Feel free to install your own handler, or reset it to defaults.
1385
1176FORK 1386FORK
1177 Most event libraries are not fork-safe. The ones who are usually are 1387 Most event libraries are not fork-safe. The ones who are usually are
1178 because they rely on inefficient but fork-safe "select" or "poll" calls. 1388 because they rely on inefficient but fork-safe "select" or "poll" calls.
1179 Only EV is fully fork-aware. 1389 Only EV is fully fork-aware.
1180 1390
… …
1190 model than specified in the variable. 1400 model than specified in the variable.
1191 1401
1192 You can make AnyEvent completely ignore this variable by deleting it 1402 You can make AnyEvent completely ignore this variable by deleting it
1193 before the first watcher gets created, e.g. with a "BEGIN" block: 1403 before the first watcher gets created, e.g. with a "BEGIN" block:
1194 1404
1195 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1405 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1196 1406
1197 use AnyEvent; 1407 use AnyEvent;
1198 1408
1199 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1409 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1200 be used to probe what backend is used and gain other information (which 1410 be used to probe what backend is used and gain other information (which
1201 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1411 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1412 and $ENV{PERL_ANYEGENT_STRICT}.
1413
1414BUGS
1415 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1416 hard to work around. If you suffer from memleaks, first upgrade to Perl
1417 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1418 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1419 not as pronounced).
1202 1420
1203SEE ALSO 1421SEE ALSO
1204 Utility functions: AnyEvent::Util. 1422 Utility functions: AnyEvent::Util.
1205 1423
1206 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1424 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
… …
1218 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1436 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1219 1437
1220 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1438 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
1221 1439
1222AUTHOR 1440AUTHOR
1223 Marc Lehmann <schmorp@schmorp.de> 1441 Marc Lehmann <schmorp@schmorp.de>
1224 http://home.schmorp.de/ 1442 http://home.schmorp.de/
1225 1443

Diff Legend

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