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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.209 by root, Wed Dec 29 04:40:23 2010 UTC vs.
Revision 1.218 by root, Thu Feb 24 12:04:20 2011 UTC

… …
114=over 4 114=over 4
115 115
116=item on_prepare => $cb->($handle) 116=item on_prepare => $cb->($handle)
117 117
118This (rarely used) callback is called before a new connection is 118This (rarely used) callback is called before a new connection is
119attempted, but after the file handle has been created. It could be used to 119attempted, but after the file handle has been created (you can access that
120file handle via C<< $handle->{fh} >>). It could be used to prepare the
120prepare the file handle with parameters required for the actual connect 121file handle with parameters required for the actual connect (as opposed to
121(as opposed to settings that can be changed when the connection is already 122settings that can be changed when the connection is already established).
122established).
123 123
124The return value of this callback should be the connect timeout value in 124The return value of this callback should be the connect timeout value in
125seconds (or C<0>, or C<undef>, or the empty list, to indicate that the 125seconds (or C<0>, or C<undef>, or the empty list, to indicate that the
126default timeout is to be used). 126default timeout is to be used).
127 127
… …
247many seconds pass without a successful read or write on the underlying 247many seconds pass without a successful read or write on the underlying
248file handle (or a call to C<timeout_reset>), the C<on_timeout> callback 248file handle (or a call to C<timeout_reset>), the C<on_timeout> callback
249will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT> 249will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT>
250error will be raised). 250error will be raised).
251 251
252There are three variants of the timeouts that work independently 252There are three variants of the timeouts that work independently of each
253of each other, for both read and write, just read, and just write: 253other, for both read and write (triggered when nothing was read I<OR>
254written), just read (triggered when nothing was read), and just write:
254C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks 255C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks
255C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions 256C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions
256C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>. 257C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>.
257 258
258Note that timeout processing is active even when you do not have 259Note that timeout processing is active even when you do not have any
259any outstanding read or write requests: If you plan to keep the connection 260outstanding read or write requests: If you plan to keep the connection
260idle then you should disable the timeout temporarily or ignore the timeout 261idle then you should disable the timeout temporarily or ignore the
261in the C<on_timeout> callback, in which case AnyEvent::Handle will simply 262timeout in the corresponding C<on_timeout> callback, in which case
262restart the timeout. 263AnyEvent::Handle will simply restart the timeout.
263 264
264Zero (the default) disables this timeout. 265Zero (the default) disables the corresponding timeout.
265 266
266=item on_timeout => $cb->($handle) 267=item on_timeout => $cb->($handle)
268
269=item on_rtimeout => $cb->($handle)
270
271=item on_wtimeout => $cb->($handle)
267 272
268Called whenever the inactivity timeout passes. If you return from this 273Called whenever the inactivity timeout passes. If you return from this
269callback, then the timeout will be reset as if some activity had happened, 274callback, then the timeout will be reset as if some activity had happened,
270so this condition is not fatal in any way. 275so this condition is not fatal in any way.
271 276
… …
536 }); 541 });
537 542
538 } else { 543 } else {
539 if ($self->{on_connect_error}) { 544 if ($self->{on_connect_error}) {
540 $self->{on_connect_error}($self, "$!"); 545 $self->{on_connect_error}($self, "$!");
541 $self->destroy; 546 $self->destroy if $self;
542 } else { 547 } else {
543 $self->_error ($!, 1); 548 $self->_error ($!, 1);
544 } 549 }
545 } 550 }
546 }, 551 },
547 sub { 552 sub {
548 local $self->{fh} = $_[0]; 553 local $self->{fh} = $_[0];
549 554
550 $self->{on_prepare} 555 $self->{on_prepare}
551 ? $self->{on_prepare}->($self) 556 ? $self->{on_prepare}->($self)
552 : () 557 : ()
553 } 558 }
554 ); 559 );
555 } 560 }
556 561
… …
765 770
766sub rbuf_max { 771sub rbuf_max {
767 $_[0]{rbuf_max} = $_[1]; 772 $_[0]{rbuf_max} = $_[1];
768} 773}
769 774
770sub rbuf_max { 775sub wbuf_max {
771 $_[0]{wbuf_max} = $_[1]; 776 $_[0]{wbuf_max} = $_[1];
772} 777}
773 778
774############################################################################# 779#############################################################################
775 780
… …
778=item $handle->rtimeout ($seconds) 783=item $handle->rtimeout ($seconds)
779 784
780=item $handle->wtimeout ($seconds) 785=item $handle->wtimeout ($seconds)
781 786
782Configures (or disables) the inactivity timeout. 787Configures (or disables) the inactivity timeout.
788
789The timeout will be checked instantly, so this method might destroy the
790handle before it returns.
783 791
784=item $handle->timeout_reset 792=item $handle->timeout_reset
785 793
786=item $handle->rtimeout_reset 794=item $handle->rtimeout_reset
787 795
… …
1087before it was actually written. One way to do that is to replace your 1095before it was actually written. One way to do that is to replace your
1088C<on_drain> handler by a callback that shuts down the socket (and set 1096C<on_drain> handler by a callback that shuts down the socket (and set
1089C<low_water_mark> to C<0>). This method is a shorthand for just that, and 1097C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1090replaces the C<on_drain> callback with: 1098replaces the C<on_drain> callback with:
1091 1099
1092 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 1100 sub { shutdown $_[0]{fh}, 1 }
1093 1101
1094This simply shuts down the write side and signals an EOF condition to the 1102This simply shuts down the write side and signals an EOF condition to the
1095the peer. 1103the peer.
1096 1104
1097You can rely on the normal read queue and C<on_eof> handling 1105You can rely on the normal read queue and C<on_eof> handling
… …
1773Note that AnyEvent::Handle will automatically C<start_read> for you when 1781Note that AnyEvent::Handle will automatically C<start_read> for you when
1774you change the C<on_read> callback or push/unshift a read callback, and it 1782you change the C<on_read> callback or push/unshift a read callback, and it
1775will automatically C<stop_read> for you when neither C<on_read> is set nor 1783will automatically C<stop_read> for you when neither C<on_read> is set nor
1776there are any read requests in the queue. 1784there are any read requests in the queue.
1777 1785
1778These methods will have no effect when in TLS mode (as TLS doesn't support 1786In older versions of this module (<= 5.3), these methods had no effect,
1779half-duplex connections). 1787as TLS does not support half-duplex connections. In current versions they
1788work as expected, as this behaviour is required to avoid certain resource
1789attacks, where the program would be forced to read (and buffer) arbitrary
1790amounts of data before being able to send some data. The drawback is that
1791some readings of the the SSL/TLS specifications basically require this
1792attack to be working, as SSL/TLS implementations might stall sending data
1793during a rehandshake.
1794
1795As a guideline, during the initial handshake, you should not stop reading,
1796and as a client, it might cause problems, depending on your applciation.
1780 1797
1781=cut 1798=cut
1782 1799
1783sub stop_read { 1800sub stop_read {
1784 my ($self) = @_; 1801 my ($self) = @_;
1785 1802
1786 delete $self->{_rw} unless $self->{tls}; 1803 delete $self->{_rw};
1787} 1804}
1788 1805
1789sub start_read { 1806sub start_read {
1790 my ($self) = @_; 1807 my ($self) = @_;
1791 1808
… …
2041 if $self->{tls} > 0; 2058 if $self->{tls} > 0;
2042 2059
2043 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)}; 2060 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
2044} 2061}
2045 2062
2063=item $handle->resettls
2064
2065This rarely-used method simply resets and TLS state on the handle, usually
2066causing data loss.
2067
2068One case where it may be useful is when you want to skip over the data in
2069the stream but you are not interested in interpreting it, so data loss is
2070no concern.
2071
2072=cut
2073
2074*resettls = \&_freetls;
2075
2046sub DESTROY { 2076sub DESTROY {
2047 my ($self) = @_; 2077 my ($self) = @_;
2048 2078
2049 &_freetls; 2079 &_freetls;
2050 2080

Diff Legend

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