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

Comparing AnyEvent/README (file contents):
Revision 1.22 by root, Sat May 24 17:58:33 2008 UTC vs.
Revision 1.33 by root, Thu Oct 30 03:43:13 2008 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.
… …
122 Many watchers either are used with "recursion" (repeating timers for 143 Many watchers either are used with "recursion" (repeating timers for
123 example), or need to refer to their watcher object in other ways. 144 example), or need to refer to their watcher object in other ways.
124 145
125 An any way to achieve that is this pattern: 146 An any way to achieve that is this pattern:
126 147
127 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 148 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
128 # you can use $w here, for example to undef it 149 # you can use $w here, for example to undef it
129 undef $w; 150 undef $w;
130 }); 151 });
131 152
132 Note that "my $w; $w =" combination. This is necessary because in Perl, 153 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 154 my variables are only visible after the statement in which they are
134 declared. 155 declared.
135 156
136 I/O WATCHERS 157 I/O WATCHERS
137 You can create an I/O watcher by calling the "AnyEvent->io" method with 158 You can create an I/O watcher by calling the "AnyEvent->io" method with
138 the following mandatory key-value pairs as arguments: 159 the following mandatory key-value pairs as arguments:
139 160
140 "fh" the Perl *file handle* (*not* file descriptor) to watch for events. 161 "fh" the Perl *file handle* (*not* file descriptor) to watch for events
162 (AnyEvent might or might not keep a reference to this file handle).
141 "poll" must be a string that is either "r" or "w", which creates a 163 "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" 164 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"
143 is the callback to invoke each time the file handle becomes ready. 165 is the callback to invoke each time the file handle becomes ready.
144 166
145 Although the callback might get passed parameters, their value and 167 Although the callback might get passed parameters, their value and
… …
152 174
153 Some event loops issue spurious readyness notifications, so you should 175 Some event loops issue spurious readyness notifications, so you should
154 always use non-blocking calls when reading/writing from/to your file 176 always use non-blocking calls when reading/writing from/to your file
155 handles. 177 handles.
156 178
157 Example:
158
159 # wait for readability of STDIN, then read a line and disable the watcher 179 Example: wait for readability of STDIN, then read a line and disable the
180 watcher.
181
160 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 182 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
161 chomp (my $input = <STDIN>); 183 chomp (my $input = <STDIN>);
162 warn "read: $input\n"; 184 warn "read: $input\n";
163 undef $w; 185 undef $w;
164 }); 186 });
… …
173 195
174 Although the callback might get passed parameters, their value and 196 Although the callback might get passed parameters, their value and
175 presence is undefined and you cannot rely on them. Portable AnyEvent 197 presence is undefined and you cannot rely on them. Portable AnyEvent
176 callbacks cannot use arguments passed to time watcher callbacks. 198 callbacks cannot use arguments passed to time watcher callbacks.
177 199
178 The timer callback will be invoked at most once: if you want a repeating 200 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 201 parameter, "interval", as a strictly positive number (> 0), then the
180 and Glib). 202 callback will be invoked regularly at that interval (in fractional
203 seconds) after the first invocation. If "interval" is specified with a
204 false value, then it is treated as if it were missing.
181 205
182 Example: 206 The callback will be rescheduled before invoking the callback, but no
207 attempt is done to avoid timer drift in most backends, so the interval
208 is only approximate.
183 209
184 # fire an event after 7.7 seconds 210 Example: fire an event after 7.7 seconds.
211
185 my $w = AnyEvent->timer (after => 7.7, cb => sub { 212 my $w = AnyEvent->timer (after => 7.7, cb => sub {
186 warn "timeout\n"; 213 warn "timeout\n";
187 }); 214 });
188 215
189 # to cancel the timer: 216 # to cancel the timer:
190 undef $w; 217 undef $w;
191 218
192 Example 2:
193
194 # fire an event after 0.5 seconds, then roughly every second 219 Example 2: fire an event after 0.5 seconds, then roughly every second.
195 my $w;
196 220
197 my $cb = sub {
198 # cancel the old timer while creating a new one
199 $w = AnyEvent->timer (after => 1, cb => $cb); 221 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
222 warn "timeout\n";
200 }; 223 };
201
202 # start the "loop" by creating the first watcher
203 $w = AnyEvent->timer (after => 0.5, cb => $cb);
204 224
205 TIMING ISSUES 225 TIMING ISSUES
206 There are two ways to handle timers: based on real time (relative, "fire 226 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 227 in 10 seconds") and based on wallclock time (absolute, "fire at 12
208 o'clock"). 228 o'clock").
… …
220 on wallclock time) timers. 240 on wallclock time) timers.
221 241
222 AnyEvent always prefers relative timers, if available, matching the 242 AnyEvent always prefers relative timers, if available, matching the
223 AnyEvent API. 243 AnyEvent API.
224 244
245 AnyEvent has two additional methods that return the "current time":
246
247 AnyEvent->time
248 This returns the "current wallclock time" as a fractional number of
249 seconds since the Epoch (the same thing as "time" or
250 "Time::HiRes::time" return, and the result is guaranteed to be
251 compatible with those).
252
253 It progresses independently of any event loop processing, i.e. each
254 call will check the system clock, which usually gets updated
255 frequently.
256
257 AnyEvent->now
258 This also returns the "current wallclock time", but unlike "time",
259 above, this value might change only once per event loop iteration,
260 depending on the event loop (most return the same time as "time",
261 above). This is the time that AnyEvent's timers get scheduled
262 against.
263
264 *In almost all cases (in all cases if you don't care), this is the
265 function to call when you want to know the current time.*
266
267 This function is also often faster then "AnyEvent->time", and thus
268 the preferred method if you want some timestamp (for example,
269 AnyEvent::Handle uses this to update it's activity timeouts).
270
271 The rest of this section is only of relevance if you try to be very
272 exact with your timing, you can skip it without bad conscience.
273
274 For a practical example of when these times differ, consider
275 Event::Lib and EV and the following set-up:
276
277 The event loop is running and has just invoked one of your callback
278 at time=500 (assume no other callbacks delay processing). In your
279 callback, you wait a second by executing "sleep 1" (blocking the
280 process for a second) and then (at time=501) you create a relative
281 timer that fires after three seconds.
282
283 With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both
284 return 501, because that is the current time, and the timer will be
285 scheduled to fire at time=504 (501 + 3).
286
287 With EV, "AnyEvent->time" returns 501 (as that is the current time),
288 but "AnyEvent->now" returns 500, as that is the time the last event
289 processing phase started. With EV, your timer gets scheduled to run
290 at time=503 (500 + 3).
291
292 In one sense, Event::Lib is more exact, as it uses the current time
293 regardless of any delays introduced by event processing. However,
294 most callbacks do not expect large delays in processing, so this
295 causes a higher drift (and a lot more system calls to get the
296 current time).
297
298 In another sense, EV is more exact, as your timer will be scheduled
299 at the same time, regardless of how long event processing actually
300 took.
301
302 In either case, if you care (and in most cases, you don't), then you
303 can get whatever behaviour you want with any event loop, by taking
304 the difference between "AnyEvent->time" and "AnyEvent->now" into
305 account.
306
225 SIGNAL WATCHERS 307 SIGNAL WATCHERS
226 You can watch for signals using a signal watcher, "signal" is the signal 308 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 309 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
228 whenever a signal occurs. 310 callback to be invoked whenever a signal occurs.
229 311
230 Although the callback might get passed parameters, their value and 312 Although the callback might get passed parameters, their value and
231 presence is undefined and you cannot rely on them. Portable AnyEvent 313 presence is undefined and you cannot rely on them. Portable AnyEvent
232 callbacks cannot use arguments passed to signal watcher callbacks. 314 callbacks cannot use arguments passed to signal watcher callbacks.
233 315
… …
248 330
249 CHILD PROCESS WATCHERS 331 CHILD PROCESS WATCHERS
250 You can also watch on a child process exit and catch its exit status. 332 You can also watch on a child process exit and catch its exit status.
251 333
252 The child process is specified by the "pid" argument (if set to 0, it 334 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 335 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 336 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 337 on any trace events (stopped/continued).
256 and exit status (as returned by waitpid), so unlike other watcher types, 338
257 you *can* rely on child watcher callback arguments. 339 The callback will be called with the pid and exit status (as returned by
340 waitpid), so unlike other watcher types, you *can* rely on child watcher
341 callback arguments.
342
343 This watcher type works by installing a signal handler for "SIGCHLD",
344 and since it cannot be shared, nothing else should use SIGCHLD or reap
345 random child processes (waiting for specific child processes, e.g.
346 inside "system", is just fine).
258 347
259 There is a slight catch to child watchers, however: you usually start 348 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 349 them *after* the child process was created, and this means the process
261 could have exited already (and no SIGCHLD will be sent anymore). 350 could have exited already (and no SIGCHLD will be sent anymore).
262 351
… …
269 an AnyEvent program, you *have* to create at least one watcher before 358 an AnyEvent program, you *have* to create at least one watcher before
270 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 359 you "fork" the child (alternatively, you can call "AnyEvent::detect").
271 360
272 Example: fork a process and wait for it 361 Example: fork a process and wait for it
273 362
274 my $done = AnyEvent->condvar; 363 my $done = AnyEvent->condvar;
275 364
276 my $pid = fork or exit 5; 365 my $pid = fork or exit 5;
277 366
278 my $w = AnyEvent->child ( 367 my $w = AnyEvent->child (
279 pid => $pid, 368 pid => $pid,
280 cb => sub { 369 cb => sub {
281 my ($pid, $status) = @_; 370 my ($pid, $status) = @_;
282 warn "pid $pid exited with status $status"; 371 warn "pid $pid exited with status $status";
283 $done->send; 372 $done->send;
284 }, 373 },
285 ); 374 );
286 375
287 # do something else, then wait for process exit 376 # do something else, then wait for process exit
288 $done->recv; 377 $done->recv;
289 378
290 CONDITION VARIABLES 379 CONDITION VARIABLES
291 If you are familiar with some event loops you will know that all of them 380 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 381 require you to run some blocking "loop", "run" or similar function that
293 will actively watch for new events and call your callbacks. 382 will actively watch for new events and call your callbacks.
… …
298 The instrument to do that is called a "condition variable", so called 387 The instrument to do that is called a "condition variable", so called
299 because they represent a condition that must become true. 388 because they represent a condition that must become true.
300 389
301 Condition variables can be created by calling the "AnyEvent->condvar" 390 Condition variables can be created by calling the "AnyEvent->condvar"
302 method, usually without arguments. The only argument pair allowed is 391 method, usually without arguments. The only argument pair allowed is
392
303 "cb", which specifies a callback to be called when the condition 393 "cb", which specifies a callback to be called when the condition
304 variable becomes true. 394 variable becomes true, with the condition variable as the first argument
395 (but not the results).
305 396
306 After creation, the condition variable is "false" until it becomes 397 After creation, the condition variable is "false" until it becomes
307 "true" by calling the "send" method (or calling the condition variable 398 "true" by calling the "send" method (or calling the condition variable
308 as if it were a callback). 399 as if it were a callback, read about the caveats in the description for
400 the "->send" method).
309 401
310 Condition variables are similar to callbacks, except that you can 402 Condition variables are similar to callbacks, except that you can
311 optionally wait for them. They can also be called merge points - points 403 optionally wait for them. They can also be called merge points - points
312 in time where multiple outstanding events have been processed. And yet 404 in time where multiple outstanding events have been processed. And yet
313 another way to call them is transactions - each condition variable can 405 another way to call them is transactions - each condition variable can
… …
364 456
365 my $done = AnyEvent->condvar; 457 my $done = AnyEvent->condvar;
366 my $delay = AnyEvent->timer (after => 5, cb => $done); 458 my $delay = AnyEvent->timer (after => 5, cb => $done);
367 $done->recv; 459 $done->recv;
368 460
461 Example: Imagine an API that returns a condvar and doesn't support
462 callbacks. This is how you make a synchronous call, for example from the
463 main program:
464
465 use AnyEvent::CouchDB;
466
467 ...
468
469 my @info = $couchdb->info->recv;
470
471 And this is how you would just ste a callback to be called whenever the
472 results are available:
473
474 $couchdb->info->cb (sub {
475 my @info = $_[0]->recv;
476 });
477
369 METHODS FOR PRODUCERS 478 METHODS FOR PRODUCERS
370 These methods should only be used by the producing side, i.e. the 479 These methods should only be used by the producing side, i.e. the
371 code/module that eventually sends the signal. Note that it is also the 480 code/module that eventually sends the signal. Note that it is also the
372 producer side which creates the condvar in most cases, but it isn't 481 producer side which creates the condvar in most cases, but it isn't
373 uncommon for the consumer to create it as well. 482 uncommon for the consumer to create it as well.
… …
383 Any arguments passed to the "send" call will be returned by all 492 Any arguments passed to the "send" call will be returned by all
384 future "->recv" calls. 493 future "->recv" calls.
385 494
386 Condition variables are overloaded so one can call them directly (as 495 Condition variables are overloaded so one can call them directly (as
387 a code reference). Calling them directly is the same as calling 496 a code reference). Calling them directly is the same as calling
388 "send". 497 "send". Note, however, that many C-based event loops do not handle
498 overloading, so as tempting as it may be, passing a condition
499 variable instead of a callback does not work. Both the pure perl and
500 EV loops support overloading, however, as well as all functions that
501 use perl to invoke a callback (as in AnyEvent::Socket and
502 AnyEvent::DNS for example).
389 503
390 $cv->croak ($error) 504 $cv->croak ($error)
391 Similar to send, but causes all call's to "->recv" to invoke 505 Similar to send, but causes all call's to "->recv" to invoke
392 "Carp::croak" with the given error message/object/scalar. 506 "Carp::croak" with the given error message/object/scalar.
393 507
… …
488 602
489 $bool = $cv->ready 603 $bool = $cv->ready
490 Returns true when the condition is "true", i.e. whether "send" or 604 Returns true when the condition is "true", i.e. whether "send" or
491 "croak" have been called. 605 "croak" have been called.
492 606
493 $cb = $cv->cb ([new callback]) 607 $cb = $cv->cb ($cb->($cv))
494 This is a mutator function that returns the callback set and 608 This is a mutator function that returns the callback set and
495 optionally replaces it before doing so. 609 optionally replaces it before doing so.
496 610
497 The callback will be called when the condition becomes "true", i.e. 611 The callback will be called when the condition becomes "true", i.e.
498 when "send" or "croak" are called. Calling "recv" inside the 612 when "send" or "croak" are called, with the only argument being the
613 condition variable itself. Calling "recv" inside the callback or at
499 callback or at any later time is guaranteed not to block. 614 any later time is guaranteed not to block.
500 615
501GLOBAL VARIABLES AND FUNCTIONS 616GLOBAL VARIABLES AND FUNCTIONS
502 $AnyEvent::MODEL 617 $AnyEvent::MODEL
503 Contains "undef" until the first watcher is being created. Then it 618 Contains "undef" until the first watcher is being created. Then it
504 contains the event model that is being used, which is the name of 619 contains the event model that is being used, which is the name of
… …
578 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 693 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
579 do anything special (it does not need to be event-based) and let 694 do anything special (it does not need to be event-based) and let
580 AnyEvent decide which implementation to chose if some module relies on 695 AnyEvent decide which implementation to chose if some module relies on
581 it. 696 it.
582 697
583 If the main program relies on a specific event model. For example, in 698 If the main program relies on a specific event model - for example, in
584 Gtk2 programs you have to rely on the Glib module. You should load the 699 Gtk2 programs you have to rely on the Glib module - you should load the
585 event module before loading AnyEvent or any module that uses it: 700 event module before loading AnyEvent or any module that uses it:
586 generally speaking, you should load it as early as possible. The reason 701 generally speaking, you should load it as early as possible. The reason
587 is that modules might create watchers when they are loaded, and AnyEvent 702 is that modules might create watchers when they are loaded, and AnyEvent
588 will decide on the event model to use as soon as it creates watchers, 703 will decide on the event model to use as soon as it creates watchers,
589 and it might chose the wrong one unless you load the correct one 704 and it might chose the wrong one unless you load the correct one
590 yourself. 705 yourself.
591 706
592 You can chose to use a rather inefficient pure-perl implementation by 707 You can chose to use a pure-perl implementation by loading the
593 loading the "AnyEvent::Impl::Perl" module, which gives you similar 708 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
594 behaviour everywhere, but letting AnyEvent chose is generally better. 709 everywhere, but letting AnyEvent chose the model is generally better.
710
711 MAINLOOP EMULATION
712 Sometimes (often for short test scripts, or even standalone programs who
713 only want to use AnyEvent), you do not want to run a specific event
714 loop.
715
716 In that case, you can use a condition variable like this:
717
718 AnyEvent->condvar->recv;
719
720 This has the effect of entering the event loop and looping forever.
721
722 Note that usually your program has some exit condition, in which case it
723 is better to use the "traditional" approach of storing a condition
724 variable somewhere, waiting for it, and sending it when the program
725 should exit cleanly.
595 726
596OTHER MODULES 727OTHER MODULES
597 The following is a non-exhaustive list of additional modules that use 728 The following is a non-exhaustive list of additional modules that use
598 AnyEvent and can therefore be mixed easily with other AnyEvent modules 729 AnyEvent and can therefore be mixed easily with other AnyEvent modules
599 in the same program. Some of the modules come with AnyEvent, some are 730 in the same program. Some of the modules come with AnyEvent, some are
… …
602 AnyEvent::Util 733 AnyEvent::Util
603 Contains various utility functions that replace often-used but 734 Contains various utility functions that replace often-used but
604 blocking functions such as "inet_aton" by event-/callback-based 735 blocking functions such as "inet_aton" by event-/callback-based
605 versions. 736 versions.
606 737
607 AnyEvent::Handle
608 Provide read and write buffers and manages watchers for reads and
609 writes.
610
611 AnyEvent::Socket 738 AnyEvent::Socket
612 Provides various utility functions for (internet protocol) sockets, 739 Provides various utility functions for (internet protocol) sockets,
613 addresses and name resolution. Also functions to create non-blocking 740 addresses and name resolution. Also functions to create non-blocking
614 tcp connections or tcp servers, with IPv6 and SRV record support and 741 tcp connections or tcp servers, with IPv6 and SRV record support and
615 more. 742 more.
616 743
744 AnyEvent::Handle
745 Provide read and write buffers, manages watchers for reads and
746 writes, supports raw and formatted I/O, I/O queued and fully
747 transparent and non-blocking SSL/TLS.
748
749 AnyEvent::DNS
750 Provides rich asynchronous DNS resolver capabilities.
751
752 AnyEvent::HTTP
753 A simple-to-use HTTP library that is capable of making a lot of
754 concurrent HTTP requests.
755
617 AnyEvent::HTTPD 756 AnyEvent::HTTPD
618 Provides a simple web application server framework. 757 Provides a simple web application server framework.
619 758
620 AnyEvent::DNS
621 Provides rich asynchronous DNS resolver capabilities.
622
623 AnyEvent::FastPing 759 AnyEvent::FastPing
624 The fastest ping in the west. 760 The fastest ping in the west.
625 761
762 AnyEvent::DBI
763 Executes DBI requests asynchronously in a proxy process.
764
765 AnyEvent::AIO
766 Truly asynchronous I/O, should be in the toolbox of every event
767 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
768 together.
769
770 AnyEvent::BDB
771 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
772 fuses BDB and AnyEvent together.
773
774 AnyEvent::GPSD
775 A non-blocking interface to gpsd, a daemon delivering GPS
776 information.
777
778 AnyEvent::IGS
779 A non-blocking interface to the Internet Go Server protocol (used by
780 App::IGS).
781
782 AnyEvent::IRC
783 AnyEvent based IRC client module family (replacing the older
626 Net::IRC3 784 Net::IRC3).
627 AnyEvent based IRC client module family.
628 785
629 Net::XMPP2 786 Net::XMPP2
630 AnyEvent based XMPP (Jabber protocol) module family. 787 AnyEvent based XMPP (Jabber protocol) module family.
631 788
632 Net::FCP 789 Net::FCP
… …
637 High level API for event-based execution flow control. 794 High level API for event-based execution flow control.
638 795
639 Coro 796 Coro
640 Has special support for AnyEvent via Coro::AnyEvent. 797 Has special support for AnyEvent via Coro::AnyEvent.
641 798
642 AnyEvent::AIO, IO::AIO
643 Truly asynchronous I/O, should be in the toolbox of every event
644 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
645 together.
646
647 AnyEvent::BDB, BDB
648 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
649 fuses IO::AIO and AnyEvent together.
650
651 IO::Lambda 799 IO::Lambda
652 The lambda approach to I/O - don't ask, look there. Can use 800 The lambda approach to I/O - don't ask, look there. Can use
653 AnyEvent. 801 AnyEvent.
654 802
655SUPPLYING YOUR OWN EVENT MODEL INTERFACE 803ERROR AND EXCEPTION HANDLING
656 This is an advanced topic that you do not normally need to use AnyEvent 804 In general, AnyEvent does not do any error handling - it relies on the
657 in a module. This section is only of use to event loop authors who want 805 caller to do that if required. The AnyEvent::Strict module (see also the
658 to provide AnyEvent compatibility. 806 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
807 checking of all AnyEvent methods, however, which is highly useful during
808 development.
659 809
660 If you need to support another event library which isn't directly 810 As for exception handling (i.e. runtime errors and exceptions thrown
661 supported by AnyEvent, you can supply your own interface to it by 811 while executing a callback), this is not only highly event-loop
662 pushing, before the first watcher gets created, the package name of the 812 specific, but also not in any way wrapped by this module, as this is the
663 event module and the package name of the interface to use onto 813 job of the main program.
664 @AnyEvent::REGISTRY. You can do that before and even without loading
665 AnyEvent, so it is reasonably cheap.
666 814
667 Example: 815 The pure perl event loop simply re-throws the exception (usually within
668 816 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
669 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 817 Glib uses "install_exception_handler" and so on.
670
671 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
672 package/class when it finds the "urxvt" package/module is already
673 loaded.
674
675 When AnyEvent is loaded and asked to find a suitable event model, it
676 will first check for the presence of urxvt by trying to "use" the
677 "urxvt::anyevent" module.
678
679 The class should provide implementations for all watcher types. See
680 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
681 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
682 the sources.
683
684 If you don't provide "signal" and "child" watchers than AnyEvent will
685 provide suitable (hopefully) replacements.
686
687 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
688 terminal emulator uses the above line as-is. An interface isn't included
689 in AnyEvent because it doesn't make sense outside the embedded
690 interpreter inside *rxvt-unicode*, and it is updated and maintained as
691 part of the *rxvt-unicode* distribution.
692
693 *rxvt-unicode* also cheats a bit by not providing blocking access to
694 condition variables: code blocking while waiting for a condition will
695 "die". This still works with most modules/usages, and blocking calls
696 must not be done in an interactive application, so it makes sense.
697 818
698ENVIRONMENT VARIABLES 819ENVIRONMENT VARIABLES
699 The following environment variables are used by this module: 820 The following environment variables are used by this module or its
821 submodules:
700 822
701 "PERL_ANYEVENT_VERBOSE" 823 "PERL_ANYEVENT_VERBOSE"
702 By default, AnyEvent will be completely silent except in fatal 824 By default, AnyEvent will be completely silent except in fatal
703 conditions. You can set this environment variable to make AnyEvent 825 conditions. You can set this environment variable to make AnyEvent
704 more talkative. 826 more talkative.
… …
707 conditions, such as not being able to load the event model specified 829 conditions, such as not being able to load the event model specified
708 by "PERL_ANYEVENT_MODEL". 830 by "PERL_ANYEVENT_MODEL".
709 831
710 When set to 2 or higher, cause AnyEvent to report to STDERR which 832 When set to 2 or higher, cause AnyEvent to report to STDERR which
711 event model it chooses. 833 event model it chooses.
834
835 "PERL_ANYEVENT_STRICT"
836 AnyEvent does not do much argument checking by default, as thorough
837 argument checking is very costly. Setting this variable to a true
838 value will cause AnyEvent to load "AnyEvent::Strict" and then to
839 thoroughly check the arguments passed to most method calls. If it
840 finds any problems it will croak.
841
842 In other words, enables "strict" mode.
843
844 Unlike "use strict", it is definitely recommended ot keep it off in
845 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
846 while developing programs can be very useful, however.
712 847
713 "PERL_ANYEVENT_MODEL" 848 "PERL_ANYEVENT_MODEL"
714 This can be used to specify the event model to be used by AnyEvent, 849 This can be used to specify the event model to be used by AnyEvent,
715 before auto detection and -probing kicks in. It must be a string 850 before auto detection and -probing kicks in. It must be a string
716 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 851 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
721 This functionality might change in future versions. 856 This functionality might change in future versions.
722 857
723 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 858 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
724 could start your program like this: 859 could start your program like this:
725 860
726 PERL_ANYEVENT_MODEL=Perl perl ... 861 PERL_ANYEVENT_MODEL=Perl perl ...
727 862
728 "PERL_ANYEVENT_PROTOCOLS" 863 "PERL_ANYEVENT_PROTOCOLS"
729 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 864 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
730 preferences for IPv4 or IPv6. The default is unspecified (and might 865 preferences for IPv4 or IPv6. The default is unspecified (and might
731 change, or be the result of auto probing). 866 change, or be the result of auto probing).
… …
753 but some (broken) firewalls drop such DNS packets, which is why it 888 but some (broken) firewalls drop such DNS packets, which is why it
754 is off by default. 889 is off by default.
755 890
756 Setting this variable to 1 will cause AnyEvent::DNS to announce 891 Setting this variable to 1 will cause AnyEvent::DNS to announce
757 EDNS0 in its DNS requests. 892 EDNS0 in its DNS requests.
893
894 "PERL_ANYEVENT_MAX_FORKS"
895 The maximum number of child processes that
896 "AnyEvent::Util::fork_call" will create in parallel.
897
898SUPPLYING YOUR OWN EVENT MODEL INTERFACE
899 This is an advanced topic that you do not normally need to use AnyEvent
900 in a module. This section is only of use to event loop authors who want
901 to provide AnyEvent compatibility.
902
903 If you need to support another event library which isn't directly
904 supported by AnyEvent, you can supply your own interface to it by
905 pushing, before the first watcher gets created, the package name of the
906 event module and the package name of the interface to use onto
907 @AnyEvent::REGISTRY. You can do that before and even without loading
908 AnyEvent, so it is reasonably cheap.
909
910 Example:
911
912 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
913
914 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
915 package/class when it finds the "urxvt" package/module is already
916 loaded.
917
918 When AnyEvent is loaded and asked to find a suitable event model, it
919 will first check for the presence of urxvt by trying to "use" the
920 "urxvt::anyevent" module.
921
922 The class should provide implementations for all watcher types. See
923 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
924 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
925 the sources.
926
927 If you don't provide "signal" and "child" watchers than AnyEvent will
928 provide suitable (hopefully) replacements.
929
930 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
931 terminal emulator uses the above line as-is. An interface isn't included
932 in AnyEvent because it doesn't make sense outside the embedded
933 interpreter inside *rxvt-unicode*, and it is updated and maintained as
934 part of the *rxvt-unicode* distribution.
935
936 *rxvt-unicode* also cheats a bit by not providing blocking access to
937 condition variables: code blocking while waiting for a condition will
938 "die". This still works with most modules/usages, and blocking calls
939 must not be done in an interactive application, so it makes sense.
758 940
759EXAMPLE PROGRAM 941EXAMPLE PROGRAM
760 The following program uses an I/O watcher to read data from STDIN, a 942 The following program uses an I/O watcher to read data from STDIN, a
761 timer to display a message once per second, and a condition variable to 943 timer to display a message once per second, and a condition variable to
762 quit the program when the user enters quit: 944 quit the program when the user enters quit:
… …
949 *destroy* is the time, in microseconds, that it takes to destroy a 1131 *destroy* is the time, in microseconds, that it takes to destroy a
950 single watcher. 1132 single watcher.
951 1133
952 Results 1134 Results
953 name watchers bytes create invoke destroy comment 1135 name watchers bytes create invoke destroy comment
954 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1136 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
955 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1137 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
956 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1138 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
957 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1139 Perl/Any 100000 452 4.14 0.75 0.99 pure perl implementation
958 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1140 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
959 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1141 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
960 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1142 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
961 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1143 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
962 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1144 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
963 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1145 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
964 1146
965 Discussion 1147 Discussion
966 The benchmark does *not* measure scalability of the event loop very 1148 The benchmark does *not* measure scalability of the event loop very
967 well. For example, a select-based event loop (such as the pure perl one) 1149 well. For example, a select-based event loop (such as the pure perl one)
968 can never compete with an event loop that uses epoll when the number of 1150 can never compete with an event loop that uses epoll when the number of
… …
1149 1331
1150 Summary 1332 Summary
1151 * C-based event loops perform very well with small number of watchers, 1333 * C-based event loops perform very well with small number of watchers,
1152 as the management overhead dominates. 1334 as the management overhead dominates.
1153 1335
1336SIGNALS
1337 AnyEvent currently installs handlers for these signals:
1338
1339 SIGCHLD
1340 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1341 emulation for event loops that do not support them natively. Also,
1342 some event loops install a similar handler.
1343
1344 SIGPIPE
1345 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1346 "undef" when AnyEvent gets loaded.
1347
1348 The rationale for this is that AnyEvent users usually do not really
1349 depend on SIGPIPE delivery (which is purely an optimisation for
1350 shell use, or badly-written programs), but "SIGPIPE" can cause
1351 spurious and rare program exits as a lot of people do not expect
1352 "SIGPIPE" when writing to some random socket.
1353
1354 The rationale for installing a no-op handler as opposed to ignoring
1355 it is that this way, the handler will be restored to defaults on
1356 exec.
1357
1358 Feel free to install your own handler, or reset it to defaults.
1359
1154FORK 1360FORK
1155 Most event libraries are not fork-safe. The ones who are usually are 1361 Most event libraries are not fork-safe. The ones who are usually are
1156 because they rely on inefficient but fork-safe "select" or "poll" calls. 1362 because they rely on inefficient but fork-safe "select" or "poll" calls.
1157 Only EV is fully fork-aware. 1363 Only EV is fully fork-aware.
1158 1364
… …
1168 model than specified in the variable. 1374 model than specified in the variable.
1169 1375
1170 You can make AnyEvent completely ignore this variable by deleting it 1376 You can make AnyEvent completely ignore this variable by deleting it
1171 before the first watcher gets created, e.g. with a "BEGIN" block: 1377 before the first watcher gets created, e.g. with a "BEGIN" block:
1172 1378
1173 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1379 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1174 1380
1175 use AnyEvent; 1381 use AnyEvent;
1176 1382
1177 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1383 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1178 be used to probe what backend is used and gain other information (which 1384 be used to probe what backend is used and gain other information (which
1179 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1385 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1386 and $ENV{PERL_ANYEGENT_STRICT}.
1387
1388BUGS
1389 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1390 hard to work around. If you suffer from memleaks, first upgrade to Perl
1391 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1392 annoying mamleaks, such as leaking on "map" and "grep" but it is usually
1393 not as pronounced).
1180 1394
1181SEE ALSO 1395SEE ALSO
1182 Utility functions: AnyEvent::Util. 1396 Utility functions: AnyEvent::Util.
1183 1397
1184 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1398 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
… …
1196 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1410 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1197 1411
1198 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1412 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
1199 1413
1200AUTHOR 1414AUTHOR
1201 Marc Lehmann <schmorp@schmorp.de> 1415 Marc Lehmann <schmorp@schmorp.de>
1202 http://home.schmorp.de/ 1416 http://home.schmorp.de/
1203 1417

Diff Legend

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