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.204 by root, Mon Nov 15 03:29:17 2010 UTC vs.
Revision 1.212 by root, Fri Dec 31 04:50:44 2010 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
… …
422Use the C<< ->starttls >> method if you need to start TLS negotiation later. 437Use the C<< ->starttls >> method if you need to start TLS negotiation later.
423 438
424=item tls_ctx => $anyevent_tls 439=item tls_ctx => $anyevent_tls
425 440
426Use the given C<AnyEvent::TLS> object to create the new TLS connection 441Use the given C<AnyEvent::TLS> object to create the new TLS connection
427(unless a connection object was specified directly). If this parameter is 442(unless a connection object was specified directly). If this
428missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 443parameter is missing (or C<undef>), then AnyEvent::Handle will use
444C<AnyEvent::Handle::TLS_CTX>.
429 445
430Instead of an object, you can also specify a hash reference with C<< key 446Instead of an object, you can also specify a hash reference with C<< key
431=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a 447=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
432new TLS context object. 448new TLS context object.
433 449
… …
501 AnyEvent::Socket::tcp_connect ( 517 AnyEvent::Socket::tcp_connect (
502 $self->{connect}[0], 518 $self->{connect}[0],
503 $self->{connect}[1], 519 $self->{connect}[1],
504 sub { 520 sub {
505 my ($fh, $host, $port, $retry) = @_; 521 my ($fh, $host, $port, $retry) = @_;
522
523 delete $self->{_connect}; # no longer needed
506 524
507 if ($fh) { 525 if ($fh) {
508 $self->{fh} = $fh; 526 $self->{fh} = $fh;
509 527
510 delete $self->{_skip_drain_rbuf}; 528 delete $self->{_skip_drain_rbuf};
… …
528 }, 546 },
529 sub { 547 sub {
530 local $self->{fh} = $_[0]; 548 local $self->{fh} = $_[0];
531 549
532 $self->{on_prepare} 550 $self->{on_prepare}
533 ? $self->{on_prepare}->($self) 551 ? $self->{on_prepare}->($self)
534 : () 552 : ()
535 } 553 }
536 ); 554 );
537 } 555 }
538 556
… …
737 755
738=item $handle->rbuf_max ($max_octets) 756=item $handle->rbuf_max ($max_octets)
739 757
740Configures the C<rbuf_max> setting (C<undef> disables it). 758Configures the C<rbuf_max> setting (C<undef> disables it).
741 759
760=item $handle->wbuf_max ($max_octets)
761
762Configures the C<wbuf_max> setting (C<undef> disables it).
763
742=cut 764=cut
743 765
744sub rbuf_max { 766sub rbuf_max {
745 $_[0]{rbuf_max} = $_[1]; 767 $_[0]{rbuf_max} = $_[1];
768}
769
770sub rbuf_max {
771 $_[0]{wbuf_max} = $_[1];
746} 772}
747 773
748############################################################################# 774#############################################################################
749 775
750=item $handle->timeout ($seconds) 776=item $handle->timeout ($seconds)
… …
870 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});
871} 897}
872 898
873=item $handle->push_write ($data) 899=item $handle->push_write ($data)
874 900
875Queues 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
876want (only limited by the available memory), as C<AnyEvent::Handle> 902you want (only limited by the available memory and C<wbuf_max>), as
877buffers it independently of the kernel. 903C<AnyEvent::Handle> buffers it independently of the kernel.
878 904
879This method may invoke callbacks (and therefore the handle might be 905This method may invoke callbacks (and therefore the handle might be
880destroyed after it returns). 906destroyed after it returns).
881 907
882=cut 908=cut
… …
910 $cb->() unless $self->{autocork}; 936 $cb->() unless $self->{autocork};
911 937
912 # if still data left in wbuf, we need to poll 938 # if still data left in wbuf, we need to poll
913 $self->{_ww} = AE::io $self->{fh}, 1, $cb 939 $self->{_ww} = AE::io $self->{fh}, 1, $cb
914 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 }
915 }; 948 };
916} 949}
917 950
918our %WH; 951our %WH;
919 952
… …
2132 2165
2133It is only safe to "forget" the reference inside EOF or error callbacks, 2166It is only safe to "forget" the reference inside EOF or error callbacks,
2134from within all other callbacks, you need to explicitly call the C<< 2167from within all other callbacks, you need to explicitly call the C<<
2135->destroy >> method. 2168->destroy >> method.
2136 2169
2170=item Why is my C<on_eof> callback never called?
2171
2172Probably because your C<on_error> callback is being called instead: When
2173you have outstanding requests in your read queue, then an EOF is
2174considered an error as you clearly expected some data.
2175
2176To avoid this, make sure you have an empty read queue whenever your handle
2177is supposed to be "idle" (i.e. connection closes are O.K.). You cna set
2178an C<on_read> handler that simply pushes the first read requests in the
2179queue.
2180
2181See also the next question, which explains this in a bit more detail.
2182
2183=item How can I serve requests in a loop?
2184
2185Most protocols consist of some setup phase (authentication for example)
2186followed by a request handling phase, where the server waits for requests
2187and handles them, in a loop.
2188
2189There are two important variants: The first (traditional, better) variant
2190handles requests until the server gets some QUIT command, causing it to
2191close the connection first (highly desirable for a busy TCP server). A
2192client dropping the connection is an error, which means this variant can
2193detect an unexpected detection close.
2194
2195To handle this case, always make sure you have a on-empty read queue, by
2196pushing the "read request start" handler on it:
2197
2198 # we assume a request starts with a single line
2199 my @start_request; @start_request = (line => sub {
2200 my ($hdl, $line) = @_;
2201
2202 ... handle request
2203
2204 # push next request read, possibly from a nested callback
2205 $hdl->push_read (@start_request);
2206 });
2207
2208 # auth done, now go into request handling loop
2209 # now push the first @start_request
2210 $hdl->push_read (@start_request);
2211
2212By always having an outstanding C<push_read>, the handle always expects
2213some data and raises the C<EPIPE> error when the connction is dropped
2214unexpectedly.
2215
2216The second variant is a protocol where the client can drop the connection
2217at any time. For TCP, this means that the server machine may run out of
2218sockets easier, and in general, it means you cnanot distinguish a protocl
2219failure/client crash from a normal connection close. Nevertheless, these
2220kinds of protocols are common (and sometimes even the best solution to the
2221problem).
2222
2223Having an outstanding read request at all times is possible if you ignore
2224C<EPIPE> errors, but this doesn't help with when the client drops the
2225connection during a request, which would still be an error.
2226
2227A better solution is to push the initial request read in an C<on_read>
2228callback. This avoids an error, as when the server doesn't expect data
2229(i.e. is idly waiting for the next request, an EOF will not raise an
2230error, but simply result in an C<on_eof> callback. It is also a bit slower
2231and simpler:
2232
2233 # auth done, now go into request handling loop
2234 $hdl->on_read (sub {
2235 my ($hdl) = @_;
2236
2237 # called each time we receive data but the read queue is empty
2238 # simply start read the request
2239
2240 $hdl->push_read (line => sub {
2241 my ($hdl, $line) = @_;
2242
2243 ... handle request
2244
2245 # do nothing special when the request has been handled, just
2246 # let the request queue go empty.
2247 });
2248 });
2249
2137=item I get different callback invocations in TLS mode/Why can't I pause 2250=item I get different callback invocations in TLS mode/Why can't I pause
2138reading? 2251reading?
2139 2252
2140Unlike, say, TCP, TLS connections do not consist of two independent 2253Unlike, say, TCP, TLS connections do not consist of two independent
2141communication channels, one for each direction. Or put differently, the 2254communication channels, one for each direction. Or put differently, the

Diff Legend

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