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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.158 by root, Fri Jul 24 08:40:35 2009 UTC vs.
Revision 1.159 by root, Fri Jul 24 12:35:58 2009 UTC

…		…
44	$cv->recv;	44	$cv->recv;
45		45
46	=head1 DESCRIPTION	46	=head1 DESCRIPTION
47		47
48	This module is a helper module to make it easier to do event-based I/O on	48	This module is a helper module to make it easier to do event-based I/O on
49	filehandles. For utility functions for doing non-blocking connects and accepts	49	filehandles.
50	on sockets see L<AnyEvent::Util>.
51		50
52	The L<AnyEvent::Intro> tutorial contains some well-documented	51	The L<AnyEvent::Intro> tutorial contains some well-documented
53	AnyEvent::Handle examples.	52	AnyEvent::Handle examples.
54		53
55	In the following, when the documentation refers to of "bytes" then this	54	In the following, when the documentation refers to of "bytes" then this
56	means characters. As sysread and syswrite are used for all I/O, their	55	means characters. As sysread and syswrite are used for all I/O, their
57	treatment of characters applies to this module as well.	56	treatment of characters applies to this module as well.
58		57
		58	At the very minimum, you should specify C<fh> or C<connect>, and the
		59	C<on_error> callback.
		60
59	All callbacks will be invoked with the handle object as their first	61	All callbacks will be invoked with the handle object as their first
60	argument.	62	argument.
61		63
62	=head1 METHODS	64	=head1 METHODS
63		65
…		…
67		69
68	The constructor supports these arguments (all as C<< key => value >> pairs).	70	The constructor supports these arguments (all as C<< key => value >> pairs).
69		71
70	=over 4	72	=over 4
71		73
72	=item fh => $filehandle [MANDATORY]
73
74	#=item fh => $filehandle [C<fh> or C<connect> MANDATORY]	74	=item fh => $filehandle [C<fh> or C<connect> MANDATORY]
75		75
76	The filehandle this L<AnyEvent::Handle> object will operate on.	76	The filehandle this L<AnyEvent::Handle> object will operate on.
77	NOTE: The filehandle will be set to non-blocking mode (using	77	NOTE: The filehandle will be set to non-blocking mode (using
78	C<AnyEvent::Util::fh_nonblocking>) by the constructor and needs to stay in	78	C<AnyEvent::Util::fh_nonblocking>) by the constructor and needs to stay in
79	that mode.	79	that mode.
80		80
81	#=item connect => [$host, $service]	81	=item connect => [$host, $service] [C<fh> or C<connect> MANDATORY]
82	#	82
83	# You have to specify either this parameter, or C<connect>, below.
84	#Try to connect to the specified host and service (port), using	83	Try to connect to the specified host and service (port), using
85	#C<AnyEvent::Socket::tcp_connect>.	84	C<AnyEvent::Socket::tcp_connect>. The C<$host> additionally becomes the
86	#	85	default C<peername>.
87	#When this	86
		87	You have to specify either this parameter, or C<fh>, above.
		88
		89	When this parameter is specified, then the C<on_prepare>,
		90	C<on_connect_error> and C<on_connect> callbacks will be called under the
		91	appropriate circumstances:
		92
		93	=over 4
		94
		95	=item on_prepare => $cb->($handle)
		96
		97	This (rarely used) callback is called before a new connection is
		98	attempted, but after the file handle has been created. It could be used to
		99	prepare the file handle with parameters required for the actual connect
		100	(as opposed to settings that can be changed when the connection is already
		101	established).
		102
		103	=item on_connect => $cb->($handle, $host, $port, $retry->())
		104
		105	This callback is called when a connection has been successfully established.
		106
		107	The actual numeric host and port (the socket peername) are passed as
		108	parameters, together with a retry callback.
		109
		110	When, for some reason, the handle is not acceptable, then calling
		111	C<$retry> will continue with the next conenction target (in case of
		112	multi-homed hosts or SRV records there can be multiple connection
		113	endpoints). When it is called then the read and write queues, eof status,
		114	tls status and similar properties of the handle are being reset.
		115
		116	In most cases, ignoring the C<$retry> parameter is the way to go.
		117
		118	=item on_connect_error => $cb->($handle, $message)
		119
		120	This callback is called when the conenction could not be
		121	established. C<$!> will contain the relevant error code, and C<$message> a
		122	message describing it (usually the same as C<"$!">).
		123
		124	If this callback isn't specified, then C<on_error> will be called with a
		125	fatal error instead.
		126
		127	=back
		128
		129	=item on_error => $cb->($handle, $fatal, $message)
		130
		131	This is the error callback, which is called when, well, some error
		132	occured, such as not being able to resolve the hostname, failure to
		133	connect or a read error.
		134
		135	Some errors are fatal (which is indicated by C<$fatal> being true). On
		136	fatal errors the handle object will be destroyed (by a call to C<< ->
		137	destroy >>) after invoking the error callback (which means you are free to
		138	examine the handle object). Examples of fatal errors are an EOF condition
		139	with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors. In
		140	cases where the other side can close the connection at their will it is
		141	often easiest to not report C<EPIPE> errors in this callback.
		142
		143	AnyEvent::Handle tries to find an appropriate error code for you to check
		144	against, but in some cases (TLS errors), this does not work well. It is
		145	recommended to always output the C<$message> argument in human-readable
		146	error messages (it's usually the same as C<"$!">).
		147
		148	Non-fatal errors can be retried by simply returning, but it is recommended
		149	to simply ignore this parameter and instead abondon the handle object
		150	when this callback is invoked. Examples of non-fatal errors are timeouts
		151	C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
		152
		153	On callback entrance, the value of C<$!> contains the operating system
		154	error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or
		155	C<EPROTO>).
		156
		157	While not mandatory, it is I<highly> recommended to set this callback, as
		158	you will not be notified of errors otherwise. The default simply calls
		159	C<croak>.
		160
		161	=item on_read => $cb->($handle)
		162
		163	This sets the default read callback, which is called when data arrives
		164	and no read request is in the queue (unlike read queue callbacks, this
		165	callback will only be called when at least one octet of data is in the
		166	read buffer).
		167
		168	To access (and remove data from) the read buffer, use the C<< ->rbuf >>
		169	method or access the C<< $handle->{rbuf} >> member directly. Note that you
		170	must not enlarge or modify the read buffer, you can only remove data at
		171	the beginning from it.
		172
		173	When an EOF condition is detected then AnyEvent::Handle will first try to
		174	feed all the remaining data to the queued callbacks and C<on_read> before
		175	calling the C<on_eof> callback. If no progress can be made, then a fatal
		176	error will be raised (with C<$!> set to C<EPIPE>).
		177
		178	Note that, unlike requests in the read queue, an C<on_read> callback
		179	doesn't mean you I<require> some data: if there is an EOF and there
		180	are outstanding read requests then an error will be flagged. With an
		181	C<on_read> callback, the C<on_eof> callback will be invoked.
88		182
89	=item on_eof => $cb->($handle)	183	=item on_eof => $cb->($handle)
90		184
91	Set the callback to be called when an end-of-file condition is detected,	185	Set the callback to be called when an end-of-file condition is detected,
92	i.e. in the case of a socket, when the other side has closed the	186	i.e. in the case of a socket, when the other side has closed the
…		…
99	callback and continue writing data, as only the read part has been shut	193	callback and continue writing data, as only the read part has been shut
100	down.	194	down.
101		195
102	If an EOF condition has been detected but no C<on_eof> callback has been	196	If an EOF condition has been detected but no C<on_eof> callback has been
103	set, then a fatal error will be raised with C<$!> set to <0>.	197	set, then a fatal error will be raised with C<$!> set to <0>.
104
105	=item on_error => $cb->($handle, $fatal, $message)
106
107	This is the error callback, which is called when, well, some error
108	occured, such as not being able to resolve the hostname, failure to
109	connect or a read error.
110
111	Some errors are fatal (which is indicated by C<$fatal> being true). On
112	fatal errors the handle object will be destroyed (by a call to C<< ->
113	destroy >>) after invoking the error callback (which means you are free to
114	examine the handle object). Examples of fatal errors are an EOF condition
115	with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors.
116
117	AnyEvent::Handle tries to find an appropriate error code for you to check
118	against, but in some cases (TLS errors), this does not work well. It is
119	recommended to always output the C<$message> argument in human-readable
120	error messages (it's usually the same as C<"$!">).
121
122	Non-fatal errors can be retried by simply returning, but it is recommended
123	to simply ignore this parameter and instead abondon the handle object
124	when this callback is invoked. Examples of non-fatal errors are timeouts
125	C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
126
127	On callback entrance, the value of C<$!> contains the operating system
128	error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or
129	C<EPROTO>).
130
131	While not mandatory, it is I<highly> recommended to set this callback, as
132	you will not be notified of errors otherwise. The default simply calls
133	C<croak>.
134
135	=item on_read => $cb->($handle)
136
137	This sets the default read callback, which is called when data arrives
138	and no read request is in the queue (unlike read queue callbacks, this
139	callback will only be called when at least one octet of data is in the
140	read buffer).
141
142	To access (and remove data from) the read buffer, use the C<< ->rbuf >>
143	method or access the C<< $handle->{rbuf} >> member directly. Note that you
144	must not enlarge or modify the read buffer, you can only remove data at
145	the beginning from it.
146
147	When an EOF condition is detected then AnyEvent::Handle will first try to
148	feed all the remaining data to the queued callbacks and C<on_read> before
149	calling the C<on_eof> callback. If no progress can be made, then a fatal
150	error will be raised (with C<$!> set to C<EPIPE>).
151
152	Note that, unlike requests in the read queue, an C<on_read> callback
153	doesn't mean you I<require> some data: if there is an EOF and there
154	are outstanding read requests then an error will be flagged. With an
155	C<on_read> callback, the C<on_eof> callback will be invoked.
156		198
157	=item on_drain => $cb->($handle)	199	=item on_drain => $cb->($handle)
158		200
159	This sets the callback that is called when the write buffer becomes empty	201	This sets the callback that is called when the write buffer becomes empty
160	(or when the callback is set and the buffer is empty already).	202	(or when the callback is set and the buffer is empty already).
…		…
359		401
360	sub new {	402	sub new {
361	my $class = shift;	403	my $class = shift;
362	my $self = bless { @_ }, $class;	404	my $self = bless { @_ }, $class;
363		405
364	$self->{fh} or Carp::croak "mandatory argument fh is missing";	406	if ($self->{fh}) {
		407	$self->_start;
		408	return unless $self->{fh}; # could be gone by now
		409
		410	} elsif ($self->{connect}) {
		411	require AnyEvent::Socket;
		412
		413	$self->{peername} = $self->{connect}[0]
		414	unless exists $self->{peername};
		415
		416	$self->{_skip_drain_rbuf} = 1;
		417
		418	{
		419	Scalar::Util::weaken (my $self = $self);
		420
		421	$self->{_connect} =
		422	AnyEvent::Socket::tcp_connect (
		423	$self->{connect}[0],
		424	$self->{connect}[1],
		425	sub {
		426	my ($fh, $host, $port, $retry) = @_;
		427
		428	if ($fh) {
		429	$self->{fh} = $fh;
		430
		431	delete $self->{_skip_drain_rbuf};
		432	$self->_start;
		433
		434	$self->{on_connect}
		435	and $self->{on_connect}($self, $host, $port, sub {
		436	delete @$self{qw(fh _tw _ww _rw _eof _queue rbuf _wbuf tls _tls_rbuf _tls_wbuf)};
		437	$self->{_skip_drain_rbuf} = 1;
		438	&$retry;
		439	});
		440
		441	} else {
		442	if ($self->{on_connect_error}) {
		443	$self->{on_connect_error}($self, "$!");
		444	$self->destroy;
		445	} else {
		446	$self->fatal ($!, 1);
		447	}
		448	}
		449	},
		450	sub {
		451	local $self->{fh} = $_[0];
		452
		453	$self->{on_prepare}->($self)
		454	if $self->{on_prepare};
		455	}
		456	);
		457	}
		458
		459	} else {
		460	Carp::croak "AnyEvent::Handle: either an existing fh or the connect parameter must be specified";
		461	}
		462
		463	$self
		464	}
		465
		466	sub _start {
		467	my ($self) = @_;
365		468
366	AnyEvent::Util::fh_nonblocking $self->{fh}, 1;	469	AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
367		470
368	$self->{_activity} = AnyEvent->now;	471	$self->{_activity} = AnyEvent->now;
369	$self->_timeout;	472	$self->_timeout;
…		…
374	if $self->{tls};	477	if $self->{tls};
375		478
376	$self->on_drain (delete $self->{on_drain}) if $self->{on_drain};	479	$self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
377		480
378	$self->start_read	481	$self->start_read
379	if $self->{on_read};	482	if $self->{on_read} \|\| @{ $self->{_queue} };
380
381	$self->{fh} && $self
382	}	483	}
383		484
384	#sub _shutdown {	485	#sub _shutdown {
385	# my ($self) = @_;	486	# my ($self) = @_;
386	#	487	#
…		…
466	sub no_delay {	567	sub no_delay {
467	$_[0]{no_delay} = $_[1];	568	$_[0]{no_delay} = $_[1];
468		569
469	eval {	570	eval {
470	local $SIG{__DIE__};	571	local $SIG{__DIE__};
471	setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];	572	setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1]
		573	if $_[0]{fh};
472	};	574	};
473	}	575	}
474		576
475	=item $handle->on_starttls ($cb)	577	=item $handle->on_starttls ($cb)
476		578
…		…
510	# reset the timeout watcher, as neccessary	612	# reset the timeout watcher, as neccessary
511	# also check for time-outs	613	# also check for time-outs
512	sub _timeout {	614	sub _timeout {
513	my ($self) = @_;	615	my ($self) = @_;
514		616
515	if ($self->{timeout}) {	617	if ($self->{timeout} && $self->{fh}) {
516	my $NOW = AnyEvent->now;	618	my $NOW = AnyEvent->now;
517		619
518	# when would the timeout trigger?	620	# when would the timeout trigger?
519	my $after = $self->{_activity} + $self->{timeout} - $NOW;	621	my $after = $self->{_activity} + $self->{timeout} - $NOW;
520		622
…		…
642	$self->{_tls_wbuf} .= $_[0];	744	$self->{_tls_wbuf} .= $_[0];
643		745
644	&_dotls ($self);	746	&_dotls ($self);
645	} else {	747	} else {
646	$self->{wbuf} .= $_[0];	748	$self->{wbuf} .= $_[0];
647	$self->_drain_wbuf;	749	$self->_drain_wbuf if $self->{fh};
648	}	750	}
649	}	751	}
650		752
651	=item $handle->push_write (type => @args)	753	=item $handle->push_write (type => @args)
652		754
…		…
869	=cut	971	=cut
870		972
871	sub _drain_rbuf {	973	sub _drain_rbuf {
872	my ($self) = @_;	974	my ($self) = @_;
873		975
		976	# avoid recursion
		977	return if exists $self->{_skip_drain_rbuf};
874	local $self->{_in_drain} = 1;	978	local $self->{_skip_drain_rbuf} = 1;
875		979
876	if (	980	if (
877	defined $self->{rbuf_max}	981	defined $self->{rbuf_max}
878	&& $self->{rbuf_max} < length $self->{rbuf}	982	&& $self->{rbuf_max} < length $self->{rbuf}
879	) {	983	) {
…		…
946		1050
947	sub on_read {	1051	sub on_read {
948	my ($self, $cb) = @_;	1052	my ($self, $cb) = @_;
949		1053
950	$self->{on_read} = $cb;	1054	$self->{on_read} = $cb;
951	$self->_drain_rbuf if $cb && !$self->{_in_drain};	1055	$self->_drain_rbuf if $cb;
952	}	1056	}
953		1057
954	=item $handle->rbuf	1058	=item $handle->rbuf
955		1059
956	Returns the read buffer (as a modifiable lvalue).	1060	Returns the read buffer (as a modifiable lvalue).
…		…
1008	$cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read")	1112	$cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read")
1009	->($self, $cb, @_);	1113	->($self, $cb, @_);
1010	}	1114	}
1011		1115
1012	push @{ $self->{_queue} }, $cb;	1116	push @{ $self->{_queue} }, $cb;
1013	$self->_drain_rbuf unless $self->{_in_drain};	1117	$self->_drain_rbuf;
1014	}	1118	}
1015		1119
1016	sub unshift_read {	1120	sub unshift_read {
1017	my $self = shift;	1121	my $self = shift;
1018	my $cb = pop;	1122	my $cb = pop;
…		…
1024	->($self, $cb, @_);	1128	->($self, $cb, @_);
1025	}	1129	}
1026		1130
1027		1131
1028	unshift @{ $self->{_queue} }, $cb;	1132	unshift @{ $self->{_queue} }, $cb;
1029	$self->_drain_rbuf unless $self->{_in_drain};	1133	$self->_drain_rbuf;
1030	}	1134	}
1031		1135
1032	=item $handle->push_read (type => @args, $cb)	1136	=item $handle->push_read (type => @args, $cb)
1033		1137
1034	=item $handle->unshift_read (type => @args, $cb)	1138	=item $handle->unshift_read (type => @args, $cb)
…		…
1427	if ($self->{tls}) {	1531	if ($self->{tls}) {
1428	Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);	1532	Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
1429		1533
1430	&_dotls ($self);	1534	&_dotls ($self);
1431	} else {	1535	} else {
1432	$self->_drain_rbuf unless $self->{_in_drain};	1536	$self->_drain_rbuf;
1433	}	1537	}
1434		1538
1435	} elsif (defined $len) {	1539	} elsif (defined $len) {
1436	delete $self->{_rw};	1540	delete $self->{_rw};
1437	$self->{_eof} = 1;	1541	$self->{_eof} = 1;
1438	$self->_drain_rbuf unless $self->{_in_drain};	1542	$self->_drain_rbuf;
1439		1543
1440	} elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {	1544	} elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
1441	return $self->_error ($!, 1);	1545	return $self->_error ($!, 1);
1442	}	1546	}
1443	});	1547	});
…		…
1503	$self->{_eof} = 1;	1607	$self->{_eof} = 1;
1504	}	1608	}
1505	}	1609	}
1506		1610
1507	$self->{_tls_rbuf} .= $tmp;	1611	$self->{_tls_rbuf} .= $tmp;
1508	$self->_drain_rbuf unless $self->{_in_drain};	1612	$self->_drain_rbuf;
1509	$self->{tls} or return; # tls session might have gone away in callback	1613	$self->{tls} or return; # tls session might have gone away in callback
1510	}	1614	}
1511		1615
1512	$tmp = Net::SSLeay::get_error ($self->{tls}, -1);	1616	$tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1513	return $self->_tls_error ($tmp)	1617	return $self->_tls_error ($tmp)

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.158 by root, Fri Jul 24 08:40:35 2009 UTC vs. Revision 1.159 by root, Fri Jul 24 12:35:58 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.158 by root, Fri Jul 24 08:40:35 2009 UTC vs.
Revision 1.159 by root, Fri Jul 24 12:35:58 2009 UTC