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

Comparing AnyEvent/README (file contents):
Revision 1.29 by root, Tue Jul 29 10:20:33 2008 UTC vs.
Revision 1.41 by root, Fri Jun 26 06:33:17 2009 UTC

1NAME 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 and POE are various supported
5 loops 5 event 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 { ... });
11 12
13 # one-shot or repeating timers
12 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); 14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
13 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... 15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
14 16
15 print AnyEvent->now; # prints current event loop time 17 print AnyEvent->now; # prints current event loop time
16 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. 18 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
17 19
20 # POSIX signal
18 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... }); 21 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
19 22
23 # child process exit
20 my $w = AnyEvent->child (pid => $pid, cb => sub { 24 my $w = AnyEvent->child (pid => $pid, cb => sub {
21 my ($pid, $status) = @_; 25 my ($pid, $status) = @_;
22 ... 26 ...
23 }); 27 });
28
29 # called when event loop idle (if applicable)
30 my $w = AnyEvent->idle (cb => sub { ... });
24 31
25 my $w = AnyEvent->condvar; # stores whether a condition was flagged 32 my $w = AnyEvent->condvar; # stores whether a condition was flagged
26 $w->send; # wake up current and all future recv's 33 $w->send; # wake up current and all future recv's
27 $w->recv; # enters "main loop" till $condvar gets ->send 34 $w->recv; # enters "main loop" till $condvar gets ->send
28 # use a condvar in callback mode: 35 # use a condvar in callback mode:
… …
132 These watchers are normal Perl objects with normal Perl lifetime. After 139 These watchers are normal Perl objects with normal Perl lifetime. After
133 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
134 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
135 in control). 142 in control).
136 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
137 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
138 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
139 to it). 152 to it).
140 153
141 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.
… …
156 169
157 I/O WATCHERS 170 I/O WATCHERS
158 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
159 the following mandatory key-value pairs as arguments: 172 the following mandatory key-value pairs as arguments:
160 173
161 "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
162 (AnyEvent might or might not keep a reference to this file handle). 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
163 "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
164 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 182 watcher waiting for "r"eadable or "w"ritable events, respectively.
183
165 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.
166 185
167 Although the callback might get passed parameters, their value and 186 Although the callback might get passed parameters, their value and
168 presence is undefined and you cannot rely on them. Portable AnyEvent 187 presence is undefined and you cannot rely on them. Portable AnyEvent
169 callbacks cannot use arguments passed to I/O watcher callbacks. 188 callbacks cannot use arguments passed to I/O watcher callbacks.
170 189
… …
302 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
303 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
304 the difference between "AnyEvent->time" and "AnyEvent->now" into 323 the difference between "AnyEvent->time" and "AnyEvent->now" into
305 account. 324 account.
306 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
307 SIGNAL WATCHERS 340 SIGNAL WATCHERS
308 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
309 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 342 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
310 callback to be invoked whenever a signal occurs. 343 callback to be invoked whenever a signal occurs.
311 344
… …
330 363
331 CHILD PROCESS WATCHERS 364 CHILD PROCESS WATCHERS
332 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.
333 366
334 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
335 watches for any child process exit). The watcher will trigger as often 368 watches for any child process exit). The watcher will triggered only
336 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
337 signal handler for "SIGCHLD". The callback will be called with the pid 370 on any trace events (stopped/continued).
338 and exit status (as returned by waitpid), so unlike other watcher types, 371
339 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).
340 380
341 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
342 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
343 could have exited already (and no SIGCHLD will be sent anymore). 383 could have exited already (and no SIGCHLD will be sent anymore).
344 384
345 Not all event models handle this correctly (POE doesn't), but even for 385 Not all event models handle this correctly (neither POE nor IO::Async
386 do, see their AnyEvent::Impl manpages for details), but even for event
346 event models that *do* handle this correctly, they usually need to be 387 models that *do* handle this correctly, they usually need to be loaded
347 loaded before the process exits (i.e. before you fork in the first 388 before the process exits (i.e. before you fork in the first place).
348 place). 389 AnyEvent's pure perl event loop handles all cases correctly regardless
390 of when you start the watcher.
349 391
350 This means you cannot create a child watcher as the very first thing in 392 This means you cannot create a child watcher as the very first thing in
351 an AnyEvent program, you *have* to create at least one watcher before 393 an AnyEvent program, you *have* to create at least one watcher before
352 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 394 you "fork" the child (alternatively, you can call "AnyEvent::detect").
353 395
354 Example: fork a process and wait for it 396 Example: fork a process and wait for it
355 397
356 my $done = AnyEvent->condvar; 398 my $done = AnyEvent->condvar;
357 399
358 my $pid = fork or exit 5; 400 my $pid = fork or exit 5;
359 401
360 my $w = AnyEvent->child ( 402 my $w = AnyEvent->child (
361 pid => $pid, 403 pid => $pid,
362 cb => sub { 404 cb => sub {
363 my ($pid, $status) = @_; 405 my ($pid, $status) = @_;
364 warn "pid $pid exited with status $status"; 406 warn "pid $pid exited with status $status";
365 $done->send; 407 $done->send;
366 }, 408 },
367 ); 409 );
368 410
369 # do something else, then wait for process exit 411 # do something else, then wait for process exit
370 $done->recv; 412 $done->recv;
413
414 IDLE WATCHERS
415 Sometimes there is a need to do something, but it is not so important to
416 do it instantly, but only when there is nothing better to do. This
417 "nothing better to do" is usually defined to be "no other events need
418 attention by the event loop".
419
420 Idle watchers ideally get invoked when the event loop has nothing better
421 to do, just before it would block the process to wait for new events.
422 Instead of blocking, the idle watcher is invoked.
423
424 Most event loops unfortunately do not really support idle watchers (only
425 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
426 will simply call the callback "from time to time".
427
428 Example: read lines from STDIN, but only process them when the program
429 is otherwise idle:
430
431 my @lines; # read data
432 my $idle_w;
433 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
434 push @lines, scalar <STDIN>;
435
436 # start an idle watcher, if not already done
437 $idle_w ||= AnyEvent->idle (cb => sub {
438 # handle only one line, when there are lines left
439 if (my $line = shift @lines) {
440 print "handled when idle: $line";
441 } else {
442 # otherwise disable the idle watcher again
443 undef $idle_w;
444 }
445 });
446 });
371 447
372 CONDITION VARIABLES 448 CONDITION VARIABLES
373 If you are familiar with some event loops you will know that all of them 449 If you are familiar with some event loops you will know that all of them
374 require you to run some blocking "loop", "run" or similar function that 450 require you to run some blocking "loop", "run" or similar function that
375 will actively watch for new events and call your callbacks. 451 will actively watch for new events and call your callbacks.
… …
623 AnyEvent::Impl::Tk based on Tk, very bad choice. 699 AnyEvent::Impl::Tk based on Tk, very bad choice.
624 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 700 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
625 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 701 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
626 AnyEvent::Impl::POE based on POE, not generic enough for full support. 702 AnyEvent::Impl::POE based on POE, not generic enough for full support.
627 703
704 # warning, support for IO::Async is only partial, as it is too broken
705 # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
706 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
707
628 There is no support for WxWidgets, as WxWidgets has no support for 708 There is no support for WxWidgets, as WxWidgets has no support for
629 watching file handles. However, you can use WxWidgets through the 709 watching file handles. However, you can use WxWidgets through the
630 POE Adaptor, as POE has a Wx backend that simply polls 20 times per 710 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
631 second, which was considered to be too horrible to even consider for 711 second, which was considered to be too horrible to even consider for
632 AnyEvent. Likewise, other POE backends can be used by AnyEvent by 712 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
… …
770 850
771 AnyEvent::IGS 851 AnyEvent::IGS
772 A non-blocking interface to the Internet Go Server protocol (used by 852 A non-blocking interface to the Internet Go Server protocol (used by
773 App::IGS). 853 App::IGS).
774 854
855 AnyEvent::IRC
856 AnyEvent based IRC client module family (replacing the older
775 Net::IRC3 857 Net::IRC3).
776 AnyEvent based IRC client module family.
777 858
778 Net::XMPP2 859 Net::XMPP2
779 AnyEvent based XMPP (Jabber protocol) module family. 860 AnyEvent based XMPP (Jabber protocol) module family.
780 861
781 Net::FCP 862 Net::FCP
… …
790 871
791 IO::Lambda 872 IO::Lambda
792 The lambda approach to I/O - don't ask, look there. Can use 873 The lambda approach to I/O - don't ask, look there. Can use
793 AnyEvent. 874 AnyEvent.
794 875
795SUPPLYING YOUR OWN EVENT MODEL INTERFACE 876ERROR AND EXCEPTION HANDLING
796 This is an advanced topic that you do not normally need to use AnyEvent 877 In general, AnyEvent does not do any error handling - it relies on the
797 in a module. This section is only of use to event loop authors who want 878 caller to do that if required. The AnyEvent::Strict module (see also the
798 to provide AnyEvent compatibility. 879 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
880 checking of all AnyEvent methods, however, which is highly useful during
881 development.
799 882
800 If you need to support another event library which isn't directly 883 As for exception handling (i.e. runtime errors and exceptions thrown
801 supported by AnyEvent, you can supply your own interface to it by 884 while executing a callback), this is not only highly event-loop
802 pushing, before the first watcher gets created, the package name of the 885 specific, but also not in any way wrapped by this module, as this is the
803 event module and the package name of the interface to use onto 886 job of the main program.
804 @AnyEvent::REGISTRY. You can do that before and even without loading
805 AnyEvent, so it is reasonably cheap.
806 887
807 Example: 888 The pure perl event loop simply re-throws the exception (usually within
808 889 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
809 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 890 Glib uses "install_exception_handler" and so on.
810
811 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
812 package/class when it finds the "urxvt" package/module is already
813 loaded.
814
815 When AnyEvent is loaded and asked to find a suitable event model, it
816 will first check for the presence of urxvt by trying to "use" the
817 "urxvt::anyevent" module.
818
819 The class should provide implementations for all watcher types. See
820 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
821 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
822 the sources.
823
824 If you don't provide "signal" and "child" watchers than AnyEvent will
825 provide suitable (hopefully) replacements.
826
827 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
828 terminal emulator uses the above line as-is. An interface isn't included
829 in AnyEvent because it doesn't make sense outside the embedded
830 interpreter inside *rxvt-unicode*, and it is updated and maintained as
831 part of the *rxvt-unicode* distribution.
832
833 *rxvt-unicode* also cheats a bit by not providing blocking access to
834 condition variables: code blocking while waiting for a condition will
835 "die". This still works with most modules/usages, and blocking calls
836 must not be done in an interactive application, so it makes sense.
837 891
838ENVIRONMENT VARIABLES 892ENVIRONMENT VARIABLES
839 The following environment variables are used by this module: 893 The following environment variables are used by this module or its
894 submodules.
895
896 Note that AnyEvent will remove *all* environment variables starting with
897 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
898 enabled.
840 899
841 "PERL_ANYEVENT_VERBOSE" 900 "PERL_ANYEVENT_VERBOSE"
842 By default, AnyEvent will be completely silent except in fatal 901 By default, AnyEvent will be completely silent except in fatal
843 conditions. You can set this environment variable to make AnyEvent 902 conditions. You can set this environment variable to make AnyEvent
844 more talkative. 903 more talkative.
… …
853 "PERL_ANYEVENT_STRICT" 912 "PERL_ANYEVENT_STRICT"
854 AnyEvent does not do much argument checking by default, as thorough 913 AnyEvent does not do much argument checking by default, as thorough
855 argument checking is very costly. Setting this variable to a true 914 argument checking is very costly. Setting this variable to a true
856 value will cause AnyEvent to load "AnyEvent::Strict" and then to 915 value will cause AnyEvent to load "AnyEvent::Strict" and then to
857 thoroughly check the arguments passed to most method calls. If it 916 thoroughly check the arguments passed to most method calls. If it
858 finds any problems it will croak. 917 finds any problems, it will croak.
859 918
860 In other words, enables "strict" mode. 919 In other words, enables "strict" mode.
861 920
862 Unlike "use strict" it is definitely recommended ot keep it off in 921 Unlike "use strict", it is definitely recommended to keep it off in
863 production. 922 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
923 while developing programs can be very useful, however.
864 924
865 "PERL_ANYEVENT_MODEL" 925 "PERL_ANYEVENT_MODEL"
866 This can be used to specify the event model to be used by AnyEvent, 926 This can be used to specify the event model to be used by AnyEvent,
867 before auto detection and -probing kicks in. It must be a string 927 before auto detection and -probing kicks in. It must be a string
868 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 928 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
887 mentioned will be used, and preference will be given to protocols 947 mentioned will be used, and preference will be given to protocols
888 mentioned earlier in the list. 948 mentioned earlier in the list.
889 949
890 This variable can effectively be used for denial-of-service attacks 950 This variable can effectively be used for denial-of-service attacks
891 against local programs (e.g. when setuid), although the impact is 951 against local programs (e.g. when setuid), although the impact is
892 likely small, as the program has to handle connection errors 952 likely small, as the program has to handle conenction and other
893 already- 953 failures anyways.
894 954
895 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 955 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
896 IPv6, but support both and try to use both. 956 IPv6, but support both and try to use both.
897 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 957 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
898 resolve or contact IPv6 addresses. 958 resolve or contact IPv6 addresses.
… …
909 EDNS0 in its DNS requests. 969 EDNS0 in its DNS requests.
910 970
911 "PERL_ANYEVENT_MAX_FORKS" 971 "PERL_ANYEVENT_MAX_FORKS"
912 The maximum number of child processes that 972 The maximum number of child processes that
913 "AnyEvent::Util::fork_call" will create in parallel. 973 "AnyEvent::Util::fork_call" will create in parallel.
974
975SUPPLYING YOUR OWN EVENT MODEL INTERFACE
976 This is an advanced topic that you do not normally need to use AnyEvent
977 in a module. This section is only of use to event loop authors who want
978 to provide AnyEvent compatibility.
979
980 If you need to support another event library which isn't directly
981 supported by AnyEvent, you can supply your own interface to it by
982 pushing, before the first watcher gets created, the package name of the
983 event module and the package name of the interface to use onto
984 @AnyEvent::REGISTRY. You can do that before and even without loading
985 AnyEvent, so it is reasonably cheap.
986
987 Example:
988
989 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
990
991 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
992 package/class when it finds the "urxvt" package/module is already
993 loaded.
994
995 When AnyEvent is loaded and asked to find a suitable event model, it
996 will first check for the presence of urxvt by trying to "use" the
997 "urxvt::anyevent" module.
998
999 The class should provide implementations for all watcher types. See
1000 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
1001 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
1002 the sources.
1003
1004 If you don't provide "signal" and "child" watchers than AnyEvent will
1005 provide suitable (hopefully) replacements.
1006
1007 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
1008 terminal emulator uses the above line as-is. An interface isn't included
1009 in AnyEvent because it doesn't make sense outside the embedded
1010 interpreter inside *rxvt-unicode*, and it is updated and maintained as
1011 part of the *rxvt-unicode* distribution.
1012
1013 *rxvt-unicode* also cheats a bit by not providing blocking access to
1014 condition variables: code blocking while waiting for a condition will
1015 "die". This still works with most modules/usages, and blocking calls
1016 must not be done in an interactive application, so it makes sense.
914 1017
915EXAMPLE PROGRAM 1018EXAMPLE PROGRAM
916 The following program uses an I/O watcher to read data from STDIN, a 1019 The following program uses an I/O watcher to read data from STDIN, a
917 timer to display a message once per second, and a condition variable to 1020 timer to display a message once per second, and a condition variable to
918 quit the program when the user enters quit: 1021 quit the program when the user enters quit:
… …
1105 *destroy* is the time, in microseconds, that it takes to destroy a 1208 *destroy* is the time, in microseconds, that it takes to destroy a
1106 single watcher. 1209 single watcher.
1107 1210
1108 Results 1211 Results
1109 name watchers bytes create invoke destroy comment 1212 name watchers bytes create invoke destroy comment
1110 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1213 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1111 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1214 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1112 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1215 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1113 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1216 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1114 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1217 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1115 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1218 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1219 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
1220 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1116 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1221 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1117 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1222 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1118 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1223 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1119 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1224 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1120 1225
1121 Discussion 1226 Discussion
1122 The benchmark does *not* measure scalability of the event loop very 1227 The benchmark does *not* measure scalability of the event loop very
1123 well. For example, a select-based event loop (such as the pure perl one) 1228 well. For example, a select-based event loop (such as the pure perl one)
1124 can never compete with an event loop that uses epoll when the number of 1229 can never compete with an event loop that uses epoll when the number of
… …
1149 few of them active), of course, but this was not subject of this 1254 few of them active), of course, but this was not subject of this
1150 benchmark. 1255 benchmark.
1151 1256
1152 The "Event" module has a relatively high setup and callback invocation 1257 The "Event" module has a relatively high setup and callback invocation
1153 cost, but overall scores in on the third place. 1258 cost, but overall scores in on the third place.
1259
1260 "IO::Async" performs admirably well, about on par with "Event", even
1261 when using its pure perl backend.
1154 1262
1155 "Glib"'s memory usage is quite a bit higher, but it features a faster 1263 "Glib"'s memory usage is quite a bit higher, but it features a faster
1156 callback invocation and overall ends up in the same class as "Event". 1264 callback invocation and overall ends up in the same class as "Event".
1157 However, Glib scales extremely badly, doubling the number of watchers 1265 However, Glib scales extremely badly, doubling the number of watchers
1158 increases the processing time by more than a factor of four, making it 1266 increases the processing time by more than a factor of four, making it
… …
1229 single "request", that is, reading the token from the pipe and 1337 single "request", that is, reading the token from the pipe and
1230 forwarding it to another server. This includes deleting the old timeout 1338 forwarding it to another server. This includes deleting the old timeout
1231 and creating a new one that moves the timeout into the future. 1339 and creating a new one that moves the timeout into the future.
1232 1340
1233 Results 1341 Results
1234 name sockets create request 1342 name sockets create request
1235 EV 20000 69.01 11.16 1343 EV 20000 69.01 11.16
1236 Perl 20000 73.32 35.87 1344 Perl 20000 73.32 35.87
1345 IOAsync 20000 157.00 98.14 epoll
1346 IOAsync 20000 159.31 616.06 poll
1237 Event 20000 212.62 257.32 1347 Event 20000 212.62 257.32
1238 Glib 20000 651.16 1896.30 1348 Glib 20000 651.16 1896.30
1239 POE 20000 349.67 12317.24 uses POE::Loop::Event 1349 POE 20000 349.67 12317.24 uses POE::Loop::Event
1240 1350
1241 Discussion 1351 Discussion
1242 This benchmark *does* measure scalability and overall performance of the 1352 This benchmark *does* measure scalability and overall performance of the
1243 particular event loop. 1353 particular event loop.
1244 1354
1245 EV is again fastest. Since it is using epoll on my system, the setup 1355 EV is again fastest. Since it is using epoll on my system, the setup
1246 time is relatively high, though. 1356 time is relatively high, though.
1247 1357
1248 Perl surprisingly comes second. It is much faster than the C-based event 1358 Perl surprisingly comes second. It is much faster than the C-based event
1249 loops Event and Glib. 1359 loops Event and Glib.
1360
1361 IO::Async performs very well when using its epoll backend, and still
1362 quite good compared to Glib when using its pure perl backend.
1250 1363
1251 Event suffers from high setup time as well (look at its code and you 1364 Event suffers from high setup time as well (look at its code and you
1252 will understand why). Callback invocation also has a high overhead 1365 will understand why). Callback invocation also has a high overhead
1253 compared to the "$_->() for .."-style loop that the Perl event loop 1366 compared to the "$_->() for .."-style loop that the Perl event loop
1254 uses. Event uses select or poll in basically all documented 1367 uses. Event uses select or poll in basically all documented
… …
1305 1418
1306 Summary 1419 Summary
1307 * C-based event loops perform very well with small number of watchers, 1420 * C-based event loops perform very well with small number of watchers,
1308 as the management overhead dominates. 1421 as the management overhead dominates.
1309 1422
1423 THE IO::Lambda BENCHMARK
1424 Recently I was told about the benchmark in the IO::Lambda manpage, which
1425 could be misinterpreted to make AnyEvent look bad. In fact, the
1426 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1427 better (which shouldn't come as a surprise to anybody). As such, the
1428 benchmark is fine, and mostly shows that the AnyEvent backend from
1429 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1430 without the extra baggage? To explore this, I wrote the equivalent
1431 benchmark for AnyEvent.
1432
1433 The benchmark itself creates an echo-server, and then, for 500 times,
1434 connects to the echo server, sends a line, waits for the reply, and then
1435 creates the next connection. This is a rather bad benchmark, as it
1436 doesn't test the efficiency of the framework or much non-blocking I/O,
1437 but it is a benchmark nevertheless.
1438
1439 name runtime
1440 Lambda/select 0.330 sec
1441 + optimized 0.122 sec
1442 Lambda/AnyEvent 0.327 sec
1443 + optimized 0.138 sec
1444 Raw sockets/select 0.077 sec
1445 POE/select, components 0.662 sec
1446 POE/select, raw sockets 0.226 sec
1447 POE/select, optimized 0.404 sec
1448
1449 AnyEvent/select/nb 0.085 sec
1450 AnyEvent/EV/nb 0.068 sec
1451 +state machine 0.134 sec
1452
1453 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1454 benchmarks actually make blocking connects and use 100% blocking I/O,
1455 defeating the purpose of an event-based solution. All of the newly
1456 written AnyEvent benchmarks use 100% non-blocking connects (using
1457 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1458 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1459 connects generally require a lot more bookkeeping and event handling
1460 than blocking connects (which involve a single syscall only).
1461
1462 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1463 offers similar expressive power as POE and IO::Lambda, using
1464 conventional Perl syntax. This means that both the echo server and the
1465 client are 100% non-blocking, further placing it at a disadvantage.
1466
1467 As you can see, the AnyEvent + EV combination even beats the
1468 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1469 backend easily beats IO::Lambda and POE.
1470
1471 And even the 100% non-blocking version written using the high-level (and
1472 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a
1473 large margin, even though it does all of DNS, tcp-connect and socket I/O
1474 in a non-blocking way.
1475
1476 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1477 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1478 part of the IO::lambda distribution and were used without any changes.
1479
1480SIGNALS
1481 AnyEvent currently installs handlers for these signals:
1482
1483 SIGCHLD
1484 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1485 emulation for event loops that do not support them natively. Also,
1486 some event loops install a similar handler.
1487
1488 If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent
1489 will reset it to default, to avoid losing child exit statuses.
1490
1491 SIGPIPE
1492 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1493 "undef" when AnyEvent gets loaded.
1494
1495 The rationale for this is that AnyEvent users usually do not really
1496 depend on SIGPIPE delivery (which is purely an optimisation for
1497 shell use, or badly-written programs), but "SIGPIPE" can cause
1498 spurious and rare program exits as a lot of people do not expect
1499 "SIGPIPE" when writing to some random socket.
1500
1501 The rationale for installing a no-op handler as opposed to ignoring
1502 it is that this way, the handler will be restored to defaults on
1503 exec.
1504
1505 Feel free to install your own handler, or reset it to defaults.
1506
1310FORK 1507FORK
1311 Most event libraries are not fork-safe. The ones who are usually are 1508 Most event libraries are not fork-safe. The ones who are usually are
1312 because they rely on inefficient but fork-safe "select" or "poll" calls. 1509 because they rely on inefficient but fork-safe "select" or "poll" calls.
1313 Only EV is fully fork-aware. 1510 Only EV is fully fork-aware.
1314 1511
… …
1325 1522
1326 You can make AnyEvent completely ignore this variable by deleting it 1523 You can make AnyEvent completely ignore this variable by deleting it
1327 before the first watcher gets created, e.g. with a "BEGIN" block: 1524 before the first watcher gets created, e.g. with a "BEGIN" block:
1328 1525
1329 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1526 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1330 1527
1331 use AnyEvent; 1528 use AnyEvent;
1332 1529
1333 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1530 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1334 be used to probe what backend is used and gain other information (which 1531 be used to probe what backend is used and gain other information (which
1335 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), 1532 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1336 and $ENV{PERL_ANYEGENT_STRICT}. 1533 and $ENV{PERL_ANYEVENT_STRICT}.
1534
1535 Note that AnyEvent will remove *all* environment variables starting with
1536 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1537 enabled.
1337 1538
1338BUGS 1539BUGS
1339 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1540 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1340 hard to work around. If you suffer from memleaks, first upgrade to Perl 1541 hard to work around. If you suffer from memleaks, first upgrade to Perl
1341 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1542 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1342 annoying mamleaks, such as leaking on "map" and "grep" but it is usually 1543 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1343 not as pronounced). 1544 not as pronounced).
1344 1545
1345SEE ALSO 1546SEE ALSO
1346 Utility functions: AnyEvent::Util. 1547 Utility functions: AnyEvent::Util.
1347 1548

Diff Legend

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