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

Comparing AnyEvent/README (file contents):
Revision 1.27 by root, Sun Jun 22 12:17:47 2008 UTC vs.
Revision 1.36 by root, Fri Mar 27 10:49:50 2009 UTC

… …
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 });
21 30
22INTRODUCTION/TUTORIAL 31INTRODUCTION/TUTORIAL
23 This manpage is mainly a reference manual. If you are interested in a 32 This manpage is mainly a reference manual. If you are interested in a
24 tutorial or some gentle introduction, have a look at the AnyEvent::Intro 33 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
25 manpage. 34 manpage.
… …
30 39
31 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of 40 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
32 policy* and AnyEvent is *small and efficient*. 41 policy* and AnyEvent is *small and efficient*.
33 42
34 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
35 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
36 pragmatic way. For event models and certain classes of immortals alike, 45 pragmatic way. For event models and certain classes of immortals alike,
37 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,
38 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.
39 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.
40 50
41 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
42 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
43 religion, a way of living, and most importantly: without forcing your 53 religion, a way of living, and most importantly: without forcing your
44 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
45 model you use. 55 model you use.
46 56
47 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
48 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
49 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
50 cannot use anything else, as it is simply incompatible to everything 60 cannot use anything else, as they are simply incompatible to everything
51 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
52 are *also* forced to use the same event loop you use. 62 are *also* forced to use the same event loop you use.
53 63
54 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 64 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
55 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
56 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
57 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.
58 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
59 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
60 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
61 event loops to AnyEvent, too, so it is future-proof). 71 to AnyEvent, too, so it is future-proof).
62 72
63 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
64 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
65 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
66 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
… …
122 These watchers are normal Perl objects with normal Perl lifetime. After 132 These watchers are normal Perl objects with normal Perl lifetime. After
123 creating a watcher it will immediately "watch" for events and invoke the 133 creating a watcher it will immediately "watch" for events and invoke the
124 callback when the event occurs (of course, only when the event model is 134 callback when the event occurs (of course, only when the event model is
125 in control). 135 in control).
126 136
137 Note that callbacks must not permanently change global variables
138 potentially in use by the event loop (such as $_ or $[) and that
139 callbacks must not "die". The former is good programming practise in
140 Perl and the latter stems from the fact that exception handling differs
141 widely between event loops.
142
127 To disable the watcher you have to destroy it (e.g. by setting the 143 To disable the watcher you have to destroy it (e.g. by setting the
128 variable you store it in to "undef" or otherwise deleting all references 144 variable you store it in to "undef" or otherwise deleting all references
129 to it). 145 to it).
130 146
131 All watchers are created by calling a method on the "AnyEvent" class. 147 All watchers are created by calling a method on the "AnyEvent" class.
… …
146 162
147 I/O WATCHERS 163 I/O WATCHERS
148 You can create an I/O watcher by calling the "AnyEvent->io" method with 164 You can create an I/O watcher by calling the "AnyEvent->io" method with
149 the following mandatory key-value pairs as arguments: 165 the following mandatory key-value pairs as arguments:
150 166
151 "fh" the Perl *file handle* (*not* file descriptor) to watch for events. 167 "fh" is the Perl *file handle* (*not* file descriptor) to watch for
168 events (AnyEvent might or might not keep a reference to this file
169 handle). Note that only file handles pointing to things for which
170 non-blocking operation makes sense are allowed. This includes sockets,
171 most character devices, pipes, fifos and so on, but not for example
172 files or block devices.
173
152 "poll" must be a string that is either "r" or "w", which creates a 174 "poll" must be a string that is either "r" or "w", which creates a
153 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 175 watcher waiting for "r"eadable or "w"ritable events, respectively.
176
154 is the callback to invoke each time the file handle becomes ready. 177 "cb" is the callback to invoke each time the file handle becomes ready.
155 178
156 Although the callback might get passed parameters, their value and 179 Although the callback might get passed parameters, their value and
157 presence is undefined and you cannot rely on them. Portable AnyEvent 180 presence is undefined and you cannot rely on them. Portable AnyEvent
158 callbacks cannot use arguments passed to I/O watcher callbacks. 181 callbacks cannot use arguments passed to I/O watcher callbacks.
159 182
… …
163 186
164 Some event loops issue spurious readyness notifications, so you should 187 Some event loops issue spurious readyness notifications, so you should
165 always use non-blocking calls when reading/writing from/to your file 188 always use non-blocking calls when reading/writing from/to your file
166 handles. 189 handles.
167 190
168 Example:
169
170 # wait for readability of STDIN, then read a line and disable the watcher 191 Example: wait for readability of STDIN, then read a line and disable the
192 watcher.
193
171 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 194 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
172 chomp (my $input = <STDIN>); 195 chomp (my $input = <STDIN>);
173 warn "read: $input\n"; 196 warn "read: $input\n";
174 undef $w; 197 undef $w;
175 }); 198 });
… …
184 207
185 Although the callback might get passed parameters, their value and 208 Although the callback might get passed parameters, their value and
186 presence is undefined and you cannot rely on them. Portable AnyEvent 209 presence is undefined and you cannot rely on them. Portable AnyEvent
187 callbacks cannot use arguments passed to time watcher callbacks. 210 callbacks cannot use arguments passed to time watcher callbacks.
188 211
189 The timer callback will be invoked at most once: if you want a repeating 212 The callback will normally be invoked once only. If you specify another
190 timer you have to create a new watcher (this is a limitation by both Tk 213 parameter, "interval", as a strictly positive number (> 0), then the
191 and Glib). 214 callback will be invoked regularly at that interval (in fractional
215 seconds) after the first invocation. If "interval" is specified with a
216 false value, then it is treated as if it were missing.
192 217
193 Example: 218 The callback will be rescheduled before invoking the callback, but no
219 attempt is done to avoid timer drift in most backends, so the interval
220 is only approximate.
194 221
195 # fire an event after 7.7 seconds 222 Example: fire an event after 7.7 seconds.
223
196 my $w = AnyEvent->timer (after => 7.7, cb => sub { 224 my $w = AnyEvent->timer (after => 7.7, cb => sub {
197 warn "timeout\n"; 225 warn "timeout\n";
198 }); 226 });
199 227
200 # to cancel the timer: 228 # to cancel the timer:
201 undef $w; 229 undef $w;
202 230
203 Example 2:
204
205 # fire an event after 0.5 seconds, then roughly every second 231 Example 2: fire an event after 0.5 seconds, then roughly every second.
206 my $w;
207 232
208 my $cb = sub {
209 # cancel the old timer while creating a new one
210 $w = AnyEvent->timer (after => 1, cb => $cb); 233 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
234 warn "timeout\n";
211 }; 235 };
212
213 # start the "loop" by creating the first watcher
214 $w = AnyEvent->timer (after => 0.5, cb => $cb);
215 236
216 TIMING ISSUES 237 TIMING ISSUES
217 There are two ways to handle timers: based on real time (relative, "fire 238 There are two ways to handle timers: based on real time (relative, "fire
218 in 10 seconds") and based on wallclock time (absolute, "fire at 12 239 in 10 seconds") and based on wallclock time (absolute, "fire at 12
219 o'clock"). 240 o'clock").
… …
295 the difference between "AnyEvent->time" and "AnyEvent->now" into 316 the difference between "AnyEvent->time" and "AnyEvent->now" into
296 account. 317 account.
297 318
298 SIGNAL WATCHERS 319 SIGNAL WATCHERS
299 You can watch for signals using a signal watcher, "signal" is the signal 320 You can watch for signals using a signal watcher, "signal" is the signal
300 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked 321 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
301 whenever a signal occurs. 322 callback to be invoked whenever a signal occurs.
302 323
303 Although the callback might get passed parameters, their value and 324 Although the callback might get passed parameters, their value and
304 presence is undefined and you cannot rely on them. Portable AnyEvent 325 presence is undefined and you cannot rely on them. Portable AnyEvent
305 callbacks cannot use arguments passed to signal watcher callbacks. 326 callbacks cannot use arguments passed to signal watcher callbacks.
306 327
… …
321 342
322 CHILD PROCESS WATCHERS 343 CHILD PROCESS WATCHERS
323 You can also watch on a child process exit and catch its exit status. 344 You can also watch on a child process exit and catch its exit status.
324 345
325 The child process is specified by the "pid" argument (if set to 0, it 346 The child process is specified by the "pid" argument (if set to 0, it
326 watches for any child process exit). The watcher will trigger as often 347 watches for any child process exit). The watcher will triggered only
327 as status change for the child are received. This works by installing a 348 when the child process has finished and an exit status is available, not
328 signal handler for "SIGCHLD". The callback will be called with the pid 349 on any trace events (stopped/continued).
329 and exit status (as returned by waitpid), so unlike other watcher types, 350
330 you *can* rely on child watcher callback arguments. 351 The callback will be called with the pid and exit status (as returned by
352 waitpid), so unlike other watcher types, you *can* rely on child watcher
353 callback arguments.
354
355 This watcher type works by installing a signal handler for "SIGCHLD",
356 and since it cannot be shared, nothing else should use SIGCHLD or reap
357 random child processes (waiting for specific child processes, e.g.
358 inside "system", is just fine).
331 359
332 There is a slight catch to child watchers, however: you usually start 360 There is a slight catch to child watchers, however: you usually start
333 them *after* the child process was created, and this means the process 361 them *after* the child process was created, and this means the process
334 could have exited already (and no SIGCHLD will be sent anymore). 362 could have exited already (and no SIGCHLD will be sent anymore).
335 363
… …
371 The instrument to do that is called a "condition variable", so called 399 The instrument to do that is called a "condition variable", so called
372 because they represent a condition that must become true. 400 because they represent a condition that must become true.
373 401
374 Condition variables can be created by calling the "AnyEvent->condvar" 402 Condition variables can be created by calling the "AnyEvent->condvar"
375 method, usually without arguments. The only argument pair allowed is 403 method, usually without arguments. The only argument pair allowed is
404
376 "cb", which specifies a callback to be called when the condition 405 "cb", which specifies a callback to be called when the condition
377 variable becomes true. 406 variable becomes true, with the condition variable as the first argument
407 (but not the results).
378 408
379 After creation, the condition variable is "false" until it becomes 409 After creation, the condition variable is "false" until it becomes
380 "true" by calling the "send" method (or calling the condition variable 410 "true" by calling the "send" method (or calling the condition variable
381 as if it were a callback, read about the caveats in the description for 411 as if it were a callback, read about the caveats in the description for
382 the "->send" method). 412 the "->send" method).
… …
438 468
439 my $done = AnyEvent->condvar; 469 my $done = AnyEvent->condvar;
440 my $delay = AnyEvent->timer (after => 5, cb => $done); 470 my $delay = AnyEvent->timer (after => 5, cb => $done);
441 $done->recv; 471 $done->recv;
442 472
473 Example: Imagine an API that returns a condvar and doesn't support
474 callbacks. This is how you make a synchronous call, for example from the
475 main program:
476
477 use AnyEvent::CouchDB;
478
479 ...
480
481 my @info = $couchdb->info->recv;
482
483 And this is how you would just ste a callback to be called whenever the
484 results are available:
485
486 $couchdb->info->cb (sub {
487 my @info = $_[0]->recv;
488 });
489
443 METHODS FOR PRODUCERS 490 METHODS FOR PRODUCERS
444 These methods should only be used by the producing side, i.e. the 491 These methods should only be used by the producing side, i.e. the
445 code/module that eventually sends the signal. Note that it is also the 492 code/module that eventually sends the signal. Note that it is also the
446 producer side which creates the condvar in most cases, but it isn't 493 producer side which creates the condvar in most cases, but it isn't
447 uncommon for the consumer to create it as well. 494 uncommon for the consumer to create it as well.
… …
567 614
568 $bool = $cv->ready 615 $bool = $cv->ready
569 Returns true when the condition is "true", i.e. whether "send" or 616 Returns true when the condition is "true", i.e. whether "send" or
570 "croak" have been called. 617 "croak" have been called.
571 618
572 $cb = $cv->cb ([new callback]) 619 $cb = $cv->cb ($cb->($cv))
573 This is a mutator function that returns the callback set and 620 This is a mutator function that returns the callback set and
574 optionally replaces it before doing so. 621 optionally replaces it before doing so.
575 622
576 The callback will be called when the condition becomes "true", i.e. 623 The callback will be called when the condition becomes "true", i.e.
577 when "send" or "croak" are called, with the only argument being the 624 when "send" or "croak" are called, with the only argument being the
… …
698 AnyEvent::Util 745 AnyEvent::Util
699 Contains various utility functions that replace often-used but 746 Contains various utility functions that replace often-used but
700 blocking functions such as "inet_aton" by event-/callback-based 747 blocking functions such as "inet_aton" by event-/callback-based
701 versions. 748 versions.
702 749
703 AnyEvent::Handle
704 Provide read and write buffers and manages watchers for reads and
705 writes.
706
707 AnyEvent::Socket 750 AnyEvent::Socket
708 Provides various utility functions for (internet protocol) sockets, 751 Provides various utility functions for (internet protocol) sockets,
709 addresses and name resolution. Also functions to create non-blocking 752 addresses and name resolution. Also functions to create non-blocking
710 tcp connections or tcp servers, with IPv6 and SRV record support and 753 tcp connections or tcp servers, with IPv6 and SRV record support and
711 more. 754 more.
712 755
756 AnyEvent::Handle
757 Provide read and write buffers, manages watchers for reads and
758 writes, supports raw and formatted I/O, I/O queued and fully
759 transparent and non-blocking SSL/TLS.
760
713 AnyEvent::DNS 761 AnyEvent::DNS
714 Provides rich asynchronous DNS resolver capabilities. 762 Provides rich asynchronous DNS resolver capabilities.
715 763
716 AnyEvent::HTTP 764 AnyEvent::HTTP
717 A simple-to-use HTTP library that is capable of making a lot of 765 A simple-to-use HTTP library that is capable of making a lot of
… …
724 The fastest ping in the west. 772 The fastest ping in the west.
725 773
726 AnyEvent::DBI 774 AnyEvent::DBI
727 Executes DBI requests asynchronously in a proxy process. 775 Executes DBI requests asynchronously in a proxy process.
728 776
777 AnyEvent::AIO
778 Truly asynchronous I/O, should be in the toolbox of every event
779 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
780 together.
781
782 AnyEvent::BDB
783 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
784 fuses BDB and AnyEvent together.
785
786 AnyEvent::GPSD
787 A non-blocking interface to gpsd, a daemon delivering GPS
788 information.
789
790 AnyEvent::IGS
791 A non-blocking interface to the Internet Go Server protocol (used by
792 App::IGS).
793
794 AnyEvent::IRC
795 AnyEvent based IRC client module family (replacing the older
729 Net::IRC3 796 Net::IRC3).
730 AnyEvent based IRC client module family.
731 797
732 Net::XMPP2 798 Net::XMPP2
733 AnyEvent based XMPP (Jabber protocol) module family. 799 AnyEvent based XMPP (Jabber protocol) module family.
734 800
735 Net::FCP 801 Net::FCP
… …
740 High level API for event-based execution flow control. 806 High level API for event-based execution flow control.
741 807
742 Coro 808 Coro
743 Has special support for AnyEvent via Coro::AnyEvent. 809 Has special support for AnyEvent via Coro::AnyEvent.
744 810
745 AnyEvent::AIO, IO::AIO
746 Truly asynchronous I/O, should be in the toolbox of every event
747 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
748 together.
749
750 AnyEvent::BDB, BDB
751 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
752 fuses IO::AIO and AnyEvent together.
753
754 IO::Lambda 811 IO::Lambda
755 The lambda approach to I/O - don't ask, look there. Can use 812 The lambda approach to I/O - don't ask, look there. Can use
756 AnyEvent. 813 AnyEvent.
757 814
758SUPPLYING YOUR OWN EVENT MODEL INTERFACE 815ERROR AND EXCEPTION HANDLING
759 This is an advanced topic that you do not normally need to use AnyEvent 816 In general, AnyEvent does not do any error handling - it relies on the
760 in a module. This section is only of use to event loop authors who want 817 caller to do that if required. The AnyEvent::Strict module (see also the
761 to provide AnyEvent compatibility. 818 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
819 checking of all AnyEvent methods, however, which is highly useful during
820 development.
762 821
763 If you need to support another event library which isn't directly 822 As for exception handling (i.e. runtime errors and exceptions thrown
764 supported by AnyEvent, you can supply your own interface to it by 823 while executing a callback), this is not only highly event-loop
765 pushing, before the first watcher gets created, the package name of the 824 specific, but also not in any way wrapped by this module, as this is the
766 event module and the package name of the interface to use onto 825 job of the main program.
767 @AnyEvent::REGISTRY. You can do that before and even without loading
768 AnyEvent, so it is reasonably cheap.
769 826
770 Example: 827 The pure perl event loop simply re-throws the exception (usually within
771 828 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
772 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 829 Glib uses "install_exception_handler" and so on.
773
774 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
775 package/class when it finds the "urxvt" package/module is already
776 loaded.
777
778 When AnyEvent is loaded and asked to find a suitable event model, it
779 will first check for the presence of urxvt by trying to "use" the
780 "urxvt::anyevent" module.
781
782 The class should provide implementations for all watcher types. See
783 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
784 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
785 the sources.
786
787 If you don't provide "signal" and "child" watchers than AnyEvent will
788 provide suitable (hopefully) replacements.
789
790 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
791 terminal emulator uses the above line as-is. An interface isn't included
792 in AnyEvent because it doesn't make sense outside the embedded
793 interpreter inside *rxvt-unicode*, and it is updated and maintained as
794 part of the *rxvt-unicode* distribution.
795
796 *rxvt-unicode* also cheats a bit by not providing blocking access to
797 condition variables: code blocking while waiting for a condition will
798 "die". This still works with most modules/usages, and blocking calls
799 must not be done in an interactive application, so it makes sense.
800 830
801ENVIRONMENT VARIABLES 831ENVIRONMENT VARIABLES
802 The following environment variables are used by this module: 832 The following environment variables are used by this module or its
833 submodules:
803 834
804 "PERL_ANYEVENT_VERBOSE" 835 "PERL_ANYEVENT_VERBOSE"
805 By default, AnyEvent will be completely silent except in fatal 836 By default, AnyEvent will be completely silent except in fatal
806 conditions. You can set this environment variable to make AnyEvent 837 conditions. You can set this environment variable to make AnyEvent
807 more talkative. 838 more talkative.
… …
810 conditions, such as not being able to load the event model specified 841 conditions, such as not being able to load the event model specified
811 by "PERL_ANYEVENT_MODEL". 842 by "PERL_ANYEVENT_MODEL".
812 843
813 When set to 2 or higher, cause AnyEvent to report to STDERR which 844 When set to 2 or higher, cause AnyEvent to report to STDERR which
814 event model it chooses. 845 event model it chooses.
846
847 "PERL_ANYEVENT_STRICT"
848 AnyEvent does not do much argument checking by default, as thorough
849 argument checking is very costly. Setting this variable to a true
850 value will cause AnyEvent to load "AnyEvent::Strict" and then to
851 thoroughly check the arguments passed to most method calls. If it
852 finds any problems it will croak.
853
854 In other words, enables "strict" mode.
855
856 Unlike "use strict", it is definitely recommended ot keep it off in
857 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
858 while developing programs can be very useful, however.
815 859
816 "PERL_ANYEVENT_MODEL" 860 "PERL_ANYEVENT_MODEL"
817 This can be used to specify the event model to be used by AnyEvent, 861 This can be used to specify the event model to be used by AnyEvent,
818 before auto detection and -probing kicks in. It must be a string 862 before auto detection and -probing kicks in. It must be a string
819 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 863 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
838 mentioned will be used, and preference will be given to protocols 882 mentioned will be used, and preference will be given to protocols
839 mentioned earlier in the list. 883 mentioned earlier in the list.
840 884
841 This variable can effectively be used for denial-of-service attacks 885 This variable can effectively be used for denial-of-service attacks
842 against local programs (e.g. when setuid), although the impact is 886 against local programs (e.g. when setuid), although the impact is
843 likely small, as the program has to handle connection errors 887 likely small, as the program has to handle conenction and other
844 already- 888 failures anyways.
845 889
846 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 890 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
847 IPv6, but support both and try to use both. 891 IPv6, but support both and try to use both.
848 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 892 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
849 resolve or contact IPv6 addresses. 893 resolve or contact IPv6 addresses.
… …
860 EDNS0 in its DNS requests. 904 EDNS0 in its DNS requests.
861 905
862 "PERL_ANYEVENT_MAX_FORKS" 906 "PERL_ANYEVENT_MAX_FORKS"
863 The maximum number of child processes that 907 The maximum number of child processes that
864 "AnyEvent::Util::fork_call" will create in parallel. 908 "AnyEvent::Util::fork_call" will create in parallel.
909
910SUPPLYING YOUR OWN EVENT MODEL INTERFACE
911 This is an advanced topic that you do not normally need to use AnyEvent
912 in a module. This section is only of use to event loop authors who want
913 to provide AnyEvent compatibility.
914
915 If you need to support another event library which isn't directly
916 supported by AnyEvent, you can supply your own interface to it by
917 pushing, before the first watcher gets created, the package name of the
918 event module and the package name of the interface to use onto
919 @AnyEvent::REGISTRY. You can do that before and even without loading
920 AnyEvent, so it is reasonably cheap.
921
922 Example:
923
924 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
925
926 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
927 package/class when it finds the "urxvt" package/module is already
928 loaded.
929
930 When AnyEvent is loaded and asked to find a suitable event model, it
931 will first check for the presence of urxvt by trying to "use" the
932 "urxvt::anyevent" module.
933
934 The class should provide implementations for all watcher types. See
935 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
936 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
937 the sources.
938
939 If you don't provide "signal" and "child" watchers than AnyEvent will
940 provide suitable (hopefully) replacements.
941
942 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
943 terminal emulator uses the above line as-is. An interface isn't included
944 in AnyEvent because it doesn't make sense outside the embedded
945 interpreter inside *rxvt-unicode*, and it is updated and maintained as
946 part of the *rxvt-unicode* distribution.
947
948 *rxvt-unicode* also cheats a bit by not providing blocking access to
949 condition variables: code blocking while waiting for a condition will
950 "die". This still works with most modules/usages, and blocking calls
951 must not be done in an interactive application, so it makes sense.
865 952
866EXAMPLE PROGRAM 953EXAMPLE PROGRAM
867 The following program uses an I/O watcher to read data from STDIN, a 954 The following program uses an I/O watcher to read data from STDIN, a
868 timer to display a message once per second, and a condition variable to 955 timer to display a message once per second, and a condition variable to
869 quit the program when the user enters quit: 956 quit the program when the user enters quit:
… …
1056 *destroy* is the time, in microseconds, that it takes to destroy a 1143 *destroy* is the time, in microseconds, that it takes to destroy a
1057 single watcher. 1144 single watcher.
1058 1145
1059 Results 1146 Results
1060 name watchers bytes create invoke destroy comment 1147 name watchers bytes create invoke destroy comment
1061 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1148 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1062 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1149 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1063 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1150 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1064 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1151 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1065 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1152 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1066 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1153 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1067 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1154 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1068 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1155 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1069 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1156 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1070 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1157 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1071 1158
1072 Discussion 1159 Discussion
1073 The benchmark does *not* measure scalability of the event loop very 1160 The benchmark does *not* measure scalability of the event loop very
1074 well. For example, a select-based event loop (such as the pure perl one) 1161 well. For example, a select-based event loop (such as the pure perl one)
1075 can never compete with an event loop that uses epoll when the number of 1162 can never compete with an event loop that uses epoll when the number of
… …
1256 1343
1257 Summary 1344 Summary
1258 * C-based event loops perform very well with small number of watchers, 1345 * C-based event loops perform very well with small number of watchers,
1259 as the management overhead dominates. 1346 as the management overhead dominates.
1260 1347
1348SIGNALS
1349 AnyEvent currently installs handlers for these signals:
1350
1351 SIGCHLD
1352 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1353 emulation for event loops that do not support them natively. Also,
1354 some event loops install a similar handler.
1355
1356 SIGPIPE
1357 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1358 "undef" when AnyEvent gets loaded.
1359
1360 The rationale for this is that AnyEvent users usually do not really
1361 depend on SIGPIPE delivery (which is purely an optimisation for
1362 shell use, or badly-written programs), but "SIGPIPE" can cause
1363 spurious and rare program exits as a lot of people do not expect
1364 "SIGPIPE" when writing to some random socket.
1365
1366 The rationale for installing a no-op handler as opposed to ignoring
1367 it is that this way, the handler will be restored to defaults on
1368 exec.
1369
1370 Feel free to install your own handler, or reset it to defaults.
1371
1261FORK 1372FORK
1262 Most event libraries are not fork-safe. The ones who are usually are 1373 Most event libraries are not fork-safe. The ones who are usually are
1263 because they rely on inefficient but fork-safe "select" or "poll" calls. 1374 because they rely on inefficient but fork-safe "select" or "poll" calls.
1264 Only EV is fully fork-aware. 1375 Only EV is fully fork-aware.
1265 1376
… …
1281 1392
1282 use AnyEvent; 1393 use AnyEvent;
1283 1394
1284 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1395 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1285 be used to probe what backend is used and gain other information (which 1396 be used to probe what backend is used and gain other information (which
1286 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1397 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1398 and $ENV{PERL_ANYEGENT_STRICT}.
1287 1399
1288BUGS 1400BUGS
1289 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1401 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1290 hard to work around. If you suffer from memleaks, first upgrade to Perl 1402 hard to work around. If you suffer from memleaks, first upgrade to Perl
1291 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1403 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1292 annoying mamleaks, such as leaking on "map" and "grep" but it is usually 1404 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1293 not as pronounced). 1405 not as pronounced).
1294 1406
1295SEE ALSO 1407SEE ALSO
1296 Utility functions: AnyEvent::Util. 1408 Utility functions: AnyEvent::Util.
1297 1409

Diff Legend

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