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

Comparing AnyEvent/README (file contents):
Revision 1.24 by root, Thu May 29 03:46:04 2008 UTC vs.
Revision 1.38 by root, Sun Apr 26 18:12:53 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 # file descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
12
13 # one-shot or repeating timers
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
16
17 print AnyEvent->now; # prints current event loop time
18 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
19
20 # POSIX signal
21 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
22
23 # child process exit
24 my $w = AnyEvent->child (pid => $pid, cb => sub {
25 my ($pid, $status) = @_;
11 ... 26 ...
12 }); 27 });
13 28
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 29 # called when event loop idle (if applicable)
15 ... 30 my $w = AnyEvent->idle (cb => sub { ... });
16 });
17 31
18 my $w = AnyEvent->condvar; # stores whether a condition was flagged 32 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's 33 $w->send; # wake up current and all future recv's
20 $w->recv; # enters "main loop" till $condvar gets ->send 34 $w->recv; # enters "main loop" till $condvar gets ->send
35 # use a condvar in callback mode:
36 $w->cb (sub { $_[0]->recv });
37
38INTRODUCTION/TUTORIAL
39 This manpage is mainly a reference manual. If you are interested in a
40 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
41 manpage.
21 42
22WHY YOU SHOULD USE THIS MODULE (OR NOT) 43WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 44 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent? 45 nowadays. So what is different about AnyEvent?
25 46
26 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of 47 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
27 policy* and AnyEvent is *small and efficient*. 48 policy* and AnyEvent is *small and efficient*.
28 49
29 First and foremost, *AnyEvent is not an event model* itself, it only 50 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 51 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, 52 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, 53 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. 54 only one event loop can be active at the same time in a process.
34 AnyEvent helps hiding the differences between those event loops. 55 AnyEvent cannot change this, but it can hide the differences between
56 those event loops.
35 57
36 The goal of AnyEvent is to offer module authors the ability to do event 58 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 59 programming (waiting for I/O or timer events) without subscribing to a
38 religion, a way of living, and most importantly: without forcing your 60 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 61 module users into the same thing by forcing them to use the same event
40 model you use. 62 model you use.
41 63
42 For modules like POE or IO::Async (which is a total misnomer as it is 64 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 65 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 66 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 67 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 68 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. 69 are *also* forced to use the same event loop you use.
48 70
49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 71 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
50 fine. AnyEvent + Tk works fine etc. etc. but none of these work together 72 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 73 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. 74 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 75 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 76 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 77 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). 78 to AnyEvent, too, so it is future-proof).
57 79
58 In addition to being free of having to use *the one and only true event 80 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 81 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 82 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 83 follow. AnyEvent, on the other hand, is lean and up to the point, by
… …
117 These watchers are normal Perl objects with normal Perl lifetime. After 139 These watchers are normal Perl objects with normal Perl lifetime. After
118 creating a watcher it will immediately "watch" for events and invoke the 140 creating a watcher it will immediately "watch" for events and invoke the
119 callback when the event occurs (of course, only when the event model is 141 callback when the event occurs (of course, only when the event model is
120 in control). 142 in control).
121 143
144 Note that callbacks must not permanently change global variables
145 potentially in use by the event loop (such as $_ or $[) and that
146 callbacks must not "die". The former is good programming practise in
147 Perl and the latter stems from the fact that exception handling differs
148 widely between event loops.
149
122 To disable the watcher you have to destroy it (e.g. by setting the 150 To disable the watcher you have to destroy it (e.g. by setting the
123 variable you store it in to "undef" or otherwise deleting all references 151 variable you store it in to "undef" or otherwise deleting all references
124 to it). 152 to it).
125 153
126 All watchers are created by calling a method on the "AnyEvent" class. 154 All watchers are created by calling a method on the "AnyEvent" class.
… …
128 Many watchers either are used with "recursion" (repeating timers for 156 Many watchers either are used with "recursion" (repeating timers for
129 example), or need to refer to their watcher object in other ways. 157 example), or need to refer to their watcher object in other ways.
130 158
131 An any way to achieve that is this pattern: 159 An any way to achieve that is this pattern:
132 160
133 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 161 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
134 # you can use $w here, for example to undef it 162 # you can use $w here, for example to undef it
135 undef $w; 163 undef $w;
136 }); 164 });
137 165
138 Note that "my $w; $w =" combination. This is necessary because in Perl, 166 Note that "my $w; $w =" combination. This is necessary because in Perl,
139 my variables are only visible after the statement in which they are 167 my variables are only visible after the statement in which they are
140 declared. 168 declared.
141 169
142 I/O WATCHERS 170 I/O WATCHERS
143 You can create an I/O watcher by calling the "AnyEvent->io" method with 171 You can create an I/O watcher by calling the "AnyEvent->io" method with
144 the following mandatory key-value pairs as arguments: 172 the following mandatory key-value pairs as arguments:
145 173
146 "fh" the Perl *file handle* (*not* file descriptor) to watch for events. 174 "fh" is the Perl *file handle* (*not* file descriptor) to watch for
175 events (AnyEvent might or might not keep a reference to this file
176 handle). Note that only file handles pointing to things for which
177 non-blocking operation makes sense are allowed. This includes sockets,
178 most character devices, pipes, fifos and so on, but not for example
179 files or block devices.
180
147 "poll" must be a string that is either "r" or "w", which creates a 181 "poll" must be a string that is either "r" or "w", which creates a
148 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 182 watcher waiting for "r"eadable or "w"ritable events, respectively.
183
149 is the callback to invoke each time the file handle becomes ready. 184 "cb" is the callback to invoke each time the file handle becomes ready.
150 185
151 Although the callback might get passed parameters, their value and 186 Although the callback might get passed parameters, their value and
152 presence is undefined and you cannot rely on them. Portable AnyEvent 187 presence is undefined and you cannot rely on them. Portable AnyEvent
153 callbacks cannot use arguments passed to I/O watcher callbacks. 188 callbacks cannot use arguments passed to I/O watcher callbacks.
154 189
… …
158 193
159 Some event loops issue spurious readyness notifications, so you should 194 Some event loops issue spurious readyness notifications, so you should
160 always use non-blocking calls when reading/writing from/to your file 195 always use non-blocking calls when reading/writing from/to your file
161 handles. 196 handles.
162 197
163 Example:
164
165 # wait for readability of STDIN, then read a line and disable the watcher 198 Example: wait for readability of STDIN, then read a line and disable the
199 watcher.
200
166 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 201 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
167 chomp (my $input = <STDIN>); 202 chomp (my $input = <STDIN>);
168 warn "read: $input\n"; 203 warn "read: $input\n";
169 undef $w; 204 undef $w;
170 }); 205 });
… …
179 214
180 Although the callback might get passed parameters, their value and 215 Although the callback might get passed parameters, their value and
181 presence is undefined and you cannot rely on them. Portable AnyEvent 216 presence is undefined and you cannot rely on them. Portable AnyEvent
182 callbacks cannot use arguments passed to time watcher callbacks. 217 callbacks cannot use arguments passed to time watcher callbacks.
183 218
184 The timer callback will be invoked at most once: if you want a repeating 219 The callback will normally be invoked once only. If you specify another
185 timer you have to create a new watcher (this is a limitation by both Tk 220 parameter, "interval", as a strictly positive number (> 0), then the
186 and Glib). 221 callback will be invoked regularly at that interval (in fractional
222 seconds) after the first invocation. If "interval" is specified with a
223 false value, then it is treated as if it were missing.
187 224
188 Example: 225 The callback will be rescheduled before invoking the callback, but no
226 attempt is done to avoid timer drift in most backends, so the interval
227 is only approximate.
189 228
190 # fire an event after 7.7 seconds 229 Example: fire an event after 7.7 seconds.
230
191 my $w = AnyEvent->timer (after => 7.7, cb => sub { 231 my $w = AnyEvent->timer (after => 7.7, cb => sub {
192 warn "timeout\n"; 232 warn "timeout\n";
193 }); 233 });
194 234
195 # to cancel the timer: 235 # to cancel the timer:
196 undef $w; 236 undef $w;
197 237
198 Example 2:
199
200 # fire an event after 0.5 seconds, then roughly every second 238 Example 2: fire an event after 0.5 seconds, then roughly every second.
201 my $w;
202 239
203 my $cb = sub {
204 # cancel the old timer while creating a new one
205 $w = AnyEvent->timer (after => 1, cb => $cb); 240 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
241 warn "timeout\n";
206 }; 242 };
207
208 # start the "loop" by creating the first watcher
209 $w = AnyEvent->timer (after => 0.5, cb => $cb);
210 243
211 TIMING ISSUES 244 TIMING ISSUES
212 There are two ways to handle timers: based on real time (relative, "fire 245 There are two ways to handle timers: based on real time (relative, "fire
213 in 10 seconds") and based on wallclock time (absolute, "fire at 12 246 in 10 seconds") and based on wallclock time (absolute, "fire at 12
214 o'clock"). 247 o'clock").
… …
288 In either case, if you care (and in most cases, you don't), then you 321 In either case, if you care (and in most cases, you don't), then you
289 can get whatever behaviour you want with any event loop, by taking 322 can get whatever behaviour you want with any event loop, by taking
290 the difference between "AnyEvent->time" and "AnyEvent->now" into 323 the difference between "AnyEvent->time" and "AnyEvent->now" into
291 account. 324 account.
292 325
326 AnyEvent->now_update
327 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
328 current time for each loop iteration (see the discussion of
329 AnyEvent->now, above).
330
331 When a callback runs for a long time (or when the process sleeps),
332 then this "current" time will differ substantially from the real
333 time, which might affect timers and time-outs.
334
335 When this is the case, you can call this method, which will update
336 the event loop's idea of "current time".
337
338 Note that updating the time *might* cause some events to be handled.
339
293 SIGNAL WATCHERS 340 SIGNAL WATCHERS
294 You can watch for signals using a signal watcher, "signal" is the signal 341 You can watch for signals using a signal watcher, "signal" is the signal
295 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked 342 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
296 whenever a signal occurs. 343 callback to be invoked whenever a signal occurs.
297 344
298 Although the callback might get passed parameters, their value and 345 Although the callback might get passed parameters, their value and
299 presence is undefined and you cannot rely on them. Portable AnyEvent 346 presence is undefined and you cannot rely on them. Portable AnyEvent
300 callbacks cannot use arguments passed to signal watcher callbacks. 347 callbacks cannot use arguments passed to signal watcher callbacks.
301 348
… …
316 363
317 CHILD PROCESS WATCHERS 364 CHILD PROCESS WATCHERS
318 You can also watch on a child process exit and catch its exit status. 365 You can also watch on a child process exit and catch its exit status.
319 366
320 The child process is specified by the "pid" argument (if set to 0, it 367 The child process is specified by the "pid" argument (if set to 0, it
321 watches for any child process exit). The watcher will trigger as often 368 watches for any child process exit). The watcher will triggered only
322 as status change for the child are received. This works by installing a 369 when the child process has finished and an exit status is available, not
323 signal handler for "SIGCHLD". The callback will be called with the pid 370 on any trace events (stopped/continued).
324 and exit status (as returned by waitpid), so unlike other watcher types, 371
325 you *can* rely on child watcher callback arguments. 372 The callback will be called with the pid and exit status (as returned by
373 waitpid), so unlike other watcher types, you *can* rely on child watcher
374 callback arguments.
375
376 This watcher type works by installing a signal handler for "SIGCHLD",
377 and since it cannot be shared, nothing else should use SIGCHLD or reap
378 random child processes (waiting for specific child processes, e.g.
379 inside "system", is just fine).
326 380
327 There is a slight catch to child watchers, however: you usually start 381 There is a slight catch to child watchers, however: you usually start
328 them *after* the child process was created, and this means the process 382 them *after* the child process was created, and this means the process
329 could have exited already (and no SIGCHLD will be sent anymore). 383 could have exited already (and no SIGCHLD will be sent anymore).
330 384
… …
337 an AnyEvent program, you *have* to create at least one watcher before 391 an AnyEvent program, you *have* to create at least one watcher before
338 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 392 you "fork" the child (alternatively, you can call "AnyEvent::detect").
339 393
340 Example: fork a process and wait for it 394 Example: fork a process and wait for it
341 395
342 my $done = AnyEvent->condvar; 396 my $done = AnyEvent->condvar;
343 397
344 my $pid = fork or exit 5; 398 my $pid = fork or exit 5;
345 399
346 my $w = AnyEvent->child ( 400 my $w = AnyEvent->child (
347 pid => $pid, 401 pid => $pid,
348 cb => sub { 402 cb => sub {
349 my ($pid, $status) = @_; 403 my ($pid, $status) = @_;
350 warn "pid $pid exited with status $status"; 404 warn "pid $pid exited with status $status";
351 $done->send; 405 $done->send;
352 }, 406 },
353 ); 407 );
354 408
355 # do something else, then wait for process exit 409 # do something else, then wait for process exit
356 $done->recv; 410 $done->recv;
411
412 IDLE WATCHERS
413 Sometimes there is a need to do something, but it is not so important to
414 do it instantly, but only when there is nothing better to do. This
415 "nothing better to do" is usually defined to be "no other events need
416 attention by the event loop".
417
418 Idle watchers ideally get invoked when the event loop has nothing better
419 to do, just before it would block the process to wait for new events.
420 Instead of blocking, the idle watcher is invoked.
421
422 Most event loops unfortunately do not really support idle watchers (only
423 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
424 will simply call the callback "from time to time".
425
426 Example: read lines from STDIN, but only process them when the program
427 is otherwise idle:
428
429 my @lines; # read data
430 my $idle_w;
431 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
432 push @lines, scalar <STDIN>;
433
434 # start an idle watcher, if not already done
435 $idle_w ||= AnyEvent->idle (cb => sub {
436 # handle only one line, when there are lines left
437 if (my $line = shift @lines) {
438 print "handled when idle: $line";
439 } else {
440 # otherwise disable the idle watcher again
441 undef $idle_w;
442 }
443 });
444 });
357 445
358 CONDITION VARIABLES 446 CONDITION VARIABLES
359 If you are familiar with some event loops you will know that all of them 447 If you are familiar with some event loops you will know that all of them
360 require you to run some blocking "loop", "run" or similar function that 448 require you to run some blocking "loop", "run" or similar function that
361 will actively watch for new events and call your callbacks. 449 will actively watch for new events and call your callbacks.
… …
366 The instrument to do that is called a "condition variable", so called 454 The instrument to do that is called a "condition variable", so called
367 because they represent a condition that must become true. 455 because they represent a condition that must become true.
368 456
369 Condition variables can be created by calling the "AnyEvent->condvar" 457 Condition variables can be created by calling the "AnyEvent->condvar"
370 method, usually without arguments. The only argument pair allowed is 458 method, usually without arguments. The only argument pair allowed is
459
371 "cb", which specifies a callback to be called when the condition 460 "cb", which specifies a callback to be called when the condition
372 variable becomes true. 461 variable becomes true, with the condition variable as the first argument
462 (but not the results).
373 463
374 After creation, the condition variable is "false" until it becomes 464 After creation, the condition variable is "false" until it becomes
375 "true" by calling the "send" method (or calling the condition variable 465 "true" by calling the "send" method (or calling the condition variable
376 as if it were a callback, read about the caveats in the description for 466 as if it were a callback, read about the caveats in the description for
377 the "->send" method). 467 the "->send" method).
… …
433 523
434 my $done = AnyEvent->condvar; 524 my $done = AnyEvent->condvar;
435 my $delay = AnyEvent->timer (after => 5, cb => $done); 525 my $delay = AnyEvent->timer (after => 5, cb => $done);
436 $done->recv; 526 $done->recv;
437 527
528 Example: Imagine an API that returns a condvar and doesn't support
529 callbacks. This is how you make a synchronous call, for example from the
530 main program:
531
532 use AnyEvent::CouchDB;
533
534 ...
535
536 my @info = $couchdb->info->recv;
537
538 And this is how you would just ste a callback to be called whenever the
539 results are available:
540
541 $couchdb->info->cb (sub {
542 my @info = $_[0]->recv;
543 });
544
438 METHODS FOR PRODUCERS 545 METHODS FOR PRODUCERS
439 These methods should only be used by the producing side, i.e. the 546 These methods should only be used by the producing side, i.e. the
440 code/module that eventually sends the signal. Note that it is also the 547 code/module that eventually sends the signal. Note that it is also the
441 producer side which creates the condvar in most cases, but it isn't 548 producer side which creates the condvar in most cases, but it isn't
442 uncommon for the consumer to create it as well. 549 uncommon for the consumer to create it as well.
… …
562 669
563 $bool = $cv->ready 670 $bool = $cv->ready
564 Returns true when the condition is "true", i.e. whether "send" or 671 Returns true when the condition is "true", i.e. whether "send" or
565 "croak" have been called. 672 "croak" have been called.
566 673
567 $cb = $cv->cb ([new callback]) 674 $cb = $cv->cb ($cb->($cv))
568 This is a mutator function that returns the callback set and 675 This is a mutator function that returns the callback set and
569 optionally replaces it before doing so. 676 optionally replaces it before doing so.
570 677
571 The callback will be called when the condition becomes "true", i.e. 678 The callback will be called when the condition becomes "true", i.e.
572 when "send" or "croak" are called. Calling "recv" inside the 679 when "send" or "croak" are called, with the only argument being the
680 condition variable itself. Calling "recv" inside the callback or at
573 callback or at any later time is guaranteed not to block. 681 any later time is guaranteed not to block.
574 682
575GLOBAL VARIABLES AND FUNCTIONS 683GLOBAL VARIABLES AND FUNCTIONS
576 $AnyEvent::MODEL 684 $AnyEvent::MODEL
577 Contains "undef" until the first watcher is being created. Then it 685 Contains "undef" until the first watcher is being created. Then it
578 contains the event model that is being used, which is the name of 686 contains the event model that is being used, which is the name of
… …
692 AnyEvent::Util 800 AnyEvent::Util
693 Contains various utility functions that replace often-used but 801 Contains various utility functions that replace often-used but
694 blocking functions such as "inet_aton" by event-/callback-based 802 blocking functions such as "inet_aton" by event-/callback-based
695 versions. 803 versions.
696 804
697 AnyEvent::Handle
698 Provide read and write buffers and manages watchers for reads and
699 writes.
700
701 AnyEvent::Socket 805 AnyEvent::Socket
702 Provides various utility functions for (internet protocol) sockets, 806 Provides various utility functions for (internet protocol) sockets,
703 addresses and name resolution. Also functions to create non-blocking 807 addresses and name resolution. Also functions to create non-blocking
704 tcp connections or tcp servers, with IPv6 and SRV record support and 808 tcp connections or tcp servers, with IPv6 and SRV record support and
705 more. 809 more.
706 810
811 AnyEvent::Handle
812 Provide read and write buffers, manages watchers for reads and
813 writes, supports raw and formatted I/O, I/O queued and fully
814 transparent and non-blocking SSL/TLS.
815
707 AnyEvent::DNS 816 AnyEvent::DNS
708 Provides rich asynchronous DNS resolver capabilities. 817 Provides rich asynchronous DNS resolver capabilities.
709 818
819 AnyEvent::HTTP
820 A simple-to-use HTTP library that is capable of making a lot of
821 concurrent HTTP requests.
822
710 AnyEvent::HTTPD 823 AnyEvent::HTTPD
711 Provides a simple web application server framework. 824 Provides a simple web application server framework.
712 825
713 AnyEvent::FastPing 826 AnyEvent::FastPing
714 The fastest ping in the west. 827 The fastest ping in the west.
715 828
829 AnyEvent::DBI
830 Executes DBI requests asynchronously in a proxy process.
831
832 AnyEvent::AIO
833 Truly asynchronous I/O, should be in the toolbox of every event
834 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
835 together.
836
837 AnyEvent::BDB
838 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
839 fuses BDB and AnyEvent together.
840
841 AnyEvent::GPSD
842 A non-blocking interface to gpsd, a daemon delivering GPS
843 information.
844
845 AnyEvent::IGS
846 A non-blocking interface to the Internet Go Server protocol (used by
847 App::IGS).
848
849 AnyEvent::IRC
850 AnyEvent based IRC client module family (replacing the older
716 Net::IRC3 851 Net::IRC3).
717 AnyEvent based IRC client module family.
718 852
719 Net::XMPP2 853 Net::XMPP2
720 AnyEvent based XMPP (Jabber protocol) module family. 854 AnyEvent based XMPP (Jabber protocol) module family.
721 855
722 Net::FCP 856 Net::FCP
… …
727 High level API for event-based execution flow control. 861 High level API for event-based execution flow control.
728 862
729 Coro 863 Coro
730 Has special support for AnyEvent via Coro::AnyEvent. 864 Has special support for AnyEvent via Coro::AnyEvent.
731 865
732 AnyEvent::AIO, IO::AIO
733 Truly asynchronous I/O, should be in the toolbox of every event
734 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
735 together.
736
737 AnyEvent::BDB, BDB
738 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
739 fuses IO::AIO and AnyEvent together.
740
741 IO::Lambda 866 IO::Lambda
742 The lambda approach to I/O - don't ask, look there. Can use 867 The lambda approach to I/O - don't ask, look there. Can use
743 AnyEvent. 868 AnyEvent.
744 869
745SUPPLYING YOUR OWN EVENT MODEL INTERFACE 870ERROR AND EXCEPTION HANDLING
746 This is an advanced topic that you do not normally need to use AnyEvent 871 In general, AnyEvent does not do any error handling - it relies on the
747 in a module. This section is only of use to event loop authors who want 872 caller to do that if required. The AnyEvent::Strict module (see also the
748 to provide AnyEvent compatibility. 873 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
874 checking of all AnyEvent methods, however, which is highly useful during
875 development.
749 876
750 If you need to support another event library which isn't directly 877 As for exception handling (i.e. runtime errors and exceptions thrown
751 supported by AnyEvent, you can supply your own interface to it by 878 while executing a callback), this is not only highly event-loop
752 pushing, before the first watcher gets created, the package name of the 879 specific, but also not in any way wrapped by this module, as this is the
753 event module and the package name of the interface to use onto 880 job of the main program.
754 @AnyEvent::REGISTRY. You can do that before and even without loading
755 AnyEvent, so it is reasonably cheap.
756 881
757 Example: 882 The pure perl event loop simply re-throws the exception (usually within
758 883 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
759 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 884 Glib uses "install_exception_handler" and so on.
760
761 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
762 package/class when it finds the "urxvt" package/module is already
763 loaded.
764
765 When AnyEvent is loaded and asked to find a suitable event model, it
766 will first check for the presence of urxvt by trying to "use" the
767 "urxvt::anyevent" module.
768
769 The class should provide implementations for all watcher types. See
770 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
771 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
772 the sources.
773
774 If you don't provide "signal" and "child" watchers than AnyEvent will
775 provide suitable (hopefully) replacements.
776
777 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
778 terminal emulator uses the above line as-is. An interface isn't included
779 in AnyEvent because it doesn't make sense outside the embedded
780 interpreter inside *rxvt-unicode*, and it is updated and maintained as
781 part of the *rxvt-unicode* distribution.
782
783 *rxvt-unicode* also cheats a bit by not providing blocking access to
784 condition variables: code blocking while waiting for a condition will
785 "die". This still works with most modules/usages, and blocking calls
786 must not be done in an interactive application, so it makes sense.
787 885
788ENVIRONMENT VARIABLES 886ENVIRONMENT VARIABLES
789 The following environment variables are used by this module: 887 The following environment variables are used by this module or its
888 submodules:
790 889
791 "PERL_ANYEVENT_VERBOSE" 890 "PERL_ANYEVENT_VERBOSE"
792 By default, AnyEvent will be completely silent except in fatal 891 By default, AnyEvent will be completely silent except in fatal
793 conditions. You can set this environment variable to make AnyEvent 892 conditions. You can set this environment variable to make AnyEvent
794 more talkative. 893 more talkative.
… …
797 conditions, such as not being able to load the event model specified 896 conditions, such as not being able to load the event model specified
798 by "PERL_ANYEVENT_MODEL". 897 by "PERL_ANYEVENT_MODEL".
799 898
800 When set to 2 or higher, cause AnyEvent to report to STDERR which 899 When set to 2 or higher, cause AnyEvent to report to STDERR which
801 event model it chooses. 900 event model it chooses.
901
902 "PERL_ANYEVENT_STRICT"
903 AnyEvent does not do much argument checking by default, as thorough
904 argument checking is very costly. Setting this variable to a true
905 value will cause AnyEvent to load "AnyEvent::Strict" and then to
906 thoroughly check the arguments passed to most method calls. If it
907 finds any problems it will croak.
908
909 In other words, enables "strict" mode.
910
911 Unlike "use strict", it is definitely recommended ot keep it off in
912 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
913 while developing programs can be very useful, however.
802 914
803 "PERL_ANYEVENT_MODEL" 915 "PERL_ANYEVENT_MODEL"
804 This can be used to specify the event model to be used by AnyEvent, 916 This can be used to specify the event model to be used by AnyEvent,
805 before auto detection and -probing kicks in. It must be a string 917 before auto detection and -probing kicks in. It must be a string
806 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 918 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
811 This functionality might change in future versions. 923 This functionality might change in future versions.
812 924
813 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 925 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
814 could start your program like this: 926 could start your program like this:
815 927
816 PERL_ANYEVENT_MODEL=Perl perl ... 928 PERL_ANYEVENT_MODEL=Perl perl ...
817 929
818 "PERL_ANYEVENT_PROTOCOLS" 930 "PERL_ANYEVENT_PROTOCOLS"
819 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 931 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
820 preferences for IPv4 or IPv6. The default is unspecified (and might 932 preferences for IPv4 or IPv6. The default is unspecified (and might
821 change, or be the result of auto probing). 933 change, or be the result of auto probing).
… …
825 mentioned will be used, and preference will be given to protocols 937 mentioned will be used, and preference will be given to protocols
826 mentioned earlier in the list. 938 mentioned earlier in the list.
827 939
828 This variable can effectively be used for denial-of-service attacks 940 This variable can effectively be used for denial-of-service attacks
829 against local programs (e.g. when setuid), although the impact is 941 against local programs (e.g. when setuid), although the impact is
830 likely small, as the program has to handle connection errors 942 likely small, as the program has to handle conenction and other
831 already- 943 failures anyways.
832 944
833 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 945 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
834 IPv6, but support both and try to use both. 946 IPv6, but support both and try to use both.
835 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 947 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
836 resolve or contact IPv6 addresses. 948 resolve or contact IPv6 addresses.
… …
847 EDNS0 in its DNS requests. 959 EDNS0 in its DNS requests.
848 960
849 "PERL_ANYEVENT_MAX_FORKS" 961 "PERL_ANYEVENT_MAX_FORKS"
850 The maximum number of child processes that 962 The maximum number of child processes that
851 "AnyEvent::Util::fork_call" will create in parallel. 963 "AnyEvent::Util::fork_call" will create in parallel.
964
965SUPPLYING YOUR OWN EVENT MODEL INTERFACE
966 This is an advanced topic that you do not normally need to use AnyEvent
967 in a module. This section is only of use to event loop authors who want
968 to provide AnyEvent compatibility.
969
970 If you need to support another event library which isn't directly
971 supported by AnyEvent, you can supply your own interface to it by
972 pushing, before the first watcher gets created, the package name of the
973 event module and the package name of the interface to use onto
974 @AnyEvent::REGISTRY. You can do that before and even without loading
975 AnyEvent, so it is reasonably cheap.
976
977 Example:
978
979 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
980
981 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
982 package/class when it finds the "urxvt" package/module is already
983 loaded.
984
985 When AnyEvent is loaded and asked to find a suitable event model, it
986 will first check for the presence of urxvt by trying to "use" the
987 "urxvt::anyevent" module.
988
989 The class should provide implementations for all watcher types. See
990 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
991 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
992 the sources.
993
994 If you don't provide "signal" and "child" watchers than AnyEvent will
995 provide suitable (hopefully) replacements.
996
997 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
998 terminal emulator uses the above line as-is. An interface isn't included
999 in AnyEvent because it doesn't make sense outside the embedded
1000 interpreter inside *rxvt-unicode*, and it is updated and maintained as
1001 part of the *rxvt-unicode* distribution.
1002
1003 *rxvt-unicode* also cheats a bit by not providing blocking access to
1004 condition variables: code blocking while waiting for a condition will
1005 "die". This still works with most modules/usages, and blocking calls
1006 must not be done in an interactive application, so it makes sense.
852 1007
853EXAMPLE PROGRAM 1008EXAMPLE PROGRAM
854 The following program uses an I/O watcher to read data from STDIN, a 1009 The following program uses an I/O watcher to read data from STDIN, a
855 timer to display a message once per second, and a condition variable to 1010 timer to display a message once per second, and a condition variable to
856 quit the program when the user enters quit: 1011 quit the program when the user enters quit:
… …
1043 *destroy* is the time, in microseconds, that it takes to destroy a 1198 *destroy* is the time, in microseconds, that it takes to destroy a
1044 single watcher. 1199 single watcher.
1045 1200
1046 Results 1201 Results
1047 name watchers bytes create invoke destroy comment 1202 name watchers bytes create invoke destroy comment
1048 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1203 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1049 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1204 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1050 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1205 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1051 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1206 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1052 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1207 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1053 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1208 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1054 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1209 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1055 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1210 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1056 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1211 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1057 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1212 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1058 1213
1059 Discussion 1214 Discussion
1060 The benchmark does *not* measure scalability of the event loop very 1215 The benchmark does *not* measure scalability of the event loop very
1061 well. For example, a select-based event loop (such as the pure perl one) 1216 well. For example, a select-based event loop (such as the pure perl one)
1062 can never compete with an event loop that uses epoll when the number of 1217 can never compete with an event loop that uses epoll when the number of
… …
1243 1398
1244 Summary 1399 Summary
1245 * C-based event loops perform very well with small number of watchers, 1400 * C-based event loops perform very well with small number of watchers,
1246 as the management overhead dominates. 1401 as the management overhead dominates.
1247 1402
1403SIGNALS
1404 AnyEvent currently installs handlers for these signals:
1405
1406 SIGCHLD
1407 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1408 emulation for event loops that do not support them natively. Also,
1409 some event loops install a similar handler.
1410
1411 SIGPIPE
1412 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1413 "undef" when AnyEvent gets loaded.
1414
1415 The rationale for this is that AnyEvent users usually do not really
1416 depend on SIGPIPE delivery (which is purely an optimisation for
1417 shell use, or badly-written programs), but "SIGPIPE" can cause
1418 spurious and rare program exits as a lot of people do not expect
1419 "SIGPIPE" when writing to some random socket.
1420
1421 The rationale for installing a no-op handler as opposed to ignoring
1422 it is that this way, the handler will be restored to defaults on
1423 exec.
1424
1425 Feel free to install your own handler, or reset it to defaults.
1426
1248FORK 1427FORK
1249 Most event libraries are not fork-safe. The ones who are usually are 1428 Most event libraries are not fork-safe. The ones who are usually are
1250 because they rely on inefficient but fork-safe "select" or "poll" calls. 1429 because they rely on inefficient but fork-safe "select" or "poll" calls.
1251 Only EV is fully fork-aware. 1430 Only EV is fully fork-aware.
1252 1431
… …
1262 model than specified in the variable. 1441 model than specified in the variable.
1263 1442
1264 You can make AnyEvent completely ignore this variable by deleting it 1443 You can make AnyEvent completely ignore this variable by deleting it
1265 before the first watcher gets created, e.g. with a "BEGIN" block: 1444 before the first watcher gets created, e.g. with a "BEGIN" block:
1266 1445
1267 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1446 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1268 1447
1269 use AnyEvent; 1448 use AnyEvent;
1270 1449
1271 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1450 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1272 be used to probe what backend is used and gain other information (which 1451 be used to probe what backend is used and gain other information (which
1273 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1452 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1453 and $ENV{PERL_ANYEGENT_STRICT}.
1454
1455BUGS
1456 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1457 hard to work around. If you suffer from memleaks, first upgrade to Perl
1458 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1459 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1460 not as pronounced).
1274 1461
1275SEE ALSO 1462SEE ALSO
1276 Utility functions: AnyEvent::Util. 1463 Utility functions: AnyEvent::Util.
1277 1464
1278 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1465 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
… …
1290 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1477 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1291 1478
1292 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1479 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
1293 1480
1294AUTHOR 1481AUTHOR
1295 Marc Lehmann <schmorp@schmorp.de> 1482 Marc Lehmann <schmorp@schmorp.de>
1296 http://home.schmorp.de/ 1483 http://home.schmorp.de/
1297 1484

Diff Legend

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