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

Comparing cvsroot/AnyEvent/README (file contents):
Revision 1.59 by root, Tue Jan 5 10:45:25 2010 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 => ...
… …
536 539
537 AnyEvent is slightly different: it expects somebody else to run the 540 AnyEvent is slightly different: it expects somebody else to run the
538 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
539 user). 542 user).
540 543
541 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
542 because they represent a condition that must become true. 545 they represent a condition that must become true.
543 546
544 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.
545 548
546 Condition variables can be created by calling the "AnyEvent->condvar" 549 Condition variables can be created by calling the "AnyEvent->condvar"
547 method, usually without arguments. The only argument pair allowed is 550 method, usually without arguments. The only argument pair allowed is
… …
552 After creation, the condition variable is "false" until it becomes 555 After creation, the condition variable is "false" until it becomes
553 "true" by calling the "send" method (or calling the condition variable 556 "true" by calling the "send" method (or calling the condition variable
554 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
555 the "->send" method). 558 the "->send" method).
556 559
557 Condition variables are similar to callbacks, except that you can 560 Since condition variables are the most complex part of the AnyEvent API,
558 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
559 in time where multiple outstanding events have been processed. And yet 562 you can connect to:
560 another way to call them is transactions - each condition variable can 563
561 be used to represent a transaction, which finishes at some point and 564 * Condition variables are like callbacks - you can call them (and pass
562 delivers a result. And yet some people know them as "futures" - a 565 them instead of callbacks). Unlike callbacks however, you can also
563 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.
564 581
565 Condition variables are very useful to signal that something has 582 Condition variables are very useful to signal that something has
566 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
567 requests, then a condition variable would be the ideal candidate to 584 requests, then a condition variable would be the ideal candidate to
568 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
… …
589 which eventually calls "-> send", and the "consumer side", which waits 606 which eventually calls "-> send", and the "consumer side", which waits
590 for the send to occur. 607 for the send to occur.
591 608
592 Example: wait for a timer. 609 Example: wait for a timer.
593 610
594 # wait till the result is ready 611 # condition: "wait till the timer is fired"
595 my $result_ready = AnyEvent->condvar; 612 my $timer_fired = AnyEvent->condvar;
596 613
597 # do something such as adding a timer 614 # create the timer - we could wait for, say
598 # or socket watcher the calls $result_ready->send 615 # a handle becomign ready, or even an
599 # when the "result" is ready. 616 # AnyEvent::HTTP request to finish, but
600 # in this case, we simply use a timer: 617 # in this case, we simply use a timer:
601 my $w = AnyEvent->timer ( 618 my $w = AnyEvent->timer (
602 after => 1, 619 after => 1,
603 cb => sub { $result_ready->send }, 620 cb => sub { $timer_fired->send },
604 ); 621 );
605 622
606 # this "blocks" (while handling events) till the callback 623 # this "blocks" (while handling events) till the callback
607 # calls ->send 624 # calls ->send
608 $result_ready->recv; 625 $timer_fired->recv;
609 626
610 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
611 variables are also callable directly. 628 variables are also callable directly.
612 629
613 my $done = AnyEvent->condvar; 630 my $done = AnyEvent->condvar;
… …
1004 1021
1005OTHER MODULES 1022OTHER MODULES
1006 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
1007 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
1008 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
1009 modules come with AnyEvent, most are available via CPAN. 1026 modules come as part of AnyEvent, the others are available via CPAN.
1010 1027
1011 AnyEvent::Util 1028 AnyEvent::Util
1012 Contains various utility functions that replace often-used but 1029 Contains various utility functions that replace often-used but
1013 blocking functions such as "inet_aton" by event-/callback-based 1030 blocking functions such as "inet_aton" by event-/callback-based
1014 versions. 1031 versions.
… …
1025 transparent and non-blocking SSL/TLS (via AnyEvent::TLS. 1042 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
1026 1043
1027 AnyEvent::DNS 1044 AnyEvent::DNS
1028 Provides rich asynchronous DNS resolver capabilities. 1045 Provides rich asynchronous DNS resolver capabilities.
1029 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
1030 AnyEvent::HTTP 1070 AnyEvent::DBI
1031 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,
1032 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.
1033 1079
1034 AnyEvent::HTTPD 1080 AnyEvent::HTTPD
1035 Provides a simple web application server framework. 1081 A simple embedded webserver.
1036 1082
1037 AnyEvent::FastPing 1083 AnyEvent::FastPing
1038 The fastest ping in the west. 1084 The fastest ping in the west.
1039
1040 AnyEvent::DBI
1041 Executes DBI requests asynchronously in a proxy process.
1042
1043 AnyEvent::AIO
1044 Truly asynchronous I/O, should be in the toolbox of every event
1045 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
1046 together.
1047
1048 AnyEvent::BDB
1049 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
1050 fuses BDB and AnyEvent together.
1051
1052 AnyEvent::GPSD
1053 A non-blocking interface to gpsd, a daemon delivering GPS
1054 information.
1055
1056 AnyEvent::IRC
1057 AnyEvent based IRC client module family (replacing the older
1058 Net::IRC3).
1059
1060 AnyEvent::XMPP
1061 AnyEvent based XMPP (Jabber protocol) module family (replacing the
1062 older Net::XMPP2>.
1063
1064 AnyEvent::IGS
1065 A non-blocking interface to the Internet Go Server protocol (used by
1066 App::IGS).
1067
1068 Net::FCP
1069 AnyEvent-based implementation of the Freenet Client Protocol,
1070 birthplace of AnyEvent.
1071
1072 Event::ExecFlow
1073 High level API for event-based execution flow control.
1074 1085
1075 Coro 1086 Coro
1076 Has special support for AnyEvent via Coro::AnyEvent. 1087 Has special support for AnyEvent via Coro::AnyEvent.
1077 1088
1078SIMPLIFIED AE API 1089SIMPLIFIED AE API
1079 Starting with version 5.0, AnyEvent officially supports a second, much 1090 Starting with version 5.0, AnyEvent officially supports a second, much
1080 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
1081 overhead. 1092 overhead by using function call syntax and a fixed number of parameters.
1082 1093
1083 See the AE manpage for details. 1094 See the AE manpage for details.
1084 1095
1085ERROR AND EXCEPTION HANDLING 1096ERROR AND EXCEPTION HANDLING
1086 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
… …
1351 1362
1352 The actual code goes further and collects all errors ("die"s, 1363 The actual code goes further and collects all errors ("die"s,
1353 exceptions) that occurred during request processing. The "result" method 1364 exceptions) that occurred during request processing. The "result" method
1354 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
1355 object) and just throws the exception, which means connection errors and 1366 object) and just throws the exception, which means connection errors and
1356 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,
1357 not in a random callback. 1368 not in a random callback.
1358 1369
1359 All of this enables the following usage styles: 1370 All of this enables the following usage styles:
1360 1371
1361 1. Blocking: 1372 1. Blocking:
… …
1774 clock is available, can take avdantage of advanced kernel interfaces 1785 clock is available, can take avdantage of advanced kernel interfaces
1775 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*.
1776 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
1777 Glib::EV). 1788 Glib::EV).
1778 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
1779 Guard 1793 Guard
1780 The guard module, when used, will be used to implement 1794 The guard module, when used, will be used to implement
1781 "AnyEvent::Util::guard". This speeds up guards considerably (and 1795 "AnyEvent::Util::guard". This speeds up guards considerably (and
1782 uses a lot less memory), but otherwise doesn't affect guard 1796 uses a lot less memory), but otherwise doesn't affect guard
1783 operation much. It is purely used for performance. 1797 operation much. It is purely used for performance.
1784 1798
1785 JSON and JSON::XS 1799 JSON and JSON::XS
1786 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
1787 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
1788 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
1789 installed. 1803 is installed.
1790
1791 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1792 installed.
1793 1804
1794 Net::SSLeay 1805 Net::SSLeay
1795 Implementing TLS/SSL in Perl is certainly interesting, but not very 1806 Implementing TLS/SSL in Perl is certainly interesting, but not very
1796 worthwhile: If this module is installed, then AnyEvent::Handle (with 1807 worthwhile: If this module is installed, then AnyEvent::Handle (with
1797 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.

Diff Legend

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