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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.320 by root, Mon Apr 12 02:50:31 2010 UTC vs.
Revision 1.329 by root, Sun Jul 11 05:44:22 2010 UTC

… …
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
12 # if you prefer function calls, look at the L<AE> manpage for 12 # if you prefer function calls, look at the AE manpage for
13 # an alternative API. 13 # an alternative API.
14 14
15 # file handle or descriptor readable 15 # file handle or descriptor readable
16 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... }); 16 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
17 17
… …
138 use AnyEvent; 138 use AnyEvent;
139 139
140 # .. AnyEvent will likely default to Tk 140 # .. AnyEvent will likely default to Tk
141 141
142The I<likely> means that, if any module loads another event model and 142The I<likely> means that, if any module loads another event model and
143starts using it, all bets are off. Maybe you should tell their authors to 143starts using it, all bets are off - this case should be very rare though,
144use AnyEvent so their modules work together with others seamlessly... 144as very few modules hardcode event loops without announcing this very
145loudly.
145 146
146The pure-perl implementation of AnyEvent is called 147The pure-perl implementation of AnyEvent is called
147C<AnyEvent::Impl::Perl>. Like other event modules you can load it 148C<AnyEvent::Impl::Perl>. Like other event modules you can load it
148explicitly and enjoy the high availability of that event loop :) 149explicitly and enjoy the high availability of that event loop :)
149 150
… …
556will actively watch for new events and call your callbacks. 557will actively watch for new events and call your callbacks.
557 558
558AnyEvent is slightly different: it expects somebody else to run the event 559AnyEvent is slightly different: it expects somebody else to run the event
559loop and will only block when necessary (usually when told by the user). 560loop and will only block when necessary (usually when told by the user).
560 561
561The instrument to do that is called a "condition variable", so called 562The tool to do that is called a "condition variable", so called because
562because they represent a condition that must become true. 563they represent a condition that must become true.
563 564
564Now is probably a good time to look at the examples further below. 565Now is probably a good time to look at the examples further below.
565 566
566Condition variables can be created by calling the C<< AnyEvent->condvar 567Condition variables can be created by calling the C<< AnyEvent->condvar
567>> method, usually without arguments. The only argument pair allowed is 568>> method, usually without arguments. The only argument pair allowed is
… …
572After creation, the condition variable is "false" until it becomes "true" 573After creation, the condition variable is "false" until it becomes "true"
573by calling the C<send> method (or calling the condition variable as if it 574by calling the C<send> method (or calling the condition variable as if it
574were a callback, read about the caveats in the description for the C<< 575were a callback, read about the caveats in the description for the C<<
575->send >> method). 576->send >> method).
576 577
577Condition variables are similar to callbacks, except that you can 578Since condition variables are the most complex part of the AnyEvent API, here are
578optionally wait for them. They can also be called merge points - points 579some different mental models of what they are - pick the ones you can connect to:
579in time where multiple outstanding events have been processed. And yet 580
580another way to call them is transactions - each condition variable can be 581=over 4
581used to represent a transaction, which finishes at some point and delivers 582
582a result. And yet some people know them as "futures" - a promise to 583=item * Condition variables are like callbacks - you can call them (and pass them instead
583compute/deliver something that you can wait for. 584of callbacks). Unlike callbacks however, you can also wait for them to be called.
585
586=item * Condition variables are signals - one side can emit or send them,
587the other side can wait for them, or install a handler that is called when
588the signal fires.
589
590=item * Condition variables are like "Merge Points" - points in your program
591where you merge multiple independent results/control flows into one.
592
593=item * Condition variables represent a transaction - function that start
594some kind of transaction can return them, leaving the caller the choice
595between waiting in a blocking fashion, or setting a callback.
596
597=item * Condition variables represent future values, or promises to deliver
598some result, long before the result is available.
599
600=back
584 601
585Condition variables are very useful to signal that something has finished, 602Condition variables are very useful to signal that something has finished,
586for example, if you write a module that does asynchronous http requests, 603for example, if you write a module that does asynchronous http requests,
587then a condition variable would be the ideal candidate to signal the 604then a condition variable would be the ideal candidate to signal the
588availability of results. The user can either act when the callback is 605availability of results. The user can either act when the callback is
… …
1057=head1 OTHER MODULES 1074=head1 OTHER MODULES
1058 1075
1059The following is a non-exhaustive list of additional modules that use 1076The following is a non-exhaustive list of additional modules that use
1060AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1077AnyEvent as a client and can therefore be mixed easily with other AnyEvent
1061modules and other event loops in the same program. Some of the modules 1078modules and other event loops in the same program. Some of the modules
1062come with AnyEvent, most are available via CPAN. 1079come as part of AnyEvent, the others are available via CPAN.
1063 1080
1064=over 4 1081=over 4
1065 1082
1066=item L<AnyEvent::Util> 1083=item L<AnyEvent::Util>
1067 1084
… …
1082 1099
1083=item L<AnyEvent::DNS> 1100=item L<AnyEvent::DNS>
1084 1101
1085Provides rich asynchronous DNS resolver capabilities. 1102Provides rich asynchronous DNS resolver capabilities.
1086 1103
1104=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1105
1106Implement event-based interfaces to the protocols of the same name (for
1107the curious, IGS is the International Go Server and FCP is the Freenet
1108Client Protocol).
1109
1110=item L<AnyEvent::Handle::UDP>
1111
1112Here be danger!
1113
1114As Pauli would put it, "Not only is it not right, it's not even wrong!" -
1115there are so many things wrong with AnyEvent::Handle::UDP, most notably
1116it's use of a stream-based API with a protocol that isn't streamable, that
1117the only way to improve it is to delete it.
1118
1119It features data corruption (but typically only under load) and general
1120confusion. On top, the author is not only clueless about UDP but also
1121fact-resistant - some gems of his understanding: "connect doesn't work
1122with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
1123packets", "I don't need to implement proper error checking as UDP doesn't
1124support error checking" and so on - he doesn't even understand what's
1125wrong with his module when it is explained to him.
1126
1087=item L<AnyEvent::HTTP> 1127=item L<AnyEvent::DBI>
1088 1128
1089A simple-to-use HTTP library that is capable of making a lot of concurrent 1129Executes L<DBI> requests asynchronously in a proxy process for you,
1090HTTP requests. 1130notifying you in an event-bnased way when the operation is finished.
1131
1132=item L<AnyEvent::AIO>
1133
1134Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1135toolbox of every event programmer. AnyEvent::AIO transparently fuses
1136L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1137file I/O, and much more.
1091 1138
1092=item L<AnyEvent::HTTPD> 1139=item L<AnyEvent::HTTPD>
1093 1140
1094Provides a simple web application server framework. 1141A simple embedded webserver.
1095 1142
1096=item L<AnyEvent::FastPing> 1143=item L<AnyEvent::FastPing>
1097 1144
1098The fastest ping in the west. 1145The fastest ping in the west.
1099
1100=item L<AnyEvent::DBI>
1101
1102Executes L<DBI> requests asynchronously in a proxy process.
1103
1104=item L<AnyEvent::AIO>
1105
1106Truly asynchronous I/O, should be in the toolbox of every event
1107programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
1108together.
1109
1110=item L<AnyEvent::BDB>
1111
1112Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
1113L<BDB> and AnyEvent together.
1114
1115=item L<AnyEvent::GPSD>
1116
1117A non-blocking interface to gpsd, a daemon delivering GPS information.
1118
1119=item L<AnyEvent::IRC>
1120
1121AnyEvent based IRC client module family (replacing the older Net::IRC3).
1122
1123=item L<AnyEvent::XMPP>
1124
1125AnyEvent based XMPP (Jabber protocol) module family (replacing the older
1126Net::XMPP2>.
1127
1128=item L<AnyEvent::IGS>
1129
1130A non-blocking interface to the Internet Go Server protocol (used by
1131L<App::IGS>).
1132
1133=item L<Net::FCP>
1134
1135AnyEvent-based implementation of the Freenet Client Protocol, birthplace
1136of AnyEvent.
1137
1138=item L<Event::ExecFlow>
1139
1140High level API for event-based execution flow control.
1141 1146
1142=item L<Coro> 1147=item L<Coro>
1143 1148
1144Has special support for AnyEvent via L<Coro::AnyEvent>. 1149Has special support for AnyEvent via L<Coro::AnyEvent>.
1145 1150
… …
1159 1164
1160BEGIN { AnyEvent::common_sense } 1165BEGIN { AnyEvent::common_sense }
1161 1166
1162use Carp (); 1167use Carp ();
1163 1168
1164our $VERSION = '5.26'; 1169our $VERSION = '5.271';
1165our $MODEL; 1170our $MODEL;
1166 1171
1167our $AUTOLOAD; 1172our $AUTOLOAD;
1168our @ISA; 1173our @ISA;
1169 1174

Diff Legend

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