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

Comparing AnyEvent/README (file contents):
Revision 1.58 by root, Sun Dec 20 22:49:52 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;
… …
1001 1021
1002OTHER MODULES 1022OTHER MODULES
1003 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
1004 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
1005 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
1006 modules come with AnyEvent, most are available via CPAN. 1026 modules come as part of AnyEvent, the others are available via CPAN.
1007 1027
1008 AnyEvent::Util 1028 AnyEvent::Util
1009 Contains various utility functions that replace often-used but 1029 Contains various utility functions that replace often-used but
1010 blocking functions such as "inet_aton" by event-/callback-based 1030 blocking functions such as "inet_aton" by event-/callback-based
1011 versions. 1031 versions.
… …
1022 transparent and non-blocking SSL/TLS (via AnyEvent::TLS. 1042 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
1023 1043
1024 AnyEvent::DNS 1044 AnyEvent::DNS
1025 Provides rich asynchronous DNS resolver capabilities. 1045 Provides rich asynchronous DNS resolver capabilities.
1026 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
1027 AnyEvent::HTTP 1070 AnyEvent::DBI
1028 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,
1029 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.
1030 1079
1031 AnyEvent::HTTPD 1080 AnyEvent::HTTPD
1032 Provides a simple web application server framework. 1081 A simple embedded webserver.
1033 1082
1034 AnyEvent::FastPing 1083 AnyEvent::FastPing
1035 The fastest ping in the west. 1084 The fastest ping in the west.
1036
1037 AnyEvent::DBI
1038 Executes DBI requests asynchronously in a proxy process.
1039
1040 AnyEvent::AIO
1041 Truly asynchronous I/O, should be in the toolbox of every event
1042 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
1043 together.
1044
1045 AnyEvent::BDB
1046 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
1047 fuses BDB and AnyEvent together.
1048
1049 AnyEvent::GPSD
1050 A non-blocking interface to gpsd, a daemon delivering GPS
1051 information.
1052
1053 AnyEvent::IRC
1054 AnyEvent based IRC client module family (replacing the older
1055 Net::IRC3).
1056
1057 AnyEvent::XMPP
1058 AnyEvent based XMPP (Jabber protocol) module family (replacing the
1059 older Net::XMPP2>.
1060
1061 AnyEvent::IGS
1062 A non-blocking interface to the Internet Go Server protocol (used by
1063 App::IGS).
1064
1065 Net::FCP
1066 AnyEvent-based implementation of the Freenet Client Protocol,
1067 birthplace of AnyEvent.
1068
1069 Event::ExecFlow
1070 High level API for event-based execution flow control.
1071 1085
1072 Coro 1086 Coro
1073 Has special support for AnyEvent via Coro::AnyEvent. 1087 Has special support for AnyEvent via Coro::AnyEvent.
1074 1088
1075SIMPLIFIED AE API 1089SIMPLIFIED AE API
1076 Starting with version 5.0, AnyEvent officially supports a second, much 1090 Starting with version 5.0, AnyEvent officially supports a second, much
1077 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
1078 overhead. 1092 overhead by using function call syntax and a fixed number of parameters.
1079 1093
1080 See the AE manpage for details. 1094 See the AE manpage for details.
1081 1095
1082ERROR AND EXCEPTION HANDLING 1096ERROR AND EXCEPTION HANDLING
1083 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
… …
1348 1362
1349 The actual code goes further and collects all errors ("die"s, 1363 The actual code goes further and collects all errors ("die"s,
1350 exceptions) that occurred during request processing. The "result" method 1364 exceptions) that occurred during request processing. The "result" method
1351 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
1352 object) and just throws the exception, which means connection errors and 1366 object) and just throws the exception, which means connection errors and
1353 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,
1354 not in a random callback. 1368 not in a random callback.
1355 1369
1356 All of this enables the following usage styles: 1370 All of this enables the following usage styles:
1357 1371
1358 1. Blocking: 1372 1. Blocking:
… …
1771 clock is available, can take avdantage of advanced kernel interfaces 1785 clock is available, can take avdantage of advanced kernel interfaces
1772 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*.
1773 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
1774 Glib::EV). 1788 Glib::EV).
1775 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
1776 Guard 1793 Guard
1777 The guard module, when used, will be used to implement 1794 The guard module, when used, will be used to implement
1778 "AnyEvent::Util::guard". This speeds up guards considerably (and 1795 "AnyEvent::Util::guard". This speeds up guards considerably (and
1779 uses a lot less memory), but otherwise doesn't affect guard 1796 uses a lot less memory), but otherwise doesn't affect guard
1780 operation much. It is purely used for performance. 1797 operation much. It is purely used for performance.
1781 1798
1782 JSON and JSON::XS 1799 JSON and JSON::XS
1783 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
1784 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
1785 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
1786 installed. 1803 is installed.
1787
1788 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1789 installed.
1790 1804
1791 Net::SSLeay 1805 Net::SSLeay
1792 Implementing TLS/SSL in Perl is certainly interesting, but not very 1806 Implementing TLS/SSL in Perl is certainly interesting, but not very
1793 worthwhile: If this module is installed, then AnyEvent::Handle (with 1807 worthwhile: If this module is installed, then AnyEvent::Handle (with
1794 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.
… …
1800 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
1801 stability. 1815 stability.
1802 1816
1803FORK 1817FORK
1804 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
1805 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
1806 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).
1807 1825
1808 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
1809 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
1810 initialises the event library). 1828 usually happens when the first AnyEvent watcher is created, or the
1829 library is loaded).
1811 1830
1812 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
1813 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
1814 something completely out of the scope of AnyEvent. 1833 something completely out of the scope of AnyEvent.
1815 1834
1816 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
1817 much more complicated: even for backends that *are* fork-aware or 1836 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 1837 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 1838 watchers, that means all timers, I/O watchers etc. are active in both
1820 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.
1821 1843
1822SECURITY CONSIDERATIONS 1844SECURITY CONSIDERATIONS
1823 AnyEvent can be forced to load any event model via 1845 AnyEvent can be forced to load any event model via
1824 $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
1825 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