[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent.pm

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

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.320 by root, Mon Apr 12 02:50:31 2010 UTC vs. Revision 1.326 by root, Sun Jun 6 10:11:56 2010 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.320 by root, Mon Apr 12 02:50:31 2010 UTC vs.
Revision 1.326 by root, Sun Jun 6 10:11:56 2010 UTC