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

Comparing AnyEvent/README (file contents):
Revision 1.57 by root, Sat Dec 5 02:52:03 2009 UTC vs.
Revision 1.62 by root, Sun Jun 6 10:13:57 2010 UTC

… …
5 Qt and POE are various supported event loops/environments. 5 Qt and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # if you prefer function calls, look at the AE manpage for
11 # an alternative API.
12
10 # file descriptor readable 13 # file handle or descriptor readable
11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... }); 14 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
12 15
13 # one-shot or repeating timers 16 # one-shot or repeating timers
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); 17 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... 18 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
… …
486 $done->recv; 489 $done->recv;
487 490
488 IDLE WATCHERS 491 IDLE WATCHERS
489 $w = AnyEvent->idle (cb => <callback>); 492 $w = AnyEvent->idle (cb => <callback>);
490 493
491 Sometimes there is a need to do something, but it is not so important to 494 Repeatedly invoke the callback after the process becomes idle, until
492 do it instantly, but only when there is nothing better to do. This 495 either the watcher is destroyed or new events have been detected.
493 "nothing better to do" is usually defined to be "no other events need
494 attention by the event loop".
495 496
496 Idle watchers ideally get invoked when the event loop has nothing better 497 Idle watchers are useful when there is a need to do something, but it is
497 to do, just before it would block the process to wait for new events. 498 not so important (or wise) to do it instantly. The callback will be
498 Instead of blocking, the idle watcher is invoked. 499 invoked only when there is "nothing better to do", which is usually
500 defined as "all outstanding events have been handled and no new events
501 have been detected". That means that idle watchers ideally get invoked
502 when the event loop has just polled for new events but none have been
503 detected. Instead of blocking to wait for more events, the idle watchers
504 will be invoked.
499 505
500 Most event loops unfortunately do not really support idle watchers (only 506 Unfortunately, most event loops do not really support idle watchers
501 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent 507 (only EV, Event and Glib do it in a usable fashion) - for the rest,
502 will simply call the callback "from time to time". 508 AnyEvent will simply call the callback "from time to time".
503 509
504 Example: read lines from STDIN, but only process them when the program 510 Example: read lines from STDIN, but only process them when the program
505 is otherwise idle: 511 is otherwise idle:
506 512
507 my @lines; # read data 513 my @lines; # read data
… …
533 539
534 AnyEvent is slightly different: it expects somebody else to run the 540 AnyEvent is slightly different: it expects somebody else to run the
535 event loop and will only block when necessary (usually when told by the 541 event loop and will only block when necessary (usually when told by the
536 user). 542 user).
537 543
538 The instrument to do that is called a "condition variable", so called 544 The tool to do that is called a "condition variable", so called because
539 because they represent a condition that must become true. 545 they represent a condition that must become true.
540 546
541 Now is probably a good time to look at the examples further below. 547 Now is probably a good time to look at the examples further below.
542 548
543 Condition variables can be created by calling the "AnyEvent->condvar" 549 Condition variables can be created by calling the "AnyEvent->condvar"
544 method, usually without arguments. The only argument pair allowed is 550 method, usually without arguments. The only argument pair allowed is
… …
549 After creation, the condition variable is "false" until it becomes 555 After creation, the condition variable is "false" until it becomes
550 "true" by calling the "send" method (or calling the condition variable 556 "true" by calling the "send" method (or calling the condition variable
551 as if it were a callback, read about the caveats in the description for 557 as if it were a callback, read about the caveats in the description for
552 the "->send" method). 558 the "->send" method).
553 559
554 Condition variables are similar to callbacks, except that you can 560 Since condition variables are the most complex part of the AnyEvent API,
555 optionally wait for them. They can also be called merge points - points 561 here are some different mental models of what they are - pick the ones
556 in time where multiple outstanding events have been processed. And yet 562 you can connect to:
557 another way to call them is transactions - each condition variable can 563
558 be used to represent a transaction, which finishes at some point and 564 * Condition variables are like callbacks - you can call them (and pass
559 delivers a result. And yet some people know them as "futures" - a 565 them instead of callbacks). Unlike callbacks however, you can also
560 promise to compute/deliver something that you can wait for. 566 wait for them to be called.
567
568 * Condition variables are signals - one side can emit or send them,
569 the other side can wait for them, or install a handler that is
570 called when the signal fires.
571
572 * Condition variables are like "Merge Points" - points in your program
573 where you merge multiple independent results/control flows into one.
574
575 * Condition variables represent a transaction - function that start
576 some kind of transaction can return them, leaving the caller the
577 choice between waiting in a blocking fashion, or setting a callback.
578
579 * Condition variables represent future values, or promises to deliver
580 some result, long before the result is available.
561 581
562 Condition variables are very useful to signal that something has 582 Condition variables are very useful to signal that something has
563 finished, for example, if you write a module that does asynchronous http 583 finished, for example, if you write a module that does asynchronous http
564 requests, then a condition variable would be the ideal candidate to 584 requests, then a condition variable would be the ideal candidate to
565 signal the availability of results. The user can either act when the 585 signal the availability of results. The user can either act when the
… …
586 which eventually calls "-> send", and the "consumer side", which waits 606 which eventually calls "-> send", and the "consumer side", which waits
587 for the send to occur. 607 for the send to occur.
588 608
589 Example: wait for a timer. 609 Example: wait for a timer.
590 610
591 # wait till the result is ready 611 # condition: "wait till the timer is fired"
592 my $result_ready = AnyEvent->condvar; 612 my $timer_fired = AnyEvent->condvar;
593 613
594 # do something such as adding a timer 614 # create the timer - we could wait for, say
595 # or socket watcher the calls $result_ready->send 615 # a handle becomign ready, or even an
596 # when the "result" is ready. 616 # AnyEvent::HTTP request to finish, but
597 # in this case, we simply use a timer: 617 # in this case, we simply use a timer:
598 my $w = AnyEvent->timer ( 618 my $w = AnyEvent->timer (
599 after => 1, 619 after => 1,
600 cb => sub { $result_ready->send }, 620 cb => sub { $timer_fired->send },
601 ); 621 );
602 622
603 # this "blocks" (while handling events) till the callback 623 # this "blocks" (while handling events) till the callback
604 # calls ->send 624 # calls ->send
605 $result_ready->recv; 625 $timer_fired->recv;
606 626
607 Example: wait for a timer, but take advantage of the fact that condition 627 Example: wait for a timer, but take advantage of the fact that condition
608 variables are also callable directly. 628 variables are also callable directly.
609 629
610 my $done = AnyEvent->condvar; 630 my $done = AnyEvent->condvar;
… …
919 You should check $AnyEvent::MODEL before adding to this array, 939 You should check $AnyEvent::MODEL before adding to this array,
920 though: if it is defined then the event loop has already been 940 though: if it is defined then the event loop has already been
921 detected, and the array will be ignored. 941 detected, and the array will be ignored.
922 942
923 Best use "AnyEvent::post_detect { BLOCK }" when your application 943 Best use "AnyEvent::post_detect { BLOCK }" when your application
924 allows it,as it takes care of these details. 944 allows it, as it takes care of these details.
925 945
926 This variable is mainly useful for modules that can do something 946 This variable is mainly useful for modules that can do something
927 useful when AnyEvent is used and thus want to know when it is 947 useful when AnyEvent is used and thus want to know when it is
928 initialised, but do not need to even load it by default. This array 948 initialised, but do not need to even load it by default. This array
929 provides the means to hook into AnyEvent passively, without loading 949 provides the means to hook into AnyEvent passively, without loading
930 it. 950 it.
951
952 Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
953 together, you could put this into Coro (this is the actual code used
954 by Coro to accomplish this):
955
956 if (defined $AnyEvent::MODEL) {
957 # AnyEvent already initialised, so load Coro::AnyEvent
958 require Coro::AnyEvent;
959 } else {
960 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
961 # as soon as it is
962 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
963 }
931 964
932WHAT TO DO IN A MODULE 965WHAT TO DO IN A MODULE
933 As a module author, you should "use AnyEvent" and call AnyEvent methods 966 As a module author, you should "use AnyEvent" and call AnyEvent methods
934 freely, but you should not load a specific event module or rely on it. 967 freely, but you should not load a specific event module or rely on it.
935 968
… …
988 1021
989OTHER MODULES 1022OTHER MODULES
990 The following is a non-exhaustive list of additional modules that use 1023 The following is a non-exhaustive list of additional modules that use
991 AnyEvent as a client and can therefore be mixed easily with other 1024 AnyEvent as a client and can therefore be mixed easily with other
992 AnyEvent modules and other event loops in the same program. Some of the 1025 AnyEvent modules and other event loops in the same program. Some of the
993 modules come with AnyEvent, most are available via CPAN. 1026 modules come as part of AnyEvent, the others are available via CPAN.
994 1027
995 AnyEvent::Util 1028 AnyEvent::Util
996 Contains various utility functions that replace often-used but 1029 Contains various utility functions that replace often-used but
997 blocking functions such as "inet_aton" by event-/callback-based 1030 blocking functions such as "inet_aton" by event-/callback-based
998 versions. 1031 versions.
… …
1009 transparent and non-blocking SSL/TLS (via AnyEvent::TLS. 1042 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
1010 1043
1011 AnyEvent::DNS 1044 AnyEvent::DNS
1012 Provides rich asynchronous DNS resolver capabilities. 1045 Provides rich asynchronous DNS resolver capabilities.
1013 1046
1047 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
1048 AnyEvent::IGS, AnyEvent::FCP
1049 Implement event-based interfaces to the protocols of the same name
1050 (for the curious, IGS is the International Go Server and FCP is the
1051 Freenet Client Protocol).
1052
1053 AnyEvent::Handle::UDP
1054 Here be danger!
1055
1056 As Pauli would put it, "Not only is it not right, it's not even
1057 wrong!" - there are so many things wrong with AnyEvent::Handle::UDP,
1058 most notably it's use of a stream-based API with a protocol that
1059 isn't streamable, that the only way to improve it is to delete it.
1060
1061 It features data corruption (but typically only under load) and
1062 general confusion. On top, the author is not only clueless about UDP
1063 but also fact-resistant - some gems of his understanding: "connect
1064 doesn't work with UDP", "UDP packets are not IP packets", "UDP only
1065 has datagrams, not packets", "I don't need to implement proper error
1066 checking as UDP doesn't support error checking" and so on - he
1067 doesn't even understand what's wrong with his module when it is
1068 explained to him.
1069
1014 AnyEvent::HTTP 1070 AnyEvent::DBI
1015 A simple-to-use HTTP library that is capable of making a lot of 1071 Executes DBI requests asynchronously in a proxy process for you,
1016 concurrent HTTP requests. 1072 notifying you in an event-bnased way when the operation is finished.
1073
1074 AnyEvent::AIO
1075 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1076 the toolbox of every event programmer. AnyEvent::AIO transparently
1077 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
1078 event-based file I/O, and much more.
1017 1079
1018 AnyEvent::HTTPD 1080 AnyEvent::HTTPD
1019 Provides a simple web application server framework. 1081 A simple embedded webserver.
1020 1082
1021 AnyEvent::FastPing 1083 AnyEvent::FastPing
1022 The fastest ping in the west. 1084 The fastest ping in the west.
1023
1024 AnyEvent::DBI
1025 Executes DBI requests asynchronously in a proxy process.
1026
1027 AnyEvent::AIO
1028 Truly asynchronous I/O, should be in the toolbox of every event
1029 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
1030 together.
1031
1032 AnyEvent::BDB
1033 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
1034 fuses BDB and AnyEvent together.
1035
1036 AnyEvent::GPSD
1037 A non-blocking interface to gpsd, a daemon delivering GPS
1038 information.
1039
1040 AnyEvent::IRC
1041 AnyEvent based IRC client module family (replacing the older
1042 Net::IRC3).
1043
1044 AnyEvent::XMPP
1045 AnyEvent based XMPP (Jabber protocol) module family (replacing the
1046 older Net::XMPP2>.
1047
1048 AnyEvent::IGS
1049 A non-blocking interface to the Internet Go Server protocol (used by
1050 App::IGS).
1051
1052 Net::FCP
1053 AnyEvent-based implementation of the Freenet Client Protocol,
1054 birthplace of AnyEvent.
1055
1056 Event::ExecFlow
1057 High level API for event-based execution flow control.
1058 1085
1059 Coro 1086 Coro
1060 Has special support for AnyEvent via Coro::AnyEvent. 1087 Has special support for AnyEvent via Coro::AnyEvent.
1061 1088
1062SIMPLIFIED AE API 1089SIMPLIFIED AE API
1063 Starting with version 5.0, AnyEvent officially supports a second, much 1090 Starting with version 5.0, AnyEvent officially supports a second, much
1064 simpler, API that is designed to reduce the calling, typing and memory 1091 simpler, API that is designed to reduce the calling, typing and memory
1065 overhead. 1092 overhead by using function call syntax and a fixed number of parameters.
1066 1093
1067 See the AE manpage for details. 1094 See the AE manpage for details.
1068 1095
1069ERROR AND EXCEPTION HANDLING 1096ERROR AND EXCEPTION HANDLING
1070 In general, AnyEvent does not do any error handling - it relies on the 1097 In general, AnyEvent does not do any error handling - it relies on the
… …
1335 1362
1336 The actual code goes further and collects all errors ("die"s, 1363 The actual code goes further and collects all errors ("die"s,
1337 exceptions) that occurred during request processing. The "result" method 1364 exceptions) that occurred during request processing. The "result" method
1338 detects whether an exception as thrown (it is stored inside the $txn 1365 detects whether an exception as thrown (it is stored inside the $txn
1339 object) and just throws the exception, which means connection errors and 1366 object) and just throws the exception, which means connection errors and
1340 other problems get reported tot he code that tries to use the result, 1367 other problems get reported to the code that tries to use the result,
1341 not in a random callback. 1368 not in a random callback.
1342 1369
1343 All of this enables the following usage styles: 1370 All of this enables the following usage styles:
1344 1371
1345 1. Blocking: 1372 1. Blocking:
… …
1758 clock is available, can take avdantage of advanced kernel interfaces 1785 clock is available, can take avdantage of advanced kernel interfaces
1759 such as "epoll" and "kqueue", and is the fastest backend *by far*. 1786 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1760 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and 1787 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1761 Glib::EV). 1788 Glib::EV).
1762 1789
1790 If you only use backends that rely on another event loop (e.g.
1791 "Tk"), then this module will do nothing for you.
1792
1763 Guard 1793 Guard
1764 The guard module, when used, will be used to implement 1794 The guard module, when used, will be used to implement
1765 "AnyEvent::Util::guard". This speeds up guards considerably (and 1795 "AnyEvent::Util::guard". This speeds up guards considerably (and
1766 uses a lot less memory), but otherwise doesn't affect guard 1796 uses a lot less memory), but otherwise doesn't affect guard
1767 operation much. It is purely used for performance. 1797 operation much. It is purely used for performance.
1768 1798
1769 JSON and JSON::XS 1799 JSON and JSON::XS
1770 One of these modules is required when you want to read or write JSON 1800 One of these modules is required when you want to read or write JSON
1771 data via AnyEvent::Handle. It is also written in pure-perl, but can 1801 data via AnyEvent::Handle. JSON is also written in pure-perl, but
1772 take advantage of the ultra-high-speed JSON::XS module when it is 1802 can take advantage of the ultra-high-speed JSON::XS module when it
1773 installed. 1803 is installed.
1774
1775 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1776 installed.
1777 1804
1778 Net::SSLeay 1805 Net::SSLeay
1779 Implementing TLS/SSL in Perl is certainly interesting, but not very 1806 Implementing TLS/SSL in Perl is certainly interesting, but not very
1780 worthwhile: If this module is installed, then AnyEvent::Handle (with 1807 worthwhile: If this module is installed, then AnyEvent::Handle (with
1781 the help of AnyEvent::TLS), gains the ability to do TLS/SSL. 1808 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
… …
1787 additionally use it to try to use a monotonic clock for timing 1814 additionally use it to try to use a monotonic clock for timing
1788 stability. 1815 stability.
1789 1816
1790FORK 1817FORK
1791 Most event libraries are not fork-safe. The ones who are usually are 1818 Most event libraries are not fork-safe. The ones who are usually are
1792 because they rely on inefficient but fork-safe "select" or "poll" calls. 1819 because they rely on inefficient but fork-safe "select" or "poll" calls
1793 Only EV is fully fork-aware. 1820 - higher performance APIs such as BSD's kqueue or the dreaded Linux
1821 epoll are usually badly thought-out hacks that are incompatible with
1822 fork in one way or another. Only EV is fully fork-aware and ensures that
1823 you continue event-processing in both parent and child (or both, if you
1824 know what you are doing).
1794 1825
1795 This means that, in general, you cannot fork and do event processing in 1826 This means that, in general, you cannot fork and do event processing in
1796 the child if a watcher was created before the fork (which in turn 1827 the child if the event library was initialised before the fork (which
1797 initialises the event library). 1828 usually happens when the first AnyEvent watcher is created, or the
1829 library is loaded).
1798 1830
1799 If you have to fork, you must either do so *before* creating your first 1831 If you have to fork, you must either do so *before* creating your first
1800 watcher OR you must not use AnyEvent at all in the child OR you must do 1832 watcher OR you must not use AnyEvent at all in the child OR you must do
1801 something completely out of the scope of AnyEvent. 1833 something completely out of the scope of AnyEvent.
1802 1834
1803 The problem of doing event processing in the parent *and* the child is 1835 The problem of doing event processing in the parent *and* the child is
1804 much more complicated: even for backends that *are* fork-aware or 1836 much more complicated: even for backends that *are* fork-aware or
1805 fork-safe, their behaviour is not usually what you want: fork clones all 1837 fork-safe, their behaviour is not usually what you want: fork clones all
1806 watchers, that means all timers, I/O watchers etc. are active in both 1838 watchers, that means all timers, I/O watchers etc. are active in both
1807 parent and child, which is almost never what you want. 1839 parent and child, which is almost never what you want. USing "exec" to
1840 start worker children from some kind of manage rprocess is usually
1841 preferred, because it is much easier and cleaner, at the expense of
1842 having to have another binary.
1808 1843
1809SECURITY CONSIDERATIONS 1844SECURITY CONSIDERATIONS
1810 AnyEvent can be forced to load any event model via 1845 AnyEvent can be forced to load any event model via
1811 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1846 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1812 to execute arbitrary code or directly gain access, it can easily be used 1847 to execute arbitrary code or directly gain access, it can easily be used

Diff Legend

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