[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.61 by root, Wed Apr 28 14:15:55 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
7	SYNOPSIS	7	SYNOPSIS
8	use AnyEvent;	8	use AnyEvent;
9		9
10	# if you prefer function calls, look at the L<AE> manpage for	10	# if you prefer function calls, look at the AE manpage for
11	# an alternative API.	11	# an alternative API.
12		12
13	# file handle or descriptor readable	13	# file handle or descriptor readable
14	my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });	14	my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
15		15
…		…
471	problems mentioned in the description of signal watchers apply.	471	problems mentioned in the description of signal watchers apply.
472		472
473	Example: fork a process and wait for it	473	Example: fork a process and wait for it
474		474
475	my $done = AnyEvent->condvar;	475	my $done = AnyEvent->condvar;
476		476
477	my $pid = fork or exit 5;	477	my $pid = fork or exit 5;
478		478
479	my $w = AnyEvent->child (	479	my $w = AnyEvent->child (
480	pid => $pid,	480	pid => $pid,
481	cb => sub {	481	cb => sub {
482	my ($pid, $status) = @_;	482	my ($pid, $status) = @_;
483	warn "pid $pid exited with status $status";	483	warn "pid $pid exited with status $status";
484	$done->send;	484	$done->send;
485	},	485	},
486	);	486	);
487		487
488	# do something else, then wait for process exit	488	# do something else, then wait for process exit
489	$done->recv;	489	$done->recv;
490		490
491	IDLE WATCHERS	491	IDLE WATCHERS
492	$w = AnyEvent->idle (cb => <callback>);	492	$w = AnyEvent->idle (cb => <callback>);
493		493
…		…
539		539
540	AnyEvent is slightly different: it expects somebody else to run the	540	AnyEvent is slightly different: it expects somebody else to run the
541	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
542	user).	542	user).
543		543
544	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
545	because they represent a condition that must become true.	545	they represent a condition that must become true.
546		546
547	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.
548		548
549	Condition variables can be created by calling the "AnyEvent->condvar"	549	Condition variables can be created by calling the "AnyEvent->condvar"
550	method, usually without arguments. The only argument pair allowed is	550	method, usually without arguments. The only argument pair allowed is
…		…
555	After creation, the condition variable is "false" until it becomes	555	After creation, the condition variable is "false" until it becomes
556	"true" by calling the "send" method (or calling the condition variable	556	"true" by calling the "send" method (or calling the condition variable
557	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
558	the "->send" method).	558	the "->send" method).
559		559
560	Condition variables are similar to callbacks, except that you can	560	Since condition variables are the most complex part of the AnyEvent API,
561	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
562	in time where multiple outstanding events have been processed. And yet	562	you can connect to:
563	another way to call them is transactions - each condition variable can	563
564	be used to represent a transaction, which finishes at some point and	564	* Condition variables are like callbacks - you can call them (and pass
565	delivers a result. And yet some people know them as "futures" - a	565	them instead of callbacks). Unlike callbacks however, you can also
566	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.
567		581
568	Condition variables are very useful to signal that something has	582	Condition variables are very useful to signal that something has
569	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
570	requests, then a condition variable would be the ideal candidate to	584	requests, then a condition variable would be the ideal candidate to
571	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
…		…
1007		1021
1008	OTHER MODULES	1022	OTHER MODULES
1009	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
1010	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
1011	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
1012	modules come with AnyEvent, most are available via CPAN.	1026	modules come as part of AnyEvent, the others are available via CPAN.
1013		1027
1014	AnyEvent::Util	1028	AnyEvent::Util
1015	Contains various utility functions that replace often-used but	1029	Contains various utility functions that replace often-used but
1016	blocking functions such as "inet_aton" by event-/callback-based	1030	blocking functions such as "inet_aton" by event-/callback-based
1017	versions.	1031	versions.
…		…
1028	transparent and non-blocking SSL/TLS (via AnyEvent::TLS.	1042	transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
1029		1043
1030	AnyEvent::DNS	1044	AnyEvent::DNS
1031	Provides rich asynchronous DNS resolver capabilities.	1045	Provides rich asynchronous DNS resolver capabilities.
1032		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
1033	AnyEvent::HTTP	1070	AnyEvent::DBI
1034	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,
1035	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.
1036		1079
1037	AnyEvent::HTTPD	1080	AnyEvent::HTTPD
1038	Provides a simple web application server framework.	1081	A simple embedded webserver.
1039		1082
1040	AnyEvent::FastPing	1083	AnyEvent::FastPing
1041	The fastest ping in the west.	1084	The fastest ping in the west.
1042
1043	AnyEvent::DBI
1044	Executes DBI requests asynchronously in a proxy process.
1045
1046	AnyEvent::AIO
1047	Truly asynchronous I/O, should be in the toolbox of every event
1048	programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
1049	together.
1050
1051	AnyEvent::BDB
1052	Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
1053	fuses BDB and AnyEvent together.
1054
1055	AnyEvent::GPSD
1056	A non-blocking interface to gpsd, a daemon delivering GPS
1057	information.
1058
1059	AnyEvent::IRC
1060	AnyEvent based IRC client module family (replacing the older
1061	Net::IRC3).
1062
1063	AnyEvent::XMPP
1064	AnyEvent based XMPP (Jabber protocol) module family (replacing the
1065	older Net::XMPP2>.
1066
1067	AnyEvent::IGS
1068	A non-blocking interface to the Internet Go Server protocol (used by
1069	App::IGS).
1070
1071	Net::FCP
1072	AnyEvent-based implementation of the Freenet Client Protocol,
1073	birthplace of AnyEvent.
1074
1075	Event::ExecFlow
1076	High level API for event-based execution flow control.
1077		1085
1078	Coro	1086	Coro
1079	Has special support for AnyEvent via Coro::AnyEvent.	1087	Has special support for AnyEvent via Coro::AnyEvent.
1080		1088
1081	SIMPLIFIED AE API	1089	SIMPLIFIED AE API
…		…
1843		1851
1844	You can make AnyEvent completely ignore this variable by deleting it	1852	You can make AnyEvent completely ignore this variable by deleting it
1845	before the first watcher gets created, e.g. with a "BEGIN" block:	1853	before the first watcher gets created, e.g. with a "BEGIN" block:
1846		1854
1847	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }	1855	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1848		1856
1849	use AnyEvent;	1857	use AnyEvent;
1850		1858
1851	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can	1859	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1852	be used to probe what backend is used and gain other information (which	1860	be used to probe what backend is used and gain other information (which
1853	is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),	1861	is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1854	and $ENV{PERL_ANYEVENT_STRICT}.	1862	and $ENV{PERL_ANYEVENT_STRICT}.

Diff Legend

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

Comparing AnyEvent/README (file contents): Revision 1.61 by root, Wed Apr 28 14:15:55 2010 UTC vs. Revision 1.62 by root, Sun Jun 6 10:13:57 2010 UTC

Diff Legend

Comparing AnyEvent/README (file contents):
Revision 1.61 by root, Wed Apr 28 14:15:55 2010 UTC vs.
Revision 1.62 by root, Sun Jun 6 10:13:57 2010 UTC