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

Comparing AnyEvent/README (file contents):
Revision 1.47 by root, Mon Jul 20 22:39:57 2009 UTC vs.
Revision 1.59 by root, Tue Jan 5 10:45:25 2010 UTC

1NAME 1NAME
2 AnyEvent - events independent of event loop implementation 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
43SUPPORT 43SUPPORT
44 There is a mailinglist for discussing all things AnyEvent, and an IRC 44 There is a mailinglist for discussing all things AnyEvent, and an IRC
45 channel, too. 45 channel, too.
46 46
47 See the AnyEvent project page at the Schmorpforge Ta-Sa Software 47 See the AnyEvent project page at the Schmorpforge Ta-Sa Software
48 Respository, at <http://anyevent.schmorp.de>, for more info. 48 Repository, at <http://anyevent.schmorp.de>, for more info.
49 49
50WHY YOU SHOULD USE THIS MODULE (OR NOT) 50WHY YOU SHOULD USE THIS MODULE (OR NOT)
51 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
52 nowadays. So what is different about AnyEvent? 52 nowadays. So what is different about AnyEvent?
53 53
173 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,
174 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
175 declared. 175 declared.
176 176
177 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
178 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
179 the following mandatory key-value pairs as arguments: 185 the following mandatory key-value pairs as arguments:
180 186
181 "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
182 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
210 warn "read: $input\n"; 216 warn "read: $input\n";
211 undef $w; 217 undef $w;
212 }); 218 });
213 219
214 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
215 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
216 with the following mandatory arguments: 230 with the following mandatory arguments:
217 231
218 "after" specifies after how many seconds (fractional values are 232 "after" specifies after how many seconds (fractional values are
219 supported) the callback should be invoked. "cb" is the callback to 233 supported) the callback should be invoked. "cb" is the callback to
340 time, which might affect timers and time-outs. 354 time, which might affect timers and time-outs.
341 355
342 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
343 the event loop's idea of "current time". 357 the event loop's idea of "current time".
344 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
345 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.
346 368
347 SIGNAL WATCHERS 369 SIGNAL WATCHERS
370 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
371
348 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
349 *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
350 callback to be invoked whenever a signal occurs. 374 callback to be invoked whenever a signal occurs.
351 375
352 Although the callback might get passed parameters, their value and 376 Although the callback might get passed parameters, their value and
368 392
369 Example: exit on SIGINT 393 Example: exit on SIGINT
370 394
371 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 395 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
372 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
373 Signal Races, Delays and Workarounds 412 Signal Races, Delays and Workarounds
374 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 413 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
375 callbacks to signals in a generic way, which is a pity, as you cannot do 414 callbacks to signals in a generic way, which is a pity, as you cannot do
376 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.
377 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
378 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
379 10 seconds). This variable can be changed only before the first signal 418 in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable
380 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
381 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
382 saving. All these problems can be avoided by installing the optional 425 All these problems can be avoided by installing the optional
383 Async::Interrupt module. This will not work with inherently broken event 426 Async::Interrupt module, which works with most event loops. It will not
384 loops such as Event or Event::Lib (and not with POE currently, as POE 427 work with inherently broken event loops such as Event or Event::Lib (and
385 does it's own workaround with one-second latency). With those, you just 428 not with POE currently, as POE does it's own workaround with one-second
386 have to suffer the delays. 429 latency). For those, you just have to suffer the delays.
387 430
388 CHILD PROCESS WATCHERS 431 CHILD PROCESS WATCHERS
432 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
433
389 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.
390 435
391 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,
392 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).
393 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
394 on any trace events (stopped/continued). 439 and an exit status is available, not on any trace events
440 (stopped/continued).
395 441
396 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
397 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
398 callback arguments. 444 callback arguments.
399 445
438 484
439 # do something else, then wait for process exit 485 # do something else, then wait for process exit
440 $done->recv; 486 $done->recv;
441 487
442 IDLE WATCHERS 488 IDLE WATCHERS
443 Sometimes there is a need to do something, but it is not so important to 489 $w = AnyEvent->idle (cb => <callback>);
444 do it instantly, but only when there is nothing better to do. This
445 "nothing better to do" is usually defined to be "no other events need
446 attention by the event loop".
447 490
448 Idle watchers ideally get invoked when the event loop has nothing better 491 Repeatedly invoke the callback after the process becomes idle, until
449 to do, just before it would block the process to wait for new events. 492 either the watcher is destroyed or new events have been detected.
450 Instead of blocking, the idle watcher is invoked.
451 493
452 Most event loops unfortunately do not really support idle watchers (only 494 Idle watchers are useful when there is a need to do something, but it is
495 not so important (or wise) to do it instantly. The callback will be
496 invoked only when there is "nothing better to do", which is usually
497 defined as "all outstanding events have been handled and no new events
498 have been detected". That means that idle watchers ideally get invoked
499 when the event loop has just polled for new events but none have been
500 detected. Instead of blocking to wait for more events, the idle watchers
501 will be invoked.
502
503 Unfortunately, most event loops do not really support idle watchers
453 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent 504 (only EV, Event and Glib do it in a usable fashion) - for the rest,
454 will simply call the callback "from time to time". 505 AnyEvent will simply call the callback "from time to time".
455 506
456 Example: read lines from STDIN, but only process them when the program 507 Example: read lines from STDIN, but only process them when the program
457 is otherwise idle: 508 is otherwise idle:
458 509
459 my @lines; # read data 510 my @lines; # read data
472 } 523 }
473 }); 524 });
474 }); 525 });
475 526
476 CONDITION VARIABLES 527 CONDITION VARIABLES
528 $cv = AnyEvent->condvar;
529
530 $cv->send (<list>);
531 my @res = $cv->recv;
532
477 If you are familiar with some event loops you will know that all of them 533 If you are familiar with some event loops you will know that all of them
478 require you to run some blocking "loop", "run" or similar function that 534 require you to run some blocking "loop", "run" or similar function that
479 will actively watch for new events and call your callbacks. 535 will actively watch for new events and call your callbacks.
480 536
481 AnyEvent is slightly different: it expects somebody else to run the 537 AnyEvent is slightly different: it expects somebody else to run the
546 after => 1, 602 after => 1,
547 cb => sub { $result_ready->send }, 603 cb => sub { $result_ready->send },
548 ); 604 );
549 605
550 # this "blocks" (while handling events) till the callback 606 # this "blocks" (while handling events) till the callback
551 # calls -<send 607 # calls ->send
552 $result_ready->recv; 608 $result_ready->recv;
553 609
554 Example: wait for a timer, but take advantage of the fact that condition 610 Example: wait for a timer, but take advantage of the fact that condition
555 variables are also callable directly. 611 variables are also callable directly.
556 612
613 into one. For example, a function that pings many hosts in parallel 669 into one. For example, a function that pings many hosts in parallel
614 might want to use a condition variable for the whole process. 670 might want to use a condition variable for the whole process.
615 671
616 Every call to "->begin" will increment a counter, and every call to 672 Every call to "->begin" will increment a counter, and every call to
617 "->end" will decrement it. If the counter reaches 0 in "->end", the 673 "->end" will decrement it. If the counter reaches 0 in "->end", the
618 (last) callback passed to "begin" will be executed. That callback is 674 (last) callback passed to "begin" will be executed, passing the
619 *supposed* to call "->send", but that is not required. If no 675 condvar as first argument. That callback is *supposed* to call
676 "->send", but that is not required. If no group callback was set,
620 callback was set, "send" will be called without any arguments. 677 "send" will be called without any arguments.
621 678
622 You can think of "$cv->send" giving you an OR condition (one call 679 You can think of "$cv->send" giving you an OR condition (one call
623 sends), while "$cv->begin" and "$cv->end" giving you an AND 680 sends), while "$cv->begin" and "$cv->end" giving you an AND
624 condition (all "begin" calls must be "end"'ed before the condvar 681 condition (all "begin" calls must be "end"'ed before the condvar
625 sends). 682 sends).
653 that are begung can potentially be zero: 710 that are begung can potentially be zero:
654 711
655 my $cv = AnyEvent->condvar; 712 my $cv = AnyEvent->condvar;
656 713
657 my %result; 714 my %result;
658 $cv->begin (sub { $cv->send (\%result) }); 715 $cv->begin (sub { shift->send (\%result) });
659 716
660 for my $host (@list_of_hosts) { 717 for my $host (@list_of_hosts) {
661 $cv->begin; 718 $cv->begin;
662 ping_host_then_call_callback $host, sub { 719 ping_host_then_call_callback $host, sub {
663 $result{$host} = ...; 720 $result{$host} = ...;
730 787
731 $cb = $cv->cb ($cb->($cv)) 788 $cb = $cv->cb ($cb->($cv))
732 This is a mutator function that returns the callback set and 789 This is a mutator function that returns the callback set and
733 optionally replaces it before doing so. 790 optionally replaces it before doing so.
734 791
735 The callback will be called when the condition becomes "true", i.e. 792 The callback will be called when the condition becomes (or already
736 when "send" or "croak" are called, with the only argument being the 793 was) "true", i.e. when "send" or "croak" are called (or were
737 condition variable itself. Calling "recv" inside the callback or at 794 called), with the only argument being the condition variable itself.
795 Calling "recv" inside the callback or at any later time is
738 any later time is guaranteed not to block. 796 guaranteed not to block.
739 797
740SUPPORTED EVENT LOOPS/BACKENDS 798SUPPORTED EVENT LOOPS/BACKENDS
741 The available backend classes are (every class has its own manpage): 799 The available backend classes are (every class has its own manpage):
742 800
743 Backends that are autoprobed when no other event loop can be found. 801 Backends that are autoprobed when no other event loop can be found.
744 EV is the preferred backend when no other event loop seems to be in 802 EV is the preferred backend when no other event loop seems to be in
745 use. If EV is not installed, then AnyEvent will try Event, and, 803 use. If EV is not installed, then AnyEvent will fall back to its own
746 failing that, will fall back to its own pure-perl implementation, 804 pure-perl implementation, which is available everywhere as it comes
747 which is available everywhere as it comes with AnyEvent itself. 805 with AnyEvent itself.
748 806
749 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 807 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
750 AnyEvent::Impl::Event based on Event, very stable, few glitches.
751 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 808 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
752 809
753 Backends that are transparently being picked up when they are used. 810 Backends that are transparently being picked up when they are used.
754 These will be used when they are currently loaded when the first 811 These will be used when they are currently loaded when the first
755 watcher is created, in which case it is assumed that the application 812 watcher is created, in which case it is assumed that the application
756 is using them. This means that AnyEvent will automatically pick the 813 is using them. This means that AnyEvent will automatically pick the
757 right backend when the main program loads an event module before 814 right backend when the main program loads an event module before
758 anything starts to create watchers. Nothing special needs to be done 815 anything starts to create watchers. Nothing special needs to be done
759 by the main program. 816 by the main program.
760 817
818 AnyEvent::Impl::Event based on Event, very stable, few glitches.
761 AnyEvent::Impl::Glib based on Glib, slow but very stable. 819 AnyEvent::Impl::Glib based on Glib, slow but very stable.
762 AnyEvent::Impl::Tk based on Tk, very broken. 820 AnyEvent::Impl::Tk based on Tk, very broken.
763 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 821 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
764 AnyEvent::Impl::POE based on POE, very slow, some limitations. 822 AnyEvent::Impl::POE based on POE, very slow, some limitations.
823 AnyEvent::Impl::Irssi used when running within irssi.
765 824
766 Backends with special needs. 825 Backends with special needs.
767 Qt requires the Qt::Application to be instantiated first, but will 826 Qt requires the Qt::Application to be instantiated first, but will
768 otherwise be picked up automatically. As long as the main program 827 otherwise be picked up automatically. As long as the main program
769 instantiates the application before any AnyEvent watchers are 828 instantiates the application before any AnyEvent watchers are
834 creates and installs the global IO::AIO watcher in a "post_detect" 893 creates and installs the global IO::AIO watcher in a "post_detect"
835 block to avoid autodetecting the event module at load time. 894 block to avoid autodetecting the event module at load time.
836 895
837 If called in scalar or list context, then it creates and returns an 896 If called in scalar or list context, then it creates and returns an
838 object that automatically removes the callback again when it is 897 object that automatically removes the callback again when it is
898 destroyed (or "undef" when the hook was immediately executed). See
839 destroyed. See Coro::BDB for a case where this is useful. 899 AnyEvent::AIO for a case where this is useful.
900
901 Example: Create a watcher for the IO::AIO module and store it in
902 $WATCHER. Only do so after the event loop is initialised, though.
903
904 our WATCHER;
905
906 my $guard = AnyEvent::post_detect {
907 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
908 };
909
910 # the ||= is important in case post_detect immediately runs the block,
911 # as to not clobber the newly-created watcher. assigning both watcher and
912 # post_detect guard to the same variable has the advantage of users being
913 # able to just C<undef $WATCHER> if the watcher causes them grief.
914
915 $WATCHER ||= $guard;
840 916
841 @AnyEvent::post_detect 917 @AnyEvent::post_detect
842 If there are any code references in this array (you can "push" to it 918 If there are any code references in this array (you can "push" to it
843 before or after loading AnyEvent), then they will called directly 919 before or after loading AnyEvent), then they will called directly
844 after the event loop has been chosen. 920 after the event loop has been chosen.
846 You should check $AnyEvent::MODEL before adding to this array, 922 You should check $AnyEvent::MODEL before adding to this array,
847 though: if it is defined then the event loop has already been 923 though: if it is defined then the event loop has already been
848 detected, and the array will be ignored. 924 detected, and the array will be ignored.
849 925
850 Best use "AnyEvent::post_detect { BLOCK }" when your application 926 Best use "AnyEvent::post_detect { BLOCK }" when your application
851 allows it,as it takes care of these details. 927 allows it, as it takes care of these details.
852 928
853 This variable is mainly useful for modules that can do something 929 This variable is mainly useful for modules that can do something
854 useful when AnyEvent is used and thus want to know when it is 930 useful when AnyEvent is used and thus want to know when it is
855 initialised, but do not need to even load it by default. This array 931 initialised, but do not need to even load it by default. This array
856 provides the means to hook into AnyEvent passively, without loading 932 provides the means to hook into AnyEvent passively, without loading
857 it. 933 it.
934
935 Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
936 together, you could put this into Coro (this is the actual code used
937 by Coro to accomplish this):
938
939 if (defined $AnyEvent::MODEL) {
940 # AnyEvent already initialised, so load Coro::AnyEvent
941 require Coro::AnyEvent;
942 } else {
943 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
944 # as soon as it is
945 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
946 }
858 947
859WHAT TO DO IN A MODULE 948WHAT TO DO IN A MODULE
860 As a module author, you should "use AnyEvent" and call AnyEvent methods 949 As a module author, you should "use AnyEvent" and call AnyEvent methods
861 freely, but you should not load a specific event module or rely on it. 950 freely, but you should not load a specific event module or rely on it.
862 951
983 Event::ExecFlow 1072 Event::ExecFlow
984 High level API for event-based execution flow control. 1073 High level API for event-based execution flow control.
985 1074
986 Coro 1075 Coro
987 Has special support for AnyEvent via Coro::AnyEvent. 1076 Has special support for AnyEvent via Coro::AnyEvent.
1077
1078SIMPLIFIED AE API
1079 Starting with version 5.0, AnyEvent officially supports a second, much
1080 simpler, API that is designed to reduce the calling, typing and memory
1081 overhead.
1082
1083 See the AE manpage for details.
988 1084
989ERROR AND EXCEPTION HANDLING 1085ERROR AND EXCEPTION HANDLING
990 In general, AnyEvent does not do any error handling - it relies on the 1086 In general, AnyEvent does not do any error handling - it relies on the
991 caller to do that if required. The AnyEvent::Strict module (see also the 1087 caller to do that if required. The AnyEvent::Strict module (see also the
992 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 1088 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
1171 warn "read: $input\n"; # output what has been read 1267 warn "read: $input\n"; # output what has been read
1172 $cv->send if $input =~ /^q/i; # quit program if /^q/i 1268 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1173 }, 1269 },
1174 ); 1270 );
1175 1271
1176 my $time_watcher; # can only be used once
1177
1178 sub new_timer {
1179 $timer = AnyEvent->timer (after => 1, cb => sub { 1272 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
1180 warn "timeout\n"; # print 'timeout' about every second 1273 warn "timeout\n"; # print 'timeout' at most every second
1181 &new_timer; # and restart the time
1182 });
1183 } 1274 });
1184
1185 new_timer; # create first timer
1186 1275
1187 $cv->recv; # wait until user enters /^q/i 1276 $cv->recv; # wait until user enters /^q/i
1188 1277
1189REAL-WORLD EXAMPLE 1278REAL-WORLD EXAMPLE
1190 Consider the Net::FCP module. It features (among others) the following 1279 Consider the Net::FCP module. It features (among others) the following
1317 through AnyEvent. The benchmark creates a lot of timers (with a zero 1406 through AnyEvent. The benchmark creates a lot of timers (with a zero
1318 timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1407 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1319 which it is), lets them fire exactly once and destroys them again. 1408 which it is), lets them fire exactly once and destroys them again.
1320 1409
1321 Source code for this benchmark is found as eg/bench in the AnyEvent 1410 Source code for this benchmark is found as eg/bench in the AnyEvent
1322 distribution. 1411 distribution. It uses the AE interface, which makes a real difference
1412 for the EV and Perl backends only.
1323 1413
1324 Explanation of the columns 1414 Explanation of the columns
1325 *watcher* is the number of event watchers created/destroyed. Since 1415 *watcher* is the number of event watchers created/destroyed. Since
1326 different event models feature vastly different performances, each event 1416 different event models feature vastly different performances, each event
1327 loop was given a number of watchers so that overall runtime is 1417 loop was given a number of watchers so that overall runtime is
1346 *destroy* is the time, in microseconds, that it takes to destroy a 1436 *destroy* is the time, in microseconds, that it takes to destroy a
1347 single watcher. 1437 single watcher.
1348 1438
1349 Results 1439 Results
1350 name watchers bytes create invoke destroy comment 1440 name watchers bytes create invoke destroy comment
1351 EV/EV 400000 224 0.47 0.35 0.27 EV native interface 1441 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
1352 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 1442 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
1353 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 1443 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
1354 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 1444 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
1355 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 1445 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
1356 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 1446 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
1357 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll 1447 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
1358 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll 1448 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
1359 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 1449 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
1360 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 1450 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
1361 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 1451 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
1362 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 1452 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
1363 1453
1364 Discussion 1454 Discussion
1365 The benchmark does *not* measure scalability of the event loop very 1455 The benchmark does *not* measure scalability of the event loop very
1366 well. For example, a select-based event loop (such as the pure perl one) 1456 well. For example, a select-based event loop (such as the pure perl one)
1367 can never compete with an event loop that uses epoll when the number of 1457 can never compete with an event loop that uses epoll when the number of
1378 benchmark machine, handling an event takes roughly 1600 CPU cycles with 1468 benchmark machine, handling an event takes roughly 1600 CPU cycles with
1379 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 1469 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
1380 CPU cycles with POE. 1470 CPU cycles with POE.
1381 1471
1382 "EV" is the sole leader regarding speed and memory use, which are both 1472 "EV" is the sole leader regarding speed and memory use, which are both
1383 maximal/minimal, respectively. Even when going through AnyEvent, it uses 1473 maximal/minimal, respectively. When using the AE API there is zero
1474 overhead (when going through the AnyEvent API create is about 5-6 times
1475 slower, with other times being equal, so still uses far less memory than
1384 far less memory than any other event loop and is still faster than Event 1476 any other event loop and is still faster than Event natively).
1385 natively.
1386 1477
1387 The pure perl implementation is hit in a few sweet spots (both the 1478 The pure perl implementation is hit in a few sweet spots (both the
1388 constant timeout and the use of a single fd hit optimisations in the 1479 constant timeout and the use of a single fd hit optimisations in the
1389 perl interpreter and the backend itself). Nevertheless this shows that 1480 perl interpreter and the backend itself). Nevertheless this shows that
1390 it adds very little overhead in itself. Like any select-based backend 1481 it adds very little overhead in itself. Like any select-based backend
1460 In this benchmark, we use 10000 socket pairs (20000 sockets), of which 1551 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
1461 100 (1%) are active. This mirrors the activity of large servers with 1552 100 (1%) are active. This mirrors the activity of large servers with
1462 many connections, most of which are idle at any one point in time. 1553 many connections, most of which are idle at any one point in time.
1463 1554
1464 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1555 Source code for this benchmark is found as eg/bench2 in the AnyEvent
1465 distribution. 1556 distribution. It uses the AE interface, which makes a real difference
1557 for the EV and Perl backends only.
1466 1558
1467 Explanation of the columns 1559 Explanation of the columns
1468 *sockets* is the number of sockets, and twice the number of "servers" 1560 *sockets* is the number of sockets, and twice the number of "servers"
1469 (as each server has a read and write socket end). 1561 (as each server has a read and write socket end).
1470 1562
1476 forwarding it to another server. This includes deleting the old timeout 1568 forwarding it to another server. This includes deleting the old timeout
1477 and creating a new one that moves the timeout into the future. 1569 and creating a new one that moves the timeout into the future.
1478 1570
1479 Results 1571 Results
1480 name sockets create request 1572 name sockets create request
1481 EV 20000 69.01 11.16 1573 EV 20000 62.66 7.99
1482 Perl 20000 73.32 35.87 1574 Perl 20000 68.32 32.64
1483 IOAsync 20000 157.00 98.14 epoll 1575 IOAsync 20000 174.06 101.15 epoll
1484 IOAsync 20000 159.31 616.06 poll 1576 IOAsync 20000 174.67 610.84 poll
1485 Event 20000 212.62 257.32 1577 Event 20000 202.69 242.91
1486 Glib 20000 651.16 1896.30 1578 Glib 20000 557.01 1689.52
1487 POE 20000 349.67 12317.24 uses POE::Loop::Event 1579 POE 20000 341.54 12086.32 uses POE::Loop::Event
1488 1580
1489 Discussion 1581 Discussion
1490 This benchmark *does* measure scalability and overall performance of the 1582 This benchmark *does* measure scalability and overall performance of the
1491 particular event loop. 1583 particular event loop.
1492 1584
1605 As you can see, the AnyEvent + EV combination even beats the 1697 As you can see, the AnyEvent + EV combination even beats the
1606 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl 1698 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1607 backend easily beats IO::Lambda and POE. 1699 backend easily beats IO::Lambda and POE.
1608 1700
1609 And even the 100% non-blocking version written using the high-level (and 1701 And even the 100% non-blocking version written using the high-level (and
1610 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a 1702 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda
1611 large margin, even though it does all of DNS, tcp-connect and socket I/O 1703 higher level ("unoptimised") abstractions by a large margin, even though
1612 in a non-blocking way. 1704 it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
1613 1705
1614 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and 1706 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1615 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are 1707 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1616 part of the IO::lambda distribution and were used without any changes. 1708 part of the IO::Lambda distribution and were used without any changes.
1617 1709
1618SIGNALS 1710SIGNALS
1619 AnyEvent currently installs handlers for these signals: 1711 AnyEvent currently installs handlers for these signals:
1620 1712
1621 SIGCHLD 1713 SIGCHLD
1648 it's built-in modules) are required to use it. 1740 it's built-in modules) are required to use it.
1649 1741
1650 That does not mean that AnyEvent won't take advantage of some additional 1742 That does not mean that AnyEvent won't take advantage of some additional
1651 modules if they are installed. 1743 modules if they are installed.
1652 1744
1653 This section epxlains which additional modules will be used, and how 1745 This section explains which additional modules will be used, and how
1654 they affect AnyEvent's operetion. 1746 they affect AnyEvent's operation.
1655 1747
1656 Async::Interrupt 1748 Async::Interrupt
1657 This slightly arcane module is used to implement fast signal 1749 This slightly arcane module is used to implement fast signal
1658 handling: To my knowledge, there is no way to do completely 1750 handling: To my knowledge, there is no way to do completely
1659 race-free and quick signal handling in pure perl. To ensure that 1751 race-free and quick signal handling in pure perl. To ensure that
1662 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY). 1754 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1663 1755
1664 If this module is available, then it will be used to implement 1756 If this module is available, then it will be used to implement
1665 signal catching, which means that signals will not be delayed, and 1757 signal catching, which means that signals will not be delayed, and
1666 the event loop will not be interrupted regularly, which is more 1758 the event loop will not be interrupted regularly, which is more
1667 efficient (And good for battery life on laptops). 1759 efficient (and good for battery life on laptops).
1668 1760
1669 This affects not just the pure-perl event loop, but also other event 1761 This affects not just the pure-perl event loop, but also other event
1670 loops that have no signal handling on their own (e.g. Glib, Tk, Qt). 1762 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1671 1763
1672 Some event loops (POE, Event, Event::Lib) offer signal watchers 1764 Some event loops (POE, Event, Event::Lib) offer signal watchers
1689 "AnyEvent::Util::guard". This speeds up guards considerably (and 1781 "AnyEvent::Util::guard". This speeds up guards considerably (and
1690 uses a lot less memory), but otherwise doesn't affect guard 1782 uses a lot less memory), but otherwise doesn't affect guard
1691 operation much. It is purely used for performance. 1783 operation much. It is purely used for performance.
1692 1784
1693 JSON and JSON::XS 1785 JSON and JSON::XS
1694 This module is required when you want to read or write JSON data via 1786 One of these modules is required when you want to read or write JSON
1695 AnyEvent::Handle. It is also written in pure-perl, but can take 1787 data via AnyEvent::Handle. It is also written in pure-perl, but can
1696 advantage of the ultra-high-speed JSON::XS module when it is 1788 take advantage of the ultra-high-speed JSON::XS module when it is
1697 installed. 1789 installed.
1698 1790
1699 In fact, AnyEvent::Handle will use JSON::XS by default if it is 1791 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1700 installed. 1792 installed.
1701 1793
1711 additionally use it to try to use a monotonic clock for timing 1803 additionally use it to try to use a monotonic clock for timing
1712 stability. 1804 stability.
1713 1805
1714FORK 1806FORK
1715 Most event libraries are not fork-safe. The ones who are usually are 1807 Most event libraries are not fork-safe. The ones who are usually are
1716 because they rely on inefficient but fork-safe "select" or "poll" calls. 1808 because they rely on inefficient but fork-safe "select" or "poll" calls
1717 Only EV is fully fork-aware. 1809 - higher performance APIs such as BSD's kqueue or the dreaded Linux
1810 epoll are usually badly thought-out hacks that are incompatible with
1811 fork in one way or another. Only EV is fully fork-aware and ensures that
1812 you continue event-processing in both parent and child (or both, if you
1813 know what you are doing).
1814
1815 This means that, in general, you cannot fork and do event processing in
1816 the child if the event library was initialised before the fork (which
1817 usually happens when the first AnyEvent watcher is created, or the
1818 library is loaded).
1718 1819
1719 If you have to fork, you must either do so *before* creating your first 1820 If you have to fork, you must either do so *before* creating your first
1720 watcher OR you must not use AnyEvent at all in the child OR you must do 1821 watcher OR you must not use AnyEvent at all in the child OR you must do
1721 something completely out of the scope of AnyEvent. 1822 something completely out of the scope of AnyEvent.
1823
1824 The problem of doing event processing in the parent *and* the child is
1825 much more complicated: even for backends that *are* fork-aware or
1826 fork-safe, their behaviour is not usually what you want: fork clones all
1827 watchers, that means all timers, I/O watchers etc. are active in both
1828 parent and child, which is almost never what you want. USing "exec" to
1829 start worker children from some kind of manage rprocess is usually
1830 preferred, because it is much easier and cleaner, at the expense of
1831 having to have another binary.
1722 1832
1723SECURITY CONSIDERATIONS 1833SECURITY CONSIDERATIONS
1724 AnyEvent can be forced to load any event model via 1834 AnyEvent can be forced to load any event model via
1725 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1835 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1726 to execute arbitrary code or directly gain access, it can easily be used 1836 to execute arbitrary code or directly gain access, it can easily be used
1758 Event::Lib, Qt, POE. 1868 Event::Lib, Qt, POE.
1759 1869
1760 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1870 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1761 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1871 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1762 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, 1872 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1763 AnyEvent::Impl::IOAsync. 1873 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
1764 1874
1765 Non-blocking file handles, sockets, TCP clients and servers: 1875 Non-blocking file handles, sockets, TCP clients and servers:
1766 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 1876 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1767 1877
1768 Asynchronous DNS: AnyEvent::DNS. 1878 Asynchronous DNS: AnyEvent::DNS.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines