Commit 97a9449a9c5a756f2b56ec8f816fc65eb88b3d7a - libanyevent-perl

New upstream release. Ansgar Burchardt 13 years ago

7 changed file(s) with 161 addition(s) and 131 deletion(s). Raw diff Collapse all Expand all

-1

Changes less more

0	0	Revision history for Perl extension AnyEvent.
1	1
2		TODO: docs signal for condvar
	2	5.27 Sun Jun 6 12:12:05 CEST 2010
	3	- postpone differently in AnyEvent::Socket now, as
	4	when not, canceling the connection attempt might fail
	5	(found by Felix Antonius Wilhelm Ostmann).
	6	- explicitly check for non-stream sockets in AE::Handle, too many
	7	clueless people fell into the trap of this somehow working.
	8	- simplified and reworked the "OTHER MODULES" section.
	9	- better/more condvar examples.
3	10
4	11	5.261 Wed Apr 28 16:13:36 CEST 2010
5	12	- AF_INET6 was not properly used from Socket6 during configuration

-2

META.yml less more

0	0	--- #YAML:1.0
1	1	name: AnyEvent
2		version: 5.261
	2	version: 5.27
3	3	abstract: ~
4	4	author: []
5	5	license: unknown

13	13	directory:
14	14	- t
15	15	- inc
16		generated_by: ExtUtils::MakeMaker version 6.56
	16	generated_by: ExtUtils::MakeMaker version 6.55_02
17	17	meta-spec:
18	18	url: http://module-build.sourceforge.net/META-spec-v1.4.html
19	19	version: 1.4

+66

-58

README less more

6	6	SYNOPSIS
7	7	use AnyEvent;
8	8
9		# if you prefer function calls, look at the L<AE> manpage for
	9	# if you prefer function calls, look at the AE manpage for
10	10	# an alternative API.
11	11
12	12	# file handle or descriptor readable

472	472	Example: fork a process and wait for it
473	473
474	474	my $done = AnyEvent->condvar;
475
476		my $pid = fork or exit 5;
477
478		my $w = AnyEvent->child (
	475
	476	my $pid = fork or exit 5;
	477
	478	my $w = AnyEvent->child (
479	479	pid => $pid,
480	480	cb => sub {
481	481	my ($pid, $status) = @_;

483	483	$done->send;
484	484	},
485	485	);
486
487		# do something else, then wait for process exit
	486
	487	# do something else, then wait for process exit
488	488	$done->recv;
489	489
490	490	IDLE WATCHERS

540	540	event loop and will only block when necessary (usually when told by the
541	541	user).
542	542
543		The instrument to do that is called a "condition variable", so called
544		because they represent a condition that must become true.
	543	The tool to do that is called a "condition variable", so called because
	544	they represent a condition that must become true.
545	545
546	546	Now is probably a good time to look at the examples further below.
547	547

556	556	as if it were a callback, read about the caveats in the description for
557	557	the "->send" method).
558	558
559		Condition variables are similar to callbacks, except that you can
560		optionally wait for them. They can also be called merge points - points
561		in time where multiple outstanding events have been processed. And yet
562		another way to call them is transactions - each condition variable can
563		be used to represent a transaction, which finishes at some point and
564		delivers a result. And yet some people know them as "futures" - a
565		promise to compute/deliver something that you can wait for.
	559	Since condition variables are the most complex part of the AnyEvent API,
	560	here are some different mental models of what they are - pick the ones
	561	you can connect to:
	562
	563	* Condition variables are like callbacks - you can call them (and pass
	564	them instead of callbacks). Unlike callbacks however, you can also
	565	wait for them to be called.
	566
	567	* Condition variables are signals - one side can emit or send them,
	568	the other side can wait for them, or install a handler that is
	569	called when the signal fires.
	570
	571	* Condition variables are like "Merge Points" - points in your program
	572	where you merge multiple independent results/control flows into one.
	573
	574	* Condition variables represent a transaction - function that start
	575	some kind of transaction can return them, leaving the caller the
	576	choice between waiting in a blocking fashion, or setting a callback.
	577
	578	* Condition variables represent future values, or promises to deliver
	579	some result, long before the result is available.
566	580
567	581	Condition variables are very useful to signal that something has
568	582	finished, for example, if you write a module that does asynchronous http

1008	1022	The following is a non-exhaustive list of additional modules that use
1009	1023	AnyEvent as a client and can therefore be mixed easily with other
1010	1024	AnyEvent modules and other event loops in the same program. Some of the
1011		modules come with AnyEvent, most are available via CPAN.
	1025	modules come as part of AnyEvent, the others are available via CPAN.
1012	1026
1013	1027	AnyEvent::Util
1014	1028	Contains various utility functions that replace often-used but

1029	1043	AnyEvent::DNS
1030	1044	Provides rich asynchronous DNS resolver capabilities.
1031	1045
1032		AnyEvent::HTTP
1033		A simple-to-use HTTP library that is capable of making a lot of
1034		concurrent HTTP requests.
	1046	AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
	1047	AnyEvent::IGS, AnyEvent::FCP
	1048	Implement event-based interfaces to the protocols of the same name
	1049	(for the curious, IGS is the International Go Server and FCP is the
	1050	Freenet Client Protocol).
	1051
	1052	AnyEvent::Handle::UDP
	1053	Here be danger!
	1054
	1055	As Pauli would put it, "Not only is it not right, it's not even
	1056	wrong!" - there are so many things wrong with AnyEvent::Handle::UDP,
	1057	most notably it's use of a stream-based API with a protocol that
	1058	isn't streamable, that the only way to improve it is to delete it.
	1059
	1060	It features data corruption (but typically only under load) and
	1061	general confusion. On top, the author is not only clueless about UDP
	1062	but also fact-resistant - some gems of his understanding: "connect
	1063	doesn't work with UDP", "UDP packets are not IP packets", "UDP only
	1064	has datagrams, not packets", "I don't need to implement proper error
	1065	checking as UDP doesn't support error checking" and so on - he
	1066	doesn't even understand what's wrong with his module when it is
	1067	explained to him.
	1068
	1069	AnyEvent::DBI
	1070	Executes DBI requests asynchronously in a proxy process for you,
	1071	notifying you in an event-bnased way when the operation is finished.
	1072
	1073	AnyEvent::AIO
	1074	Truly asynchronous (as opposed to non-blocking) I/O, should be in
	1075	the toolbox of every event programmer. AnyEvent::AIO transparently
	1076	fuses IO::AIO and AnyEvent together, giving AnyEvent access to
	1077	event-based file I/O, and much more.
1035	1078
1036	1079	AnyEvent::HTTPD
1037		Provides a simple web application server framework.
	1080	A simple embedded webserver.
1038	1081
1039	1082	AnyEvent::FastPing
1040	1083	The fastest ping in the west.
1041
1042		AnyEvent::DBI
1043		Executes DBI requests asynchronously in a proxy process.
1044
1045		AnyEvent::AIO
1046		Truly asynchronous I/O, should be in the toolbox of every event
1047		programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
1048		together.
1049
1050		AnyEvent::BDB
1051		Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
1052		fuses BDB and AnyEvent together.
1053
1054		AnyEvent::GPSD
1055		A non-blocking interface to gpsd, a daemon delivering GPS
1056		information.
1057
1058		AnyEvent::IRC
1059		AnyEvent based IRC client module family (replacing the older
1060		Net::IRC3).
1061
1062		AnyEvent::XMPP
1063		AnyEvent based XMPP (Jabber protocol) module family (replacing the
1064		older Net::XMPP2>.
1065
1066		AnyEvent::IGS
1067		A non-blocking interface to the Internet Go Server protocol (used by
1068		App::IGS).
1069
1070		Net::FCP
1071		AnyEvent-based implementation of the Freenet Client Protocol,
1072		birthplace of AnyEvent.
1073
1074		Event::ExecFlow
1075		High level API for event-based execution flow control.
1076	1084
1077	1085	Coro
1078	1086	Has special support for AnyEvent via Coro::AnyEvent.

1844	1852	before the first watcher gets created, e.g. with a "BEGIN" block:
1845	1853
1846	1854	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1847
1848		use AnyEvent;
	1855
	1856	use AnyEvent;
1849	1857
1850	1858	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1851	1859	be used to probe what backend is used and gain other information (which

-6

debian/changelog less more

0		libanyevent-perl (5.261-1) UNRELEASED; urgency=low
1
2		IGNORE-VERSION: 5.261-1
3		Changes to constants.pl.PL seem to be irrelevant on Debian.
4
5		-- Ansgar Burchardt <ansgar@43-1.org> Thu, 29 Apr 2010 18:09:54 +0900
	0	libanyevent-perl (5.270-1) unstable; urgency=low
	1
	2	* New upstream release.
	3
	4	-- Ansgar Burchardt <ansgar@43-1.org> Sun, 06 Jun 2010 22:13:37 +0900
6	5
7	6	libanyevent-perl (5.260-1) unstable; urgency=low
8	7

-2

lib/AnyEvent/Handle.pm less more

0	0	=head1 NAME
1	1
2		AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
	2	AnyEvent::Handle - non-blocking I/O on streaming handles via AnyEvent
3	3
4	4	=head1 SYNOPSIS
5	5

32	32	=head1 DESCRIPTION
33	33
34	34	This module is a helper module to make it easier to do event-based I/O on
35		filehandles.
	35	stream-based filehandles (sockets, pipes or other stream things).
36	36
37	37	The L<AnyEvent::Intro> tutorial contains some well-documented
38	38	AnyEvent::Handle examples.

532	532
533	533	sub _start {
534	534	my ($self) = @_;
	535
	536	# too many clueless people try to use udp and similar sockets
	537	# with AnyEvent::Handle, do them a favour.
	538	my $type = getsockopt $self->{fh}, Socket::SOL_SOCKET (), Socket::SO_TYPE ();
	539	Carp::croak "AnyEvent::Handle: only stream sockets supported, anything else will NOT work!"
	540	if Socket::SOCK_STREAM != (unpack "I", $type) && defined $type;
535	541
536	542	AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
537	543

-3

lib/AnyEvent/Socket.pm less more

798	798	can be used as a normal perl file handle as well.
799	799
800	800	Unless called in void context, C<tcp_connect> returns a guard object that
801		will automatically abort connecting when it gets destroyed (it does not do
802		anything to the socket after the connect was successful).
	801	will automatically cancel the connection attempt when it gets destroyed
	802	- in which case the callback will not be invoked. Destroying it does not
	803	do anything to the socket after the connect was successful - you cannot
	804	"uncall" a callback that has been invoked already.
803	805
804	806	Sometimes you need to "prepare" the socket before connecting, for example,
805	807	to C<bind> it to some port, or you want a specific connect timeout that

895	897	return unless exists $state{fh};
896	898
897	899	my $target = shift @target
898		or return (%state = (), _postpone $connect);
	900	or return _postpone sub {
	901	return unless exists $state{fh};
	902	%state = ();
	903	$connect->();
	904	};
899	905
900	906	my ($domain, $type, $proto, $sockaddr) = @$target;
901	907

+63

-59

lib/AnyEvent.pm less more

8	8
9	9	use AnyEvent;
10	10
11		# if you prefer function calls, look at the L<AE> manpage for
	11	# if you prefer function calls, look at the AE manpage for
12	12	# an alternative API.
13	13
14	14	# file handle or descriptor readable

557	557	AnyEvent is slightly different: it expects somebody else to run the event
558	558	loop and will only block when necessary (usually when told by the user).
559	559
560		The instrument to do that is called a "condition variable", so called
561		because they represent a condition that must become true.
	560	The tool to do that is called a "condition variable", so called because
	561	they represent a condition that must become true.
562	562
563	563	Now is probably a good time to look at the examples further below.
564	564

573	573	were a callback, read about the caveats in the description for the C<<
574	574	->send >> method).
575	575
576		Condition variables are similar to callbacks, except that you can
577		optionally wait for them. They can also be called merge points - points
578		in time where multiple outstanding events have been processed. And yet
579		another way to call them is transactions - each condition variable can be
580		used to represent a transaction, which finishes at some point and delivers
581		a result. And yet some people know them as "futures" - a promise to
582		compute/deliver something that you can wait for.
	576	Since condition variables are the most complex part of the AnyEvent API, here are
	577	some different mental models of what they are - pick the ones you can connect to:
	578
	579	=over 4
	580
	581	=item * Condition variables are like callbacks - you can call them (and pass them instead
	582	of callbacks). Unlike callbacks however, you can also wait for them to be called.
	583
	584	=item * Condition variables are signals - one side can emit or send them,
	585	the other side can wait for them, or install a handler that is called when
	586	the signal fires.
	587
	588	=item * Condition variables are like "Merge Points" - points in your program
	589	where you merge multiple independent results/control flows into one.
	590
	591	=item * Condition variables represent a transaction - function that start
	592	some kind of transaction can return them, leaving the caller the choice
	593	between waiting in a blocking fashion, or setting a callback.
	594
	595	=item * Condition variables represent future values, or promises to deliver
	596	some result, long before the result is available.
	597
	598	=back
583	599
584	600	Condition variables are very useful to signal that something has finished,
585	601	for example, if you write a module that does asynchronous http requests,

1058	1074	The following is a non-exhaustive list of additional modules that use
1059	1075	AnyEvent as a client and can therefore be mixed easily with other AnyEvent
1060	1076	modules and other event loops in the same program. Some of the modules
1061		come with AnyEvent, most are available via CPAN.
	1077	come as part of AnyEvent, the others are available via CPAN.
1062	1078
1063	1079	=over 4
1064	1080

1083	1099
1084	1100	Provides rich asynchronous DNS resolver capabilities.
1085	1101
1086		=item L<AnyEvent::HTTP>
1087
1088		A simple-to-use HTTP library that is capable of making a lot of concurrent
1089		HTTP requests.
	1102	=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
	1103
	1104	Implement event-based interfaces to the protocols of the same name (for
	1105	the curious, IGS is the International Go Server and FCP is the Freenet
	1106	Client Protocol).
	1107
	1108	=item L<AnyEvent::Handle::UDP>
	1109
	1110	Here be danger!
	1111
	1112	As Pauli would put it, "Not only is it not right, it's not even wrong!" -
	1113	there are so many things wrong with AnyEvent::Handle::UDP, most notably
	1114	it's use of a stream-based API with a protocol that isn't streamable, that
	1115	the only way to improve it is to delete it.
	1116
	1117	It features data corruption (but typically only under load) and general
	1118	confusion. On top, the author is not only clueless about UDP but also
	1119	fact-resistant - some gems of his understanding: "connect doesn't work
	1120	with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
	1121	packets", "I don't need to implement proper error checking as UDP doesn't
	1122	support error checking" and so on - he doesn't even understand what's
	1123	wrong with his module when it is explained to him.
	1124
	1125	=item L<AnyEvent::DBI>
	1126
	1127	Executes L<DBI> requests asynchronously in a proxy process for you,
	1128	notifying you in an event-bnased way when the operation is finished.
	1129
	1130	=item L<AnyEvent::AIO>
	1131
	1132	Truly asynchronous (as opposed to non-blocking) I/O, should be in the
	1133	toolbox of every event programmer. AnyEvent::AIO transparently fuses
	1134	L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
	1135	file I/O, and much more.
1090	1136
1091	1137	=item L<AnyEvent::HTTPD>
1092	1138
1093		Provides a simple web application server framework.
	1139	A simple embedded webserver.
1094	1140
1095	1141	=item L<AnyEvent::FastPing>
1096	1142
1097	1143	The fastest ping in the west.
1098
1099		=item L<AnyEvent::DBI>
1100
1101		Executes L<DBI> requests asynchronously in a proxy process.
1102
1103		=item L<AnyEvent::AIO>
1104
1105		Truly asynchronous I/O, should be in the toolbox of every event
1106		programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
1107		together.
1108
1109		=item L<AnyEvent::BDB>
1110
1111		Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
1112		L<BDB> and AnyEvent together.
1113
1114		=item L<AnyEvent::GPSD>
1115
1116		A non-blocking interface to gpsd, a daemon delivering GPS information.
1117
1118		=item L<AnyEvent::IRC>
1119
1120		AnyEvent based IRC client module family (replacing the older Net::IRC3).
1121
1122		=item L<AnyEvent::XMPP>
1123
1124		AnyEvent based XMPP (Jabber protocol) module family (replacing the older
1125		Net::XMPP2>.
1126
1127		=item L<AnyEvent::IGS>
1128
1129		A non-blocking interface to the Internet Go Server protocol (used by
1130		L<App::IGS>).
1131
1132		=item L<Net::FCP>
1133
1134		AnyEvent-based implementation of the Freenet Client Protocol, birthplace
1135		of AnyEvent.
1136
1137		=item L<Event::ExecFlow>
1138
1139		High level API for event-based execution flow control.
1140	1144
1141	1145	=item L<Coro>
1142	1146

1160	1164
1161	1165	use Carp ();
1162	1166
1163		our $VERSION = '5.261';
	1167	our $VERSION = '5.27';
1164	1168	our $MODEL;
1165	1169
1166	1170	our $AUTOLOAD;