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

Comparing AnyEvent/README (file contents):
Revision 1.50 by root, Sat Aug 1 09:14:54 2009 UTC vs.
Revision 1.55 by root, Mon Sep 14 05:05:09 2009 UTC

576 after => 1, 576 after => 1,
577 cb => sub { $result_ready->send }, 577 cb => sub { $result_ready->send },
578 ); 578 );
579 579
580 # this "blocks" (while handling events) till the callback 580 # this "blocks" (while handling events) till the callback
581 # calls -<send 581 # calls ->send
582 $result_ready->recv; 582 $result_ready->recv;
583 583
584 Example: wait for a timer, but take advantage of the fact that condition 584 Example: wait for a timer, but take advantage of the fact that condition
585 variables are also callable directly. 585 variables are also callable directly.
586 586
643 into one. For example, a function that pings many hosts in parallel 643 into one. For example, a function that pings many hosts in parallel
644 might want to use a condition variable for the whole process. 644 might want to use a condition variable for the whole process.
645 645
646 Every call to "->begin" will increment a counter, and every call to 646 Every call to "->begin" will increment a counter, and every call to
647 "->end" will decrement it. If the counter reaches 0 in "->end", the 647 "->end" will decrement it. If the counter reaches 0 in "->end", the
648 (last) callback passed to "begin" will be executed. That callback is 648 (last) callback passed to "begin" will be executed, passing the
649 *supposed* to call "->send", but that is not required. If no 649 condvar as first argument. That callback is *supposed* to call
650 "->send", but that is not required. If no group callback was set,
650 callback was set, "send" will be called without any arguments. 651 "send" will be called without any arguments.
651 652
652 You can think of "$cv->send" giving you an OR condition (one call 653 You can think of "$cv->send" giving you an OR condition (one call
653 sends), while "$cv->begin" and "$cv->end" giving you an AND 654 sends), while "$cv->begin" and "$cv->end" giving you an AND
654 condition (all "begin" calls must be "end"'ed before the condvar 655 condition (all "begin" calls must be "end"'ed before the condvar
655 sends). 656 sends).
683 that are begung can potentially be zero: 684 that are begung can potentially be zero:
684 685
685 my $cv = AnyEvent->condvar; 686 my $cv = AnyEvent->condvar;
686 687
687 my %result; 688 my %result;
688 $cv->begin (sub { $cv->send (\%result) }); 689 $cv->begin (sub { shift->send (\%result) });
689 690
690 for my $host (@list_of_hosts) { 691 for my $host (@list_of_hosts) {
691 $cv->begin; 692 $cv->begin;
692 ping_host_then_call_callback $host, sub { 693 ping_host_then_call_callback $host, sub {
693 $result{$host} = ...; 694 $result{$host} = ...;
771SUPPORTED EVENT LOOPS/BACKENDS 772SUPPORTED EVENT LOOPS/BACKENDS
772 The available backend classes are (every class has its own manpage): 773 The available backend classes are (every class has its own manpage):
773 774
774 Backends that are autoprobed when no other event loop can be found. 775 Backends that are autoprobed when no other event loop can be found.
775 EV is the preferred backend when no other event loop seems to be in 776 EV is the preferred backend when no other event loop seems to be in
776 use. If EV is not installed, then AnyEvent will try Event, and, 777 use. If EV is not installed, then AnyEvent will fall back to its own
777 failing that, will fall back to its own pure-perl implementation, 778 pure-perl implementation, which is available everywhere as it comes
778 which is available everywhere as it comes with AnyEvent itself. 779 with AnyEvent itself.
779 780
780 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 781 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
781 AnyEvent::Impl::Event based on Event, very stable, few glitches.
782 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 782 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
783 783
784 Backends that are transparently being picked up when they are used. 784 Backends that are transparently being picked up when they are used.
785 These will be used when they are currently loaded when the first 785 These will be used when they are currently loaded when the first
786 watcher is created, in which case it is assumed that the application 786 watcher is created, in which case it is assumed that the application
787 is using them. This means that AnyEvent will automatically pick the 787 is using them. This means that AnyEvent will automatically pick the
788 right backend when the main program loads an event module before 788 right backend when the main program loads an event module before
789 anything starts to create watchers. Nothing special needs to be done 789 anything starts to create watchers. Nothing special needs to be done
790 by the main program. 790 by the main program.
791 791
792 AnyEvent::Impl::Event based on Event, very stable, few glitches.
792 AnyEvent::Impl::Glib based on Glib, slow but very stable. 793 AnyEvent::Impl::Glib based on Glib, slow but very stable.
793 AnyEvent::Impl::Tk based on Tk, very broken. 794 AnyEvent::Impl::Tk based on Tk, very broken.
794 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 795 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
795 AnyEvent::Impl::POE based on POE, very slow, some limitations. 796 AnyEvent::Impl::POE based on POE, very slow, some limitations.
796 AnyEvent::Impl::Irssi used when running within irssi. 797 AnyEvent::Impl::Irssi used when running within irssi.
1032 Event::ExecFlow 1033 Event::ExecFlow
1033 High level API for event-based execution flow control. 1034 High level API for event-based execution flow control.
1034 1035
1035 Coro 1036 Coro
1036 Has special support for AnyEvent via Coro::AnyEvent. 1037 Has special support for AnyEvent via Coro::AnyEvent.
1038
1039SIMPLIFIED AE API
1040 Starting with version 5.0, AnyEvent officially supports a second, much
1041 simpler, API that is designed to reduce the calling, typing and memory
1042 overhead.
1043
1044 See the AE manpage for details.
1037 1045
1038ERROR AND EXCEPTION HANDLING 1046ERROR AND EXCEPTION HANDLING
1039 In general, AnyEvent does not do any error handling - it relies on the 1047 In general, AnyEvent does not do any error handling - it relies on the
1040 caller to do that if required. The AnyEvent::Strict module (see also the 1048 caller to do that if required. The AnyEvent::Strict module (see also the
1041 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 1049 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
1220 warn "read: $input\n"; # output what has been read 1228 warn "read: $input\n"; # output what has been read
1221 $cv->send if $input =~ /^q/i; # quit program if /^q/i 1229 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1222 }, 1230 },
1223 ); 1231 );
1224 1232
1225 my $time_watcher; # can only be used once
1226
1227 sub new_timer {
1228 $timer = AnyEvent->timer (after => 1, cb => sub { 1233 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
1229 warn "timeout\n"; # print 'timeout' about every second 1234 warn "timeout\n"; # print 'timeout' at most every second
1230 &new_timer; # and restart the time
1231 });
1232 } 1235 });
1233
1234 new_timer; # create first timer
1235 1236
1236 $cv->recv; # wait until user enters /^q/i 1237 $cv->recv; # wait until user enters /^q/i
1237 1238
1238REAL-WORLD EXAMPLE 1239REAL-WORLD EXAMPLE
1239 Consider the Net::FCP module. It features (among others) the following 1240 Consider the Net::FCP module. It features (among others) the following
1366 through AnyEvent. The benchmark creates a lot of timers (with a zero 1367 through AnyEvent. The benchmark creates a lot of timers (with a zero
1367 timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1368 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1368 which it is), lets them fire exactly once and destroys them again. 1369 which it is), lets them fire exactly once and destroys them again.
1369 1370
1370 Source code for this benchmark is found as eg/bench in the AnyEvent 1371 Source code for this benchmark is found as eg/bench in the AnyEvent
1371 distribution. 1372 distribution. It uses the AE interface, which makes a real difference
1373 for the EV and Perl backends only.
1372 1374
1373 Explanation of the columns 1375 Explanation of the columns
1374 *watcher* is the number of event watchers created/destroyed. Since 1376 *watcher* is the number of event watchers created/destroyed. Since
1375 different event models feature vastly different performances, each event 1377 different event models feature vastly different performances, each event
1376 loop was given a number of watchers so that overall runtime is 1378 loop was given a number of watchers so that overall runtime is
1395 *destroy* is the time, in microseconds, that it takes to destroy a 1397 *destroy* is the time, in microseconds, that it takes to destroy a
1396 single watcher. 1398 single watcher.
1397 1399
1398 Results 1400 Results
1399 name watchers bytes create invoke destroy comment 1401 name watchers bytes create invoke destroy comment
1400 EV/EV 400000 224 0.47 0.35 0.27 EV native interface 1402 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
1401 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 1403 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
1402 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 1404 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
1403 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 1405 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
1404 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 1406 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
1405 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 1407 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
1406 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll 1408 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
1407 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll 1409 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
1408 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 1410 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
1409 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 1411 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
1410 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 1412 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
1411 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 1413 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
1412 1414
1413 Discussion 1415 Discussion
1414 The benchmark does *not* measure scalability of the event loop very 1416 The benchmark does *not* measure scalability of the event loop very
1415 well. For example, a select-based event loop (such as the pure perl one) 1417 well. For example, a select-based event loop (such as the pure perl one)
1416 can never compete with an event loop that uses epoll when the number of 1418 can never compete with an event loop that uses epoll when the number of
1427 benchmark machine, handling an event takes roughly 1600 CPU cycles with 1429 benchmark machine, handling an event takes roughly 1600 CPU cycles with
1428 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 1430 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
1429 CPU cycles with POE. 1431 CPU cycles with POE.
1430 1432
1431 "EV" is the sole leader regarding speed and memory use, which are both 1433 "EV" is the sole leader regarding speed and memory use, which are both
1432 maximal/minimal, respectively. Even when going through AnyEvent, it uses 1434 maximal/minimal, respectively. When using the AE API there is zero
1435 overhead (when going through the AnyEvent API create is about 5-6 times
1436 slower, with other times being equal, so still uses far less memory than
1433 far less memory than any other event loop and is still faster than Event 1437 any other event loop and is still faster than Event natively).
1434 natively.
1435 1438
1436 The pure perl implementation is hit in a few sweet spots (both the 1439 The pure perl implementation is hit in a few sweet spots (both the
1437 constant timeout and the use of a single fd hit optimisations in the 1440 constant timeout and the use of a single fd hit optimisations in the
1438 perl interpreter and the backend itself). Nevertheless this shows that 1441 perl interpreter and the backend itself). Nevertheless this shows that
1439 it adds very little overhead in itself. Like any select-based backend 1442 it adds very little overhead in itself. Like any select-based backend
1509 In this benchmark, we use 10000 socket pairs (20000 sockets), of which 1512 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
1510 100 (1%) are active. This mirrors the activity of large servers with 1513 100 (1%) are active. This mirrors the activity of large servers with
1511 many connections, most of which are idle at any one point in time. 1514 many connections, most of which are idle at any one point in time.
1512 1515
1513 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1516 Source code for this benchmark is found as eg/bench2 in the AnyEvent
1514 distribution. 1517 distribution. It uses the AE interface, which makes a real difference
1518 for the EV and Perl backends only.
1515 1519
1516 Explanation of the columns 1520 Explanation of the columns
1517 *sockets* is the number of sockets, and twice the number of "servers" 1521 *sockets* is the number of sockets, and twice the number of "servers"
1518 (as each server has a read and write socket end). 1522 (as each server has a read and write socket end).
1519 1523
1525 forwarding it to another server. This includes deleting the old timeout 1529 forwarding it to another server. This includes deleting the old timeout
1526 and creating a new one that moves the timeout into the future. 1530 and creating a new one that moves the timeout into the future.
1527 1531
1528 Results 1532 Results
1529 name sockets create request 1533 name sockets create request
1530 EV 20000 69.01 11.16 1534 EV 20000 62.66 7.99
1531 Perl 20000 73.32 35.87 1535 Perl 20000 68.32 32.64
1532 IOAsync 20000 157.00 98.14 epoll 1536 IOAsync 20000 174.06 101.15 epoll
1533 IOAsync 20000 159.31 616.06 poll 1537 IOAsync 20000 174.67 610.84 poll
1534 Event 20000 212.62 257.32 1538 Event 20000 202.69 242.91
1535 Glib 20000 651.16 1896.30 1539 Glib 20000 557.01 1689.52
1536 POE 20000 349.67 12317.24 uses POE::Loop::Event 1540 POE 20000 341.54 12086.32 uses POE::Loop::Event
1537 1541
1538 Discussion 1542 Discussion
1539 This benchmark *does* measure scalability and overall performance of the 1543 This benchmark *does* measure scalability and overall performance of the
1540 particular event loop. 1544 particular event loop.
1541 1545
1654 As you can see, the AnyEvent + EV combination even beats the 1658 As you can see, the AnyEvent + EV combination even beats the
1655 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl 1659 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1656 backend easily beats IO::Lambda and POE. 1660 backend easily beats IO::Lambda and POE.
1657 1661
1658 And even the 100% non-blocking version written using the high-level (and 1662 And even the 100% non-blocking version written using the high-level (and
1659 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a 1663 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda
1660 large margin, even though it does all of DNS, tcp-connect and socket I/O 1664 higher level ("unoptimised") abstractions by a large margin, even though
1661 in a non-blocking way. 1665 it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
1662 1666
1663 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and 1667 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1664 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are 1668 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1665 part of the IO::lambda distribution and were used without any changes. 1669 part of the IO::Lambda distribution and were used without any changes.
1666 1670
1667SIGNALS 1671SIGNALS
1668 AnyEvent currently installs handlers for these signals: 1672 AnyEvent currently installs handlers for these signals:
1669 1673
1670 SIGCHLD 1674 SIGCHLD
1738 "AnyEvent::Util::guard". This speeds up guards considerably (and 1742 "AnyEvent::Util::guard". This speeds up guards considerably (and
1739 uses a lot less memory), but otherwise doesn't affect guard 1743 uses a lot less memory), but otherwise doesn't affect guard
1740 operation much. It is purely used for performance. 1744 operation much. It is purely used for performance.
1741 1745
1742 JSON and JSON::XS 1746 JSON and JSON::XS
1743 This module is required when you want to read or write JSON data via 1747 One of these modules is required when you want to read or write JSON
1744 AnyEvent::Handle. It is also written in pure-perl, but can take 1748 data via AnyEvent::Handle. It is also written in pure-perl, but can
1745 advantage of the ultra-high-speed JSON::XS module when it is 1749 take advantage of the ultra-high-speed JSON::XS module when it is
1746 installed. 1750 installed.
1747 1751
1748 In fact, AnyEvent::Handle will use JSON::XS by default if it is 1752 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1749 installed. 1753 installed.
1750 1754

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines