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

Comparing AnyEvent/README (file contents):
Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC vs.
Revision 1.58 by root, Sun Dec 20 22:49:52 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - the DBI of event loop programming
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 event loops. 5 Qt and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable 10 # file descriptor readable
… …
37 37
38INTRODUCTION/TUTORIAL 38INTRODUCTION/TUTORIAL
39 This manpage is mainly a reference manual. If you are interested in a 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 40 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
41 manpage. 41 manpage.
42
43SUPPORT
44 There is a mailinglist for discussing all things AnyEvent, and an IRC
45 channel, too.
46
47 See the AnyEvent project page at the Schmorpforge Ta-Sa Software
48 Repository, at <http://anyevent.schmorp.de>, for more info.
42 49
43WHY YOU SHOULD USE THIS MODULE (OR NOT) 50WHY YOU SHOULD USE THIS MODULE (OR NOT)
44 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 51 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
45 nowadays. So what is different about AnyEvent? 52 nowadays. So what is different about AnyEvent?
46 53
… …
166 Note that "my $w; $w =" combination. This is necessary because in Perl, 173 Note that "my $w; $w =" combination. This is necessary because in Perl,
167 my variables are only visible after the statement in which they are 174 my variables are only visible after the statement in which they are
168 declared. 175 declared.
169 176
170 I/O WATCHERS 177 I/O WATCHERS
178 $w = AnyEvent->io (
179 fh => <filehandle_or_fileno>,
180 poll => <"r" or "w">,
181 cb => <callback>,
182 );
183
171 You can create an I/O watcher by calling the "AnyEvent->io" method with 184 You can create an I/O watcher by calling the "AnyEvent->io" method with
172 the following mandatory key-value pairs as arguments: 185 the following mandatory key-value pairs as arguments:
173 186
174 "fh" is the Perl *file handle* (or a naked file descriptor) to watch for 187 "fh" is the Perl *file handle* (or a naked file descriptor) to watch for
175 events (AnyEvent might or might not keep a reference to this file 188 events (AnyEvent might or might not keep a reference to this file
… …
203 warn "read: $input\n"; 216 warn "read: $input\n";
204 undef $w; 217 undef $w;
205 }); 218 });
206 219
207 TIME WATCHERS 220 TIME WATCHERS
221 $w = AnyEvent->timer (after => <seconds>, cb => <callback>);
222
223 $w = AnyEvent->timer (
224 after => <fractional_seconds>,
225 interval => <fractional_seconds>,
226 cb => <callback>,
227 );
228
208 You can create a time watcher by calling the "AnyEvent->timer" method 229 You can create a time watcher by calling the "AnyEvent->timer" method
209 with the following mandatory arguments: 230 with the following mandatory arguments:
210 231
211 "after" specifies after how many seconds (fractional values are 232 "after" specifies after how many seconds (fractional values are
212 supported) the callback should be invoked. "cb" is the callback to 233 supported) the callback should be invoked. "cb" is the callback to
… …
333 time, which might affect timers and time-outs. 354 time, which might affect timers and time-outs.
334 355
335 When this is the case, you can call this method, which will update 356 When this is the case, you can call this method, which will update
336 the event loop's idea of "current time". 357 the event loop's idea of "current time".
337 358
359 A typical example would be a script in a web server (e.g.
360 "mod_perl") - when mod_perl executes the script, then the event loop
361 will have the wrong idea about the "current time" (being potentially
362 far in the past, when the script ran the last time). In that case
363 you should arrange a call to "AnyEvent->now_update" each time the
364 web server process wakes up again (e.g. at the start of your script,
365 or in a handler).
366
338 Note that updating the time *might* cause some events to be handled. 367 Note that updating the time *might* cause some events to be handled.
339 368
340 SIGNAL WATCHERS 369 SIGNAL WATCHERS
370 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
371
341 You can watch for signals using a signal watcher, "signal" is the signal 372 You can watch for signals using a signal watcher, "signal" is the signal
342 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 373 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
343 callback to be invoked whenever a signal occurs. 374 callback to be invoked whenever a signal occurs.
344 375
345 Although the callback might get passed parameters, their value and 376 Although the callback might get passed parameters, their value and
… …
357 388
358 This watcher might use %SIG (depending on the event loop used), so 389 This watcher might use %SIG (depending on the event loop used), so
359 programs overwriting those signals directly will likely not work 390 programs overwriting those signals directly will likely not work
360 correctly. 391 correctly.
361 392
393 Example: exit on SIGINT
394
395 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
396
397 Restart Behaviour
398 While restart behaviour is up to the event loop implementation, most
399 will not restart syscalls (that includes Async::Interrupt and AnyEvent's
400 pure perl implementation).
401
402 Safe/Unsafe Signals
403 Perl signals can be either "safe" (synchronous to opcode handling) or
404 "unsafe" (asynchronous) - the former might get delayed indefinitely, the
405 latter might corrupt your memory.
406
407 AnyEvent signal handlers are, in addition, synchronous to the event
408 loop, i.e. they will not interrupt your running perl program but will
409 only be called as part of the normal event handling (just like timer,
410 I/O etc. callbacks, too).
411
412 Signal Races, Delays and Workarounds
362 Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not 413 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
363 support attaching callbacks to signals, which is a pity, as you cannot 414 callbacks to signals in a generic way, which is a pity, as you cannot do
364 do race-free signal handling in perl. AnyEvent will try to do it's best, 415 race-free signal handling in perl, requiring C libraries for this.
365 but in some cases, signals will be delayed. The maximum time a signal 416 AnyEvent will try to do it's best, which means in some cases, signals
366 might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default: 417 will be delayed. The maximum time a signal might be delayed is specified
367 10 seconds). This variable can be changed only before the first signal 418 in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable
368 watcher is created, and should be left alone otherwise. Higher values 419 can be changed only before the first signal watcher is created, and
420 should be left alone otherwise. This variable determines how often
421 AnyEvent polls for signals (in case a wake-up was missed). Higher values
369 will cause fewer spurious wake-ups, which is better for power and CPU 422 will cause fewer spurious wake-ups, which is better for power and CPU
423 saving.
424
370 saving. All these problems can be avoided by installing the optional 425 All these problems can be avoided by installing the optional
371 Async::Interrupt module. 426 Async::Interrupt module, which works with most event loops. It will not
372 427 work with inherently broken event loops such as Event or Event::Lib (and
373 Example: exit on SIGINT 428 not with POE currently, as POE does it's own workaround with one-second
374 429 latency). For those, you just have to suffer the delays.
375 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
376 430
377 CHILD PROCESS WATCHERS 431 CHILD PROCESS WATCHERS
432 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
433
378 You can also watch on a child process exit and catch its exit status. 434 You can also watch on a child process exit and catch its exit status.
379 435
380 The child process is specified by the "pid" argument (if set to 0, it 436 The child process is specified by the "pid" argument (one some backends,
381 watches for any child process exit). The watcher will triggered only 437 using 0 watches for any child process exit, on others this will croak).
382 when the child process has finished and an exit status is available, not 438 The watcher will be triggered only when the child process has finished
383 on any trace events (stopped/continued). 439 and an exit status is available, not on any trace events
440 (stopped/continued).
384 441
385 The callback will be called with the pid and exit status (as returned by 442 The callback will be called with the pid and exit status (as returned by
386 waitpid), so unlike other watcher types, you *can* rely on child watcher 443 waitpid), so unlike other watcher types, you *can* rely on child watcher
387 callback arguments. 444 callback arguments.
388 445
… …
427 484
428 # do something else, then wait for process exit 485 # do something else, then wait for process exit
429 $done->recv; 486 $done->recv;
430 487
431 IDLE WATCHERS 488 IDLE WATCHERS
489 $w = AnyEvent->idle (cb => <callback>);
490
432 Sometimes there is a need to do something, but it is not so important to 491 Sometimes there is a need to do something, but it is not so important to
433 do it instantly, but only when there is nothing better to do. This 492 do it instantly, but only when there is nothing better to do. This
434 "nothing better to do" is usually defined to be "no other events need 493 "nothing better to do" is usually defined to be "no other events need
435 attention by the event loop". 494 attention by the event loop".
436 495
… …
461 } 520 }
462 }); 521 });
463 }); 522 });
464 523
465 CONDITION VARIABLES 524 CONDITION VARIABLES
525 $cv = AnyEvent->condvar;
526
527 $cv->send (<list>);
528 my @res = $cv->recv;
529
466 If you are familiar with some event loops you will know that all of them 530 If you are familiar with some event loops you will know that all of them
467 require you to run some blocking "loop", "run" or similar function that 531 require you to run some blocking "loop", "run" or similar function that
468 will actively watch for new events and call your callbacks. 532 will actively watch for new events and call your callbacks.
469 533
470 AnyEvent is slightly different: it expects somebody else to run the 534 AnyEvent is slightly different: it expects somebody else to run the
… …
490 Condition variables are similar to callbacks, except that you can 554 Condition variables are similar to callbacks, except that you can
491 optionally wait for them. They can also be called merge points - points 555 optionally wait for them. They can also be called merge points - points
492 in time where multiple outstanding events have been processed. And yet 556 in time where multiple outstanding events have been processed. And yet
493 another way to call them is transactions - each condition variable can 557 another way to call them is transactions - each condition variable can
494 be used to represent a transaction, which finishes at some point and 558 be used to represent a transaction, which finishes at some point and
495 delivers a result. 559 delivers a result. And yet some people know them as "futures" - a
560 promise to compute/deliver something that you can wait for.
496 561
497 Condition variables are very useful to signal that something has 562 Condition variables are very useful to signal that something has
498 finished, for example, if you write a module that does asynchronous http 563 finished, for example, if you write a module that does asynchronous http
499 requests, then a condition variable would be the ideal candidate to 564 requests, then a condition variable would be the ideal candidate to
500 signal the availability of results. The user can either act when the 565 signal the availability of results. The user can either act when the
… …
534 after => 1, 599 after => 1,
535 cb => sub { $result_ready->send }, 600 cb => sub { $result_ready->send },
536 ); 601 );
537 602
538 # this "blocks" (while handling events) till the callback 603 # this "blocks" (while handling events) till the callback
539 # calls -<send 604 # calls ->send
540 $result_ready->recv; 605 $result_ready->recv;
541 606
542 Example: wait for a timer, but take advantage of the fact that condition 607 Example: wait for a timer, but take advantage of the fact that condition
543 variables are also callable directly. 608 variables are also callable directly.
544 609
… …
601 into one. For example, a function that pings many hosts in parallel 666 into one. For example, a function that pings many hosts in parallel
602 might want to use a condition variable for the whole process. 667 might want to use a condition variable for the whole process.
603 668
604 Every call to "->begin" will increment a counter, and every call to 669 Every call to "->begin" will increment a counter, and every call to
605 "->end" will decrement it. If the counter reaches 0 in "->end", the 670 "->end" will decrement it. If the counter reaches 0 in "->end", the
606 (last) callback passed to "begin" will be executed. That callback is 671 (last) callback passed to "begin" will be executed, passing the
607 *supposed* to call "->send", but that is not required. If no 672 condvar as first argument. That callback is *supposed* to call
673 "->send", but that is not required. If no group callback was set,
608 callback was set, "send" will be called without any arguments. 674 "send" will be called without any arguments.
609 675
610 You can think of "$cv->send" giving you an OR condition (one call 676 You can think of "$cv->send" giving you an OR condition (one call
611 sends), while "$cv->begin" and "$cv->end" giving you an AND 677 sends), while "$cv->begin" and "$cv->end" giving you an AND
612 condition (all "begin" calls must be "end"'ed before the condvar 678 condition (all "begin" calls must be "end"'ed before the condvar
613 sends). 679 sends).
… …
641 that are begung can potentially be zero: 707 that are begung can potentially be zero:
642 708
643 my $cv = AnyEvent->condvar; 709 my $cv = AnyEvent->condvar;
644 710
645 my %result; 711 my %result;
646 $cv->begin (sub { $cv->send (\%result) }); 712 $cv->begin (sub { shift->send (\%result) });
647 713
648 for my $host (@list_of_hosts) { 714 for my $host (@list_of_hosts) {
649 $cv->begin; 715 $cv->begin;
650 ping_host_then_call_callback $host, sub { 716 ping_host_then_call_callback $host, sub {
651 $result{$host} = ...; 717 $result{$host} = ...;
… …
718 784
719 $cb = $cv->cb ($cb->($cv)) 785 $cb = $cv->cb ($cb->($cv))
720 This is a mutator function that returns the callback set and 786 This is a mutator function that returns the callback set and
721 optionally replaces it before doing so. 787 optionally replaces it before doing so.
722 788
723 The callback will be called when the condition becomes "true", i.e. 789 The callback will be called when the condition becomes (or already
724 when "send" or "croak" are called, with the only argument being the 790 was) "true", i.e. when "send" or "croak" are called (or were
725 condition variable itself. Calling "recv" inside the callback or at 791 called), with the only argument being the condition variable itself.
792 Calling "recv" inside the callback or at any later time is
726 any later time is guaranteed not to block. 793 guaranteed not to block.
727 794
728SUPPORTED EVENT LOOPS/BACKENDS 795SUPPORTED EVENT LOOPS/BACKENDS
729 The available backend classes are (every class has its own manpage): 796 The available backend classes are (every class has its own manpage):
730 797
731 Backends that are autoprobed when no other event loop can be found. 798 Backends that are autoprobed when no other event loop can be found.
732 EV is the preferred backend when no other event loop seems to be in 799 EV is the preferred backend when no other event loop seems to be in
733 use. If EV is not installed, then AnyEvent will try Event, and, 800 use. If EV is not installed, then AnyEvent will fall back to its own
734 failing that, will fall back to its own pure-perl implementation, 801 pure-perl implementation, which is available everywhere as it comes
735 which is available everywhere as it comes with AnyEvent itself. 802 with AnyEvent itself.
736 803
737 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 804 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
738 AnyEvent::Impl::Event based on Event, very stable, few glitches.
739 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 805 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
740 806
741 Backends that are transparently being picked up when they are used. 807 Backends that are transparently being picked up when they are used.
742 These will be used when they are currently loaded when the first 808 These will be used when they are currently loaded when the first
743 watcher is created, in which case it is assumed that the application 809 watcher is created, in which case it is assumed that the application
744 is using them. This means that AnyEvent will automatically pick the 810 is using them. This means that AnyEvent will automatically pick the
745 right backend when the main program loads an event module before 811 right backend when the main program loads an event module before
746 anything starts to create watchers. Nothing special needs to be done 812 anything starts to create watchers. Nothing special needs to be done
747 by the main program. 813 by the main program.
748 814
815 AnyEvent::Impl::Event based on Event, very stable, few glitches.
749 AnyEvent::Impl::Glib based on Glib, slow but very stable. 816 AnyEvent::Impl::Glib based on Glib, slow but very stable.
750 AnyEvent::Impl::Tk based on Tk, very broken. 817 AnyEvent::Impl::Tk based on Tk, very broken.
751 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 818 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
752 AnyEvent::Impl::POE based on POE, very slow, some limitations. 819 AnyEvent::Impl::POE based on POE, very slow, some limitations.
820 AnyEvent::Impl::Irssi used when running within irssi.
753 821
754 Backends with special needs. 822 Backends with special needs.
755 Qt requires the Qt::Application to be instantiated first, but will 823 Qt requires the Qt::Application to be instantiated first, but will
756 otherwise be picked up automatically. As long as the main program 824 otherwise be picked up automatically. As long as the main program
757 instantiates the application before any AnyEvent watchers are 825 instantiates the application before any AnyEvent watchers are
… …
822 creates and installs the global IO::AIO watcher in a "post_detect" 890 creates and installs the global IO::AIO watcher in a "post_detect"
823 block to avoid autodetecting the event module at load time. 891 block to avoid autodetecting the event module at load time.
824 892
825 If called in scalar or list context, then it creates and returns an 893 If called in scalar or list context, then it creates and returns an
826 object that automatically removes the callback again when it is 894 object that automatically removes the callback again when it is
895 destroyed (or "undef" when the hook was immediately executed). See
827 destroyed. See Coro::BDB for a case where this is useful. 896 AnyEvent::AIO for a case where this is useful.
897
898 Example: Create a watcher for the IO::AIO module and store it in
899 $WATCHER. Only do so after the event loop is initialised, though.
900
901 our WATCHER;
902
903 my $guard = AnyEvent::post_detect {
904 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
905 };
906
907 # the ||= is important in case post_detect immediately runs the block,
908 # as to not clobber the newly-created watcher. assigning both watcher and
909 # post_detect guard to the same variable has the advantage of users being
910 # able to just C<undef $WATCHER> if the watcher causes them grief.
911
912 $WATCHER ||= $guard;
828 913
829 @AnyEvent::post_detect 914 @AnyEvent::post_detect
830 If there are any code references in this array (you can "push" to it 915 If there are any code references in this array (you can "push" to it
831 before or after loading AnyEvent), then they will called directly 916 before or after loading AnyEvent), then they will called directly
832 after the event loop has been chosen. 917 after the event loop has been chosen.
… …
834 You should check $AnyEvent::MODEL before adding to this array, 919 You should check $AnyEvent::MODEL before adding to this array,
835 though: if it is defined then the event loop has already been 920 though: if it is defined then the event loop has already been
836 detected, and the array will be ignored. 921 detected, and the array will be ignored.
837 922
838 Best use "AnyEvent::post_detect { BLOCK }" when your application 923 Best use "AnyEvent::post_detect { BLOCK }" when your application
839 allows it,as it takes care of these details. 924 allows it, as it takes care of these details.
840 925
841 This variable is mainly useful for modules that can do something 926 This variable is mainly useful for modules that can do something
842 useful when AnyEvent is used and thus want to know when it is 927 useful when AnyEvent is used and thus want to know when it is
843 initialised, but do not need to even load it by default. This array 928 initialised, but do not need to even load it by default. This array
844 provides the means to hook into AnyEvent passively, without loading 929 provides the means to hook into AnyEvent passively, without loading
845 it. 930 it.
931
932 Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
933 together, you could put this into Coro (this is the actual code used
934 by Coro to accomplish this):
935
936 if (defined $AnyEvent::MODEL) {
937 # AnyEvent already initialised, so load Coro::AnyEvent
938 require Coro::AnyEvent;
939 } else {
940 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
941 # as soon as it is
942 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
943 }
846 944
847WHAT TO DO IN A MODULE 945WHAT TO DO IN A MODULE
848 As a module author, you should "use AnyEvent" and call AnyEvent methods 946 As a module author, you should "use AnyEvent" and call AnyEvent methods
849 freely, but you should not load a specific event module or rely on it. 947 freely, but you should not load a specific event module or rely on it.
850 948
… …
971 Event::ExecFlow 1069 Event::ExecFlow
972 High level API for event-based execution flow control. 1070 High level API for event-based execution flow control.
973 1071
974 Coro 1072 Coro
975 Has special support for AnyEvent via Coro::AnyEvent. 1073 Has special support for AnyEvent via Coro::AnyEvent.
1074
1075SIMPLIFIED AE API
1076 Starting with version 5.0, AnyEvent officially supports a second, much
1077 simpler, API that is designed to reduce the calling, typing and memory
1078 overhead.
1079
1080 See the AE manpage for details.
976 1081
977ERROR AND EXCEPTION HANDLING 1082ERROR AND EXCEPTION HANDLING
978 In general, AnyEvent does not do any error handling - it relies on the 1083 In general, AnyEvent does not do any error handling - it relies on the
979 caller to do that if required. The AnyEvent::Strict module (see also the 1084 caller to do that if required. The AnyEvent::Strict module (see also the
980 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 1085 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
… …
1159 warn "read: $input\n"; # output what has been read 1264 warn "read: $input\n"; # output what has been read
1160 $cv->send if $input =~ /^q/i; # quit program if /^q/i 1265 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1161 }, 1266 },
1162 ); 1267 );
1163 1268
1164 my $time_watcher; # can only be used once
1165
1166 sub new_timer {
1167 $timer = AnyEvent->timer (after => 1, cb => sub { 1269 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
1168 warn "timeout\n"; # print 'timeout' about every second 1270 warn "timeout\n"; # print 'timeout' at most every second
1169 &new_timer; # and restart the time
1170 });
1171 } 1271 });
1172
1173 new_timer; # create first timer
1174 1272
1175 $cv->recv; # wait until user enters /^q/i 1273 $cv->recv; # wait until user enters /^q/i
1176 1274
1177REAL-WORLD EXAMPLE 1275REAL-WORLD EXAMPLE
1178 Consider the Net::FCP module. It features (among others) the following 1276 Consider the Net::FCP module. It features (among others) the following
… …
1305 through AnyEvent. The benchmark creates a lot of timers (with a zero 1403 through AnyEvent. The benchmark creates a lot of timers (with a zero
1306 timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1404 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1307 which it is), lets them fire exactly once and destroys them again. 1405 which it is), lets them fire exactly once and destroys them again.
1308 1406
1309 Source code for this benchmark is found as eg/bench in the AnyEvent 1407 Source code for this benchmark is found as eg/bench in the AnyEvent
1310 distribution. 1408 distribution. It uses the AE interface, which makes a real difference
1409 for the EV and Perl backends only.
1311 1410
1312 Explanation of the columns 1411 Explanation of the columns
1313 *watcher* is the number of event watchers created/destroyed. Since 1412 *watcher* is the number of event watchers created/destroyed. Since
1314 different event models feature vastly different performances, each event 1413 different event models feature vastly different performances, each event
1315 loop was given a number of watchers so that overall runtime is 1414 loop was given a number of watchers so that overall runtime is
… …
1334 *destroy* is the time, in microseconds, that it takes to destroy a 1433 *destroy* is the time, in microseconds, that it takes to destroy a
1335 single watcher. 1434 single watcher.
1336 1435
1337 Results 1436 Results
1338 name watchers bytes create invoke destroy comment 1437 name watchers bytes create invoke destroy comment
1339 EV/EV 400000 224 0.47 0.35 0.27 EV native interface 1438 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
1340 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 1439 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
1341 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 1440 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
1342 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 1441 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
1343 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 1442 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
1344 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 1443 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
1345 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll 1444 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
1346 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll 1445 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
1347 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 1446 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
1348 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 1447 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
1349 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 1448 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
1350 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 1449 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
1351 1450
1352 Discussion 1451 Discussion
1353 The benchmark does *not* measure scalability of the event loop very 1452 The benchmark does *not* measure scalability of the event loop very
1354 well. For example, a select-based event loop (such as the pure perl one) 1453 well. For example, a select-based event loop (such as the pure perl one)
1355 can never compete with an event loop that uses epoll when the number of 1454 can never compete with an event loop that uses epoll when the number of
… …
1366 benchmark machine, handling an event takes roughly 1600 CPU cycles with 1465 benchmark machine, handling an event takes roughly 1600 CPU cycles with
1367 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 1466 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
1368 CPU cycles with POE. 1467 CPU cycles with POE.
1369 1468
1370 "EV" is the sole leader regarding speed and memory use, which are both 1469 "EV" is the sole leader regarding speed and memory use, which are both
1371 maximal/minimal, respectively. Even when going through AnyEvent, it uses 1470 maximal/minimal, respectively. When using the AE API there is zero
1471 overhead (when going through the AnyEvent API create is about 5-6 times
1472 slower, with other times being equal, so still uses far less memory than
1372 far less memory than any other event loop and is still faster than Event 1473 any other event loop and is still faster than Event natively).
1373 natively.
1374 1474
1375 The pure perl implementation is hit in a few sweet spots (both the 1475 The pure perl implementation is hit in a few sweet spots (both the
1376 constant timeout and the use of a single fd hit optimisations in the 1476 constant timeout and the use of a single fd hit optimisations in the
1377 perl interpreter and the backend itself). Nevertheless this shows that 1477 perl interpreter and the backend itself). Nevertheless this shows that
1378 it adds very little overhead in itself. Like any select-based backend 1478 it adds very little overhead in itself. Like any select-based backend
… …
1448 In this benchmark, we use 10000 socket pairs (20000 sockets), of which 1548 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
1449 100 (1%) are active. This mirrors the activity of large servers with 1549 100 (1%) are active. This mirrors the activity of large servers with
1450 many connections, most of which are idle at any one point in time. 1550 many connections, most of which are idle at any one point in time.
1451 1551
1452 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1552 Source code for this benchmark is found as eg/bench2 in the AnyEvent
1453 distribution. 1553 distribution. It uses the AE interface, which makes a real difference
1554 for the EV and Perl backends only.
1454 1555
1455 Explanation of the columns 1556 Explanation of the columns
1456 *sockets* is the number of sockets, and twice the number of "servers" 1557 *sockets* is the number of sockets, and twice the number of "servers"
1457 (as each server has a read and write socket end). 1558 (as each server has a read and write socket end).
1458 1559
… …
1464 forwarding it to another server. This includes deleting the old timeout 1565 forwarding it to another server. This includes deleting the old timeout
1465 and creating a new one that moves the timeout into the future. 1566 and creating a new one that moves the timeout into the future.
1466 1567
1467 Results 1568 Results
1468 name sockets create request 1569 name sockets create request
1469 EV 20000 69.01 11.16 1570 EV 20000 62.66 7.99
1470 Perl 20000 73.32 35.87 1571 Perl 20000 68.32 32.64
1471 IOAsync 20000 157.00 98.14 epoll 1572 IOAsync 20000 174.06 101.15 epoll
1472 IOAsync 20000 159.31 616.06 poll 1573 IOAsync 20000 174.67 610.84 poll
1473 Event 20000 212.62 257.32 1574 Event 20000 202.69 242.91
1474 Glib 20000 651.16 1896.30 1575 Glib 20000 557.01 1689.52
1475 POE 20000 349.67 12317.24 uses POE::Loop::Event 1576 POE 20000 341.54 12086.32 uses POE::Loop::Event
1476 1577
1477 Discussion 1578 Discussion
1478 This benchmark *does* measure scalability and overall performance of the 1579 This benchmark *does* measure scalability and overall performance of the
1479 particular event loop. 1580 particular event loop.
1480 1581
… …
1593 As you can see, the AnyEvent + EV combination even beats the 1694 As you can see, the AnyEvent + EV combination even beats the
1594 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl 1695 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1595 backend easily beats IO::Lambda and POE. 1696 backend easily beats IO::Lambda and POE.
1596 1697
1597 And even the 100% non-blocking version written using the high-level (and 1698 And even the 100% non-blocking version written using the high-level (and
1598 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a 1699 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda
1599 large margin, even though it does all of DNS, tcp-connect and socket I/O 1700 higher level ("unoptimised") abstractions by a large margin, even though
1600 in a non-blocking way. 1701 it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
1601 1702
1602 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and 1703 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1603 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are 1704 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1604 part of the IO::lambda distribution and were used without any changes. 1705 part of the IO::Lambda distribution and were used without any changes.
1605 1706
1606SIGNALS 1707SIGNALS
1607 AnyEvent currently installs handlers for these signals: 1708 AnyEvent currently installs handlers for these signals:
1608 1709
1609 SIGCHLD 1710 SIGCHLD
… …
1636 it's built-in modules) are required to use it. 1737 it's built-in modules) are required to use it.
1637 1738
1638 That does not mean that AnyEvent won't take advantage of some additional 1739 That does not mean that AnyEvent won't take advantage of some additional
1639 modules if they are installed. 1740 modules if they are installed.
1640 1741
1641 This section epxlains which additional modules will be used, and how 1742 This section explains which additional modules will be used, and how
1642 they affect AnyEvent's operetion. 1743 they affect AnyEvent's operation.
1643 1744
1644 Async::Interrupt 1745 Async::Interrupt
1645 This slightly arcane module is used to implement fast signal 1746 This slightly arcane module is used to implement fast signal
1646 handling: To my knowledge, there is no way to do completely 1747 handling: To my knowledge, there is no way to do completely
1647 race-free and quick signal handling in pure perl. To ensure that 1748 race-free and quick signal handling in pure perl. To ensure that
1648 signals still get delivered, AnyEvent will start an interval timer 1749 signals still get delivered, AnyEvent will start an interval timer
1649 to wake up perl (and catch the signals) with soemd elay (default is 1750 to wake up perl (and catch the signals) with some delay (default is
1650 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY). 1751 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1651 1752
1652 If this module is available, then it will be used to implement 1753 If this module is available, then it will be used to implement
1653 signal catching, which means that signals will not be delayed, and 1754 signal catching, which means that signals will not be delayed, and
1654 the event loop will not be interrupted regularly, which is more 1755 the event loop will not be interrupted regularly, which is more
1655 efficient (And good for battery life on laptops). 1756 efficient (and good for battery life on laptops).
1656 1757
1657 This affects not just the pure-perl event loop, but also other event 1758 This affects not just the pure-perl event loop, but also other event
1658 loops that have no signal handling on their own (e.g. Glib, Tk, Qt). 1759 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1760
1761 Some event loops (POE, Event, Event::Lib) offer signal watchers
1762 natively, and either employ their own workarounds (POE) or use
1763 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1764 Installing Async::Interrupt does nothing for those backends.
1659 1765
1660 EV This module isn't really "optional", as it is simply one of the 1766 EV This module isn't really "optional", as it is simply one of the
1661 backend event loops that AnyEvent can use. However, it is simply the 1767 backend event loops that AnyEvent can use. However, it is simply the
1662 best event loop available in terms of features, speed and stability: 1768 best event loop available in terms of features, speed and stability:
1663 It supports the AnyEvent API optimally, implements all the watcher 1769 It supports the AnyEvent API optimally, implements all the watcher
… …
1672 "AnyEvent::Util::guard". This speeds up guards considerably (and 1778 "AnyEvent::Util::guard". This speeds up guards considerably (and
1673 uses a lot less memory), but otherwise doesn't affect guard 1779 uses a lot less memory), but otherwise doesn't affect guard
1674 operation much. It is purely used for performance. 1780 operation much. It is purely used for performance.
1675 1781
1676 JSON and JSON::XS 1782 JSON and JSON::XS
1677 This module is required when you want to read or write JSON data via 1783 One of these modules is required when you want to read or write JSON
1678 AnyEvent::Handle. It is also written in pure-perl, but can take 1784 data via AnyEvent::Handle. It is also written in pure-perl, but can
1679 advantage of the ulta-high-speed JSON::XS module when it is 1785 take advantage of the ultra-high-speed JSON::XS module when it is
1680 installed. 1786 installed.
1681 1787
1682 In fact, AnyEvent::Handle will use JSON::XS by default if it is 1788 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1683 installed. 1789 installed.
1684 1790
… …
1697FORK 1803FORK
1698 Most event libraries are not fork-safe. The ones who are usually are 1804 Most event libraries are not fork-safe. The ones who are usually are
1699 because they rely on inefficient but fork-safe "select" or "poll" calls. 1805 because they rely on inefficient but fork-safe "select" or "poll" calls.
1700 Only EV is fully fork-aware. 1806 Only EV is fully fork-aware.
1701 1807
1808 This means that, in general, you cannot fork and do event processing in
1809 the child if a watcher was created before the fork (which in turn
1810 initialises the event library).
1811
1702 If you have to fork, you must either do so *before* creating your first 1812 If you have to fork, you must either do so *before* creating your first
1703 watcher OR you must not use AnyEvent at all in the child OR you must do 1813 watcher OR you must not use AnyEvent at all in the child OR you must do
1704 something completely out of the scope of AnyEvent. 1814 something completely out of the scope of AnyEvent.
1815
1816 The problem of doing event processing in the parent *and* the child is
1817 much more complicated: even for backends that *are* fork-aware or
1818 fork-safe, their behaviour is not usually what you want: fork clones all
1819 watchers, that means all timers, I/O watchers etc. are active in both
1820 parent and child, which is almost never what you want.
1705 1821
1706SECURITY CONSIDERATIONS 1822SECURITY CONSIDERATIONS
1707 AnyEvent can be forced to load any event model via 1823 AnyEvent can be forced to load any event model via
1708 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1824 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1709 to execute arbitrary code or directly gain access, it can easily be used 1825 to execute arbitrary code or directly gain access, it can easily be used
… …
1741 Event::Lib, Qt, POE. 1857 Event::Lib, Qt, POE.
1742 1858
1743 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1859 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1744 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1860 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1745 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, 1861 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1746 AnyEvent::Impl::IOAsync. 1862 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
1747 1863
1748 Non-blocking file handles, sockets, TCP clients and servers: 1864 Non-blocking file handles, sockets, TCP clients and servers:
1749 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 1865 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1750 1866
1751 Asynchronous DNS: AnyEvent::DNS. 1867 Asynchronous DNS: AnyEvent::DNS.

Diff Legend

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