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.208 by root, Sun Dec 5 11:41:45 2010 UTC vs.
Revision 1.214 by root, Sun Jan 16 17:12:27 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
… …
278For example, a server accepting connections from untrusted sources should 278For example, a server accepting connections from untrusted sources should
279be configured to accept only so-and-so much data that it cannot act on 279be configured to accept only so-and-so much data that it cannot act on
280(for example, when expecting a line, an attacker could send an unlimited 280(for example, when expecting a line, an attacker could send an unlimited
281amount of data without a callback ever being called as long as the line 281amount of data without a callback ever being called as long as the line
282isn't finished). 282isn't finished).
283
284=item wbuf_max => <bytes>
285
286If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
287when the write buffer ever (strictly) exceeds this size. This is useful to
288avoid some forms of denial-of-service attacks.
289
290Although the units of this parameter is bytes, this is the I<raw> number
291of bytes not yet accepted by the kernel. This can make a difference when
292you e.g. use TLS, as TLS typically makes your write data larger (but it
293can also make it smaller due to compression).
294
295As an example of when this limit is useful, take a chat server that sends
296chat messages to a client. If the client does not read those in a timely
297manner then the send buffer in the server would grow unbounded.
283 298
284=item autocork => <boolean> 299=item autocork => <boolean>
285 300
286When disabled (the default), C<push_write> will try to immediately 301When disabled (the default), C<push_write> will try to immediately
287write the data to the handle if possible. This avoids having to register 302write the data to the handle if possible. This avoids having to register
… …
531 }, 546 },
532 sub { 547 sub {
533 local $self->{fh} = $_[0]; 548 local $self->{fh} = $_[0];
534 549
535 $self->{on_prepare} 550 $self->{on_prepare}
536 ? $self->{on_prepare}->($self) 551 ? $self->{on_prepare}->($self)
537 : () 552 : ()
538 } 553 }
539 ); 554 );
540 } 555 }
541 556
… …
740 755
741=item $handle->rbuf_max ($max_octets) 756=item $handle->rbuf_max ($max_octets)
742 757
743Configures the C<rbuf_max> setting (C<undef> disables it). 758Configures the C<rbuf_max> setting (C<undef> disables it).
744 759
760=item $handle->wbuf_max ($max_octets)
761
762Configures the C<wbuf_max> setting (C<undef> disables it).
763
745=cut 764=cut
746 765
747sub rbuf_max { 766sub rbuf_max {
748 $_[0]{rbuf_max} = $_[1]; 767 $_[0]{rbuf_max} = $_[1];
768}
769
770sub rbuf_max {
771 $_[0]{wbuf_max} = $_[1];
749} 772}
750 773
751############################################################################# 774#############################################################################
752 775
753=item $handle->timeout ($seconds) 776=item $handle->timeout ($seconds)
… …
873 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf}); 896 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
874} 897}
875 898
876=item $handle->push_write ($data) 899=item $handle->push_write ($data)
877 900
878Queues the given scalar to be written. You can push as much data as you 901Queues the given scalar to be written. You can push as much data as
879want (only limited by the available memory), as C<AnyEvent::Handle> 902you want (only limited by the available memory and C<wbuf_max>), as
880buffers it independently of the kernel. 903C<AnyEvent::Handle> buffers it independently of the kernel.
881 904
882This method may invoke callbacks (and therefore the handle might be 905This method may invoke callbacks (and therefore the handle might be
883destroyed after it returns). 906destroyed after it returns).
884 907
885=cut 908=cut
… …
913 $cb->() unless $self->{autocork}; 936 $cb->() unless $self->{autocork};
914 937
915 # if still data left in wbuf, we need to poll 938 # if still data left in wbuf, we need to poll
916 $self->{_ww} = AE::io $self->{fh}, 1, $cb 939 $self->{_ww} = AE::io $self->{fh}, 1, $cb
917 if length $self->{wbuf}; 940 if length $self->{wbuf};
941
942 if (
943 defined $self->{wbuf_max}
944 && $self->{wbuf_max} < length $self->{wbuf}
945 ) {
946 $self->_error (Errno::ENOSPC, 1), return;
947 }
918 }; 948 };
919} 949}
920 950
921our %WH; 951our %WH;
922 952
… …
1057before it was actually written. One way to do that is to replace your 1087before it was actually written. One way to do that is to replace your
1058C<on_drain> handler by a callback that shuts down the socket (and set 1088C<on_drain> handler by a callback that shuts down the socket (and set
1059C<low_water_mark> to C<0>). This method is a shorthand for just that, and 1089C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1060replaces the C<on_drain> callback with: 1090replaces the C<on_drain> callback with:
1061 1091
1062 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 1092 sub { shutdown $_[0]{fh}, 1 }
1063 1093
1064This simply shuts down the write side and signals an EOF condition to the 1094This simply shuts down the write side and signals an EOF condition to the
1065the peer. 1095the peer.
1066 1096
1067You can rely on the normal read queue and C<on_eof> handling 1097You can rely on the normal read queue and C<on_eof> handling
… …
1743Note that AnyEvent::Handle will automatically C<start_read> for you when 1773Note that AnyEvent::Handle will automatically C<start_read> for you when
1744you change the C<on_read> callback or push/unshift a read callback, and it 1774you change the C<on_read> callback or push/unshift a read callback, and it
1745will automatically C<stop_read> for you when neither C<on_read> is set nor 1775will automatically C<stop_read> for you when neither C<on_read> is set nor
1746there are any read requests in the queue. 1776there are any read requests in the queue.
1747 1777
1748These methods will have no effect when in TLS mode (as TLS doesn't support 1778In older versions of this module (<= 5.3), these methods had no effect,
1749half-duplex connections). 1779as TLS does not support half-duplex connections. In current versions they
1780work as expected, as this behaviour is required to avoid certain resource
1781attacks, where the program would be forced to read (and buffer) arbitrary
1782amounts of data before being able to send some data. The drawback is that
1783some readings of the the SSL/TLS specifications basically require this
1784attack to be working, as SSL/TLS implementations might stall sending data
1785during a rehandshake.
1786
1787As a guideline, during the initial handshake, you should not stop reading,
1788and as a client, it might cause problems, depending on your applciation.
1750 1789
1751=cut 1790=cut
1752 1791
1753sub stop_read { 1792sub stop_read {
1754 my ($self) = @_; 1793 my ($self) = @_;
1755 1794
1756 delete $self->{_rw} unless $self->{tls}; 1795 delete $self->{_rw};
1757} 1796}
1758 1797
1759sub start_read { 1798sub start_read {
1760 my ($self) = @_; 1799 my ($self) = @_;
1761 1800

Diff Legend

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