… | |
… | |
75 | } |
75 | } |
76 | |
76 | |
77 | \&$func |
77 | \&$func |
78 | } |
78 | } |
79 | |
79 | |
|
|
80 | sub MAX_READ_SIZE() { 131072 } |
|
|
81 | |
80 | =head1 METHODS |
82 | =head1 METHODS |
81 | |
83 | |
82 | =over 4 |
84 | =over 4 |
83 | |
85 | |
84 | =item $handle = B<new> AnyEvent::Handle fh => $filehandle, key => value... |
86 | =item $handle = B<new> AnyEvent::Handle fh => $filehandle, key => value... |
… | |
… | |
112 | =over 4 |
114 | =over 4 |
113 | |
115 | |
114 | =item on_prepare => $cb->($handle) |
116 | =item on_prepare => $cb->($handle) |
115 | |
117 | |
116 | This (rarely used) callback is called before a new connection is |
118 | This (rarely used) callback is called before a new connection is |
117 | attempted, but after the file handle has been created. It could be used to |
119 | attempted, but after the file handle has been created (you can access that |
|
|
120 | file handle via C<< $handle->{fh} >>). It could be used to prepare the |
118 | prepare the file handle with parameters required for the actual connect |
121 | file handle with parameters required for the actual connect (as opposed to |
119 | (as opposed to settings that can be changed when the connection is already |
122 | settings that can be changed when the connection is already established). |
120 | established). |
|
|
121 | |
123 | |
122 | The return value of this callback should be the connect timeout value in |
124 | The return value of this callback should be the connect timeout value in |
123 | seconds (or C<0>, or C<undef>, or the empty list, to indicate that the |
125 | seconds (or C<0>, or C<undef>, or the empty list, to indicate that the |
124 | default timeout is to be used). |
126 | default timeout is to be used). |
125 | |
127 | |
… | |
… | |
157 | |
159 | |
158 | Some errors are fatal (which is indicated by C<$fatal> being true). On |
160 | Some errors are fatal (which is indicated by C<$fatal> being true). On |
159 | fatal errors the handle object will be destroyed (by a call to C<< -> |
161 | fatal errors the handle object will be destroyed (by a call to C<< -> |
160 | destroy >>) after invoking the error callback (which means you are free to |
162 | destroy >>) after invoking the error callback (which means you are free to |
161 | examine the handle object). Examples of fatal errors are an EOF condition |
163 | examine the handle object). Examples of fatal errors are an EOF condition |
162 | with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors. In |
164 | with active (but unsatisfiable) read watchers (C<EPIPE>) or I/O errors. In |
163 | cases where the other side can close the connection at will, it is |
165 | cases where the other side can close the connection at will, it is |
164 | often easiest to not report C<EPIPE> errors in this callback. |
166 | often easiest to not report C<EPIPE> errors in this callback. |
165 | |
167 | |
166 | AnyEvent::Handle tries to find an appropriate error code for you to check |
168 | AnyEvent::Handle tries to find an appropriate error code for you to check |
167 | against, but in some cases (TLS errors), this does not work well. It is |
169 | against, but in some cases (TLS errors), this does not work well. It is |
… | |
… | |
276 | For example, a server accepting connections from untrusted sources should |
278 | For example, a server accepting connections from untrusted sources should |
277 | be configured to accept only so-and-so much data that it cannot act on |
279 | be configured to accept only so-and-so much data that it cannot act on |
278 | (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 |
279 | amount of data without a callback ever being called as long as the line |
281 | amount of data without a callback ever being called as long as the line |
280 | isn't finished). |
282 | isn't finished). |
|
|
283 | |
|
|
284 | =item wbuf_max => <bytes> |
|
|
285 | |
|
|
286 | If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>) |
|
|
287 | when the write buffer ever (strictly) exceeds this size. This is useful to |
|
|
288 | avoid some forms of denial-of-service attacks. |
|
|
289 | |
|
|
290 | Although the units of this parameter is bytes, this is the I<raw> number |
|
|
291 | of bytes not yet accepted by the kernel. This can make a difference when |
|
|
292 | you e.g. use TLS, as TLS typically makes your write data larger (but it |
|
|
293 | can also make it smaller due to compression). |
|
|
294 | |
|
|
295 | As an example of when this limit is useful, take a chat server that sends |
|
|
296 | chat messages to a client. If the client does not read those in a timely |
|
|
297 | manner then the send buffer in the server would grow unbounded. |
281 | |
298 | |
282 | =item autocork => <boolean> |
299 | =item autocork => <boolean> |
283 | |
300 | |
284 | When disabled (the default), C<push_write> will try to immediately |
301 | When disabled (the default), C<push_write> will try to immediately |
285 | write the data to the handle if possible. This avoids having to register |
302 | write the data to the handle if possible. This avoids having to register |
… | |
… | |
337 | already have occured on BSD systems), but at least it will protect you |
354 | already have occured on BSD systems), but at least it will protect you |
338 | from most attacks. |
355 | from most attacks. |
339 | |
356 | |
340 | =item read_size => <bytes> |
357 | =item read_size => <bytes> |
341 | |
358 | |
342 | The default read block size (the number of bytes this module will |
359 | The initial read block size, the number of bytes this module will try to |
343 | try to read during each loop iteration, which affects memory |
360 | read during each loop iteration. Each handle object will consume at least |
344 | requirements). Default: C<8192>. |
361 | this amount of memory for the read buffer as well, so when handling many |
|
|
362 | connections requirements). See also C<max_read_size>. Default: C<2048>. |
|
|
363 | |
|
|
364 | =item max_read_size => <bytes> |
|
|
365 | |
|
|
366 | The maximum read buffer size used by the dynamic adjustment |
|
|
367 | algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in |
|
|
368 | one go it will double C<read_size> up to the maximum given by this |
|
|
369 | option. Default: C<131072> or C<read_size>, whichever is higher. |
345 | |
370 | |
346 | =item low_water_mark => <bytes> |
371 | =item low_water_mark => <bytes> |
347 | |
372 | |
348 | Sets the number of bytes (default: C<0>) that make up an "empty" write |
373 | Sets the number of bytes (default: C<0>) that make up an "empty" write |
349 | buffer: If the buffer reaches this size or gets even samller it is |
374 | buffer: If the buffer reaches this size or gets even samller it is |
… | |
… | |
412 | Use the C<< ->starttls >> method if you need to start TLS negotiation later. |
437 | Use the C<< ->starttls >> method if you need to start TLS negotiation later. |
413 | |
438 | |
414 | =item tls_ctx => $anyevent_tls |
439 | =item tls_ctx => $anyevent_tls |
415 | |
440 | |
416 | Use the given C<AnyEvent::TLS> object to create the new TLS connection |
441 | Use the given C<AnyEvent::TLS> object to create the new TLS connection |
417 | (unless a connection object was specified directly). If this parameter is |
442 | (unless a connection object was specified directly). If this |
418 | missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. |
443 | parameter is missing (or C<undef>), then AnyEvent::Handle will use |
|
|
444 | C<AnyEvent::Handle::TLS_CTX>. |
419 | |
445 | |
420 | Instead of an object, you can also specify a hash reference with C<< key |
446 | Instead of an object, you can also specify a hash reference with C<< key |
421 | => 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 |
422 | new TLS context object. |
448 | new TLS context object. |
423 | |
449 | |
… | |
… | |
491 | AnyEvent::Socket::tcp_connect ( |
517 | AnyEvent::Socket::tcp_connect ( |
492 | $self->{connect}[0], |
518 | $self->{connect}[0], |
493 | $self->{connect}[1], |
519 | $self->{connect}[1], |
494 | sub { |
520 | sub { |
495 | my ($fh, $host, $port, $retry) = @_; |
521 | my ($fh, $host, $port, $retry) = @_; |
|
|
522 | |
|
|
523 | delete $self->{_connect}; # no longer needed |
496 | |
524 | |
497 | if ($fh) { |
525 | if ($fh) { |
498 | $self->{fh} = $fh; |
526 | $self->{fh} = $fh; |
499 | |
527 | |
500 | delete $self->{_skip_drain_rbuf}; |
528 | delete $self->{_skip_drain_rbuf}; |
… | |
… | |
518 | }, |
546 | }, |
519 | sub { |
547 | sub { |
520 | local $self->{fh} = $_[0]; |
548 | local $self->{fh} = $_[0]; |
521 | |
549 | |
522 | $self->{on_prepare} |
550 | $self->{on_prepare} |
523 | ? $self->{on_prepare}->($self) |
551 | ? $self->{on_prepare}->($self) |
524 | : () |
552 | : () |
525 | } |
553 | } |
526 | ); |
554 | ); |
527 | } |
555 | } |
528 | |
556 | |
… | |
… | |
545 | AnyEvent::Util::fh_nonblocking $self->{fh}, 1; |
573 | AnyEvent::Util::fh_nonblocking $self->{fh}, 1; |
546 | |
574 | |
547 | $self->{_activity} = |
575 | $self->{_activity} = |
548 | $self->{_ractivity} = |
576 | $self->{_ractivity} = |
549 | $self->{_wactivity} = AE::now; |
577 | $self->{_wactivity} = AE::now; |
|
|
578 | |
|
|
579 | $self->{read_size} ||= 2048; |
|
|
580 | $self->{max_read_size} = $self->{read_size} |
|
|
581 | if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE); |
550 | |
582 | |
551 | $self->timeout (delete $self->{timeout} ) if $self->{timeout}; |
583 | $self->timeout (delete $self->{timeout} ) if $self->{timeout}; |
552 | $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout}; |
584 | $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout}; |
553 | $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout}; |
585 | $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout}; |
554 | |
586 | |
… | |
… | |
644 | =cut |
676 | =cut |
645 | |
677 | |
646 | sub no_delay { |
678 | sub no_delay { |
647 | $_[0]{no_delay} = $_[1]; |
679 | $_[0]{no_delay} = $_[1]; |
648 | |
680 | |
649 | eval { |
|
|
650 | local $SIG{__DIE__}; |
|
|
651 | setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1] |
681 | setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1] |
652 | if $_[0]{fh}; |
682 | if $_[0]{fh}; |
653 | }; |
|
|
654 | } |
683 | } |
655 | |
684 | |
656 | =item $handle->keepalive ($boolean) |
685 | =item $handle->keepalive ($boolean) |
657 | |
686 | |
658 | Enables or disables the C<keepalive> setting (see constructor argument of |
687 | Enables or disables the C<keepalive> setting (see constructor argument of |
… | |
… | |
726 | |
755 | |
727 | =item $handle->rbuf_max ($max_octets) |
756 | =item $handle->rbuf_max ($max_octets) |
728 | |
757 | |
729 | Configures the C<rbuf_max> setting (C<undef> disables it). |
758 | Configures the C<rbuf_max> setting (C<undef> disables it). |
730 | |
759 | |
|
|
760 | =item $handle->wbuf_max ($max_octets) |
|
|
761 | |
|
|
762 | Configures the C<wbuf_max> setting (C<undef> disables it). |
|
|
763 | |
731 | =cut |
764 | =cut |
732 | |
765 | |
733 | sub rbuf_max { |
766 | sub rbuf_max { |
734 | $_[0]{rbuf_max} = $_[1]; |
767 | $_[0]{rbuf_max} = $_[1]; |
|
|
768 | } |
|
|
769 | |
|
|
770 | sub rbuf_max { |
|
|
771 | $_[0]{wbuf_max} = $_[1]; |
735 | } |
772 | } |
736 | |
773 | |
737 | ############################################################################# |
774 | ############################################################################# |
738 | |
775 | |
739 | =item $handle->timeout ($seconds) |
776 | =item $handle->timeout ($seconds) |
… | |
… | |
767 | $_[0]{$on_timeout} = $_[1]; |
804 | $_[0]{$on_timeout} = $_[1]; |
768 | }; |
805 | }; |
769 | |
806 | |
770 | *$timeout = sub { |
807 | *$timeout = sub { |
771 | my ($self, $new_value) = @_; |
808 | my ($self, $new_value) = @_; |
|
|
809 | |
|
|
810 | $new_value >= 0 |
|
|
811 | or Carp::croak "AnyEvent::Handle->$timeout called with negative timeout ($new_value), caught"; |
772 | |
812 | |
773 | $self->{$timeout} = $new_value; |
813 | $self->{$timeout} = $new_value; |
774 | delete $self->{$tw}; &$cb; |
814 | delete $self->{$tw}; &$cb; |
775 | }; |
815 | }; |
776 | |
816 | |
… | |
… | |
856 | 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}); |
857 | } |
897 | } |
858 | |
898 | |
859 | =item $handle->push_write ($data) |
899 | =item $handle->push_write ($data) |
860 | |
900 | |
861 | Queues the given scalar to be written. You can push as much data as you |
901 | Queues the given scalar to be written. You can push as much data as |
862 | want (only limited by the available memory), as C<AnyEvent::Handle> |
902 | you want (only limited by the available memory and C<wbuf_max>), as |
863 | buffers it independently of the kernel. |
903 | C<AnyEvent::Handle> buffers it independently of the kernel. |
864 | |
904 | |
865 | This method may invoke callbacks (and therefore the handle might be |
905 | This method may invoke callbacks (and therefore the handle might be |
866 | destroyed after it returns). |
906 | destroyed after it returns). |
867 | |
907 | |
868 | =cut |
908 | =cut |
… | |
… | |
896 | $cb->() unless $self->{autocork}; |
936 | $cb->() unless $self->{autocork}; |
897 | |
937 | |
898 | # if still data left in wbuf, we need to poll |
938 | # if still data left in wbuf, we need to poll |
899 | $self->{_ww} = AE::io $self->{fh}, 1, $cb |
939 | $self->{_ww} = AE::io $self->{fh}, 1, $cb |
900 | 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 | } |
901 | }; |
948 | }; |
902 | } |
949 | } |
903 | |
950 | |
904 | our %WH; |
951 | our %WH; |
905 | |
952 | |
… | |
… | |
1745 | unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) { |
1792 | unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) { |
1746 | Scalar::Util::weaken $self; |
1793 | Scalar::Util::weaken $self; |
1747 | |
1794 | |
1748 | $self->{_rw} = AE::io $self->{fh}, 0, sub { |
1795 | $self->{_rw} = AE::io $self->{fh}, 0, sub { |
1749 | my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf}); |
1796 | my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf}); |
1750 | my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; |
1797 | my $len = sysread $self->{fh}, $$rbuf, $self->{read_size}, length $$rbuf; |
1751 | |
1798 | |
1752 | if ($len > 0) { |
1799 | if ($len > 0) { |
1753 | $self->{_activity} = $self->{_ractivity} = AE::now; |
1800 | $self->{_activity} = $self->{_ractivity} = AE::now; |
1754 | |
1801 | |
1755 | if ($self->{tls}) { |
1802 | if ($self->{tls}) { |
1756 | Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf); |
1803 | Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf); |
1757 | |
1804 | |
1758 | &_dotls ($self); |
1805 | &_dotls ($self); |
1759 | } else { |
1806 | } else { |
1760 | $self->_drain_rbuf; |
1807 | $self->_drain_rbuf; |
|
|
1808 | } |
|
|
1809 | |
|
|
1810 | if ($len == $self->{read_size}) { |
|
|
1811 | $self->{read_size} *= 2; |
|
|
1812 | $self->{read_size} = $self->{max_read_size} || MAX_READ_SIZE |
|
|
1813 | if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE); |
1761 | } |
1814 | } |
1762 | |
1815 | |
1763 | } elsif (defined $len) { |
1816 | } elsif (defined $len) { |
1764 | delete $self->{_rw}; |
1817 | delete $self->{_rw}; |
1765 | $self->{_eof} = 1; |
1818 | $self->{_eof} = 1; |
… | |
… | |
2006 | push @linger, AE::io $fh, 1, sub { |
2059 | push @linger, AE::io $fh, 1, sub { |
2007 | my $len = syswrite $fh, $wbuf, length $wbuf; |
2060 | my $len = syswrite $fh, $wbuf, length $wbuf; |
2008 | |
2061 | |
2009 | if ($len > 0) { |
2062 | if ($len > 0) { |
2010 | substr $wbuf, 0, $len, ""; |
2063 | substr $wbuf, 0, $len, ""; |
2011 | } else { |
2064 | } elsif (defined $len || ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK)) { |
2012 | @linger = (); # end |
2065 | @linger = (); # end |
2013 | } |
2066 | } |
2014 | }; |
2067 | }; |
2015 | push @linger, AE::timer $linger, 0, sub { |
2068 | push @linger, AE::timer $linger, 0, sub { |
2016 | @linger = (); |
2069 | @linger = (); |
… | |
… | |
2112 | |
2165 | |
2113 | It is only safe to "forget" the reference inside EOF or error callbacks, |
2166 | It is only safe to "forget" the reference inside EOF or error callbacks, |
2114 | from within all other callbacks, you need to explicitly call the C<< |
2167 | from within all other callbacks, you need to explicitly call the C<< |
2115 | ->destroy >> method. |
2168 | ->destroy >> method. |
2116 | |
2169 | |
|
|
2170 | =item Why is my C<on_eof> callback never called? |
|
|
2171 | |
|
|
2172 | Probably because your C<on_error> callback is being called instead: When |
|
|
2173 | you have outstanding requests in your read queue, then an EOF is |
|
|
2174 | considered an error as you clearly expected some data. |
|
|
2175 | |
|
|
2176 | To avoid this, make sure you have an empty read queue whenever your handle |
|
|
2177 | is supposed to be "idle" (i.e. connection closes are O.K.). You cna set |
|
|
2178 | an C<on_read> handler that simply pushes the first read requests in the |
|
|
2179 | queue. |
|
|
2180 | |
|
|
2181 | See also the next question, which explains this in a bit more detail. |
|
|
2182 | |
|
|
2183 | =item How can I serve requests in a loop? |
|
|
2184 | |
|
|
2185 | Most protocols consist of some setup phase (authentication for example) |
|
|
2186 | followed by a request handling phase, where the server waits for requests |
|
|
2187 | and handles them, in a loop. |
|
|
2188 | |
|
|
2189 | There are two important variants: The first (traditional, better) variant |
|
|
2190 | handles requests until the server gets some QUIT command, causing it to |
|
|
2191 | close the connection first (highly desirable for a busy TCP server). A |
|
|
2192 | client dropping the connection is an error, which means this variant can |
|
|
2193 | detect an unexpected detection close. |
|
|
2194 | |
|
|
2195 | To handle this case, always make sure you have a on-empty read queue, by |
|
|
2196 | pushing 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 | |
|
|
2212 | By always having an outstanding C<push_read>, the handle always expects |
|
|
2213 | some data and raises the C<EPIPE> error when the connction is dropped |
|
|
2214 | unexpectedly. |
|
|
2215 | |
|
|
2216 | The second variant is a protocol where the client can drop the connection |
|
|
2217 | at any time. For TCP, this means that the server machine may run out of |
|
|
2218 | sockets easier, and in general, it means you cnanot distinguish a protocl |
|
|
2219 | failure/client crash from a normal connection close. Nevertheless, these |
|
|
2220 | kinds of protocols are common (and sometimes even the best solution to the |
|
|
2221 | problem). |
|
|
2222 | |
|
|
2223 | Having an outstanding read request at all times is possible if you ignore |
|
|
2224 | C<EPIPE> errors, but this doesn't help with when the client drops the |
|
|
2225 | connection during a request, which would still be an error. |
|
|
2226 | |
|
|
2227 | A better solution is to push the initial request read in an C<on_read> |
|
|
2228 | callback. 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 |
|
|
2230 | error, but simply result in an C<on_eof> callback. It is also a bit slower |
|
|
2231 | and 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 | |
2117 | =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 |
2118 | reading? |
2251 | reading? |
2119 | |
2252 | |
2120 | Unlike, say, TCP, TLS connections do not consist of two independent |
2253 | Unlike, say, TCP, TLS connections do not consist of two independent |
2121 | communication channels, one for each direction. Or put differently, the |
2254 | communication channels, one for each direction. Or put differently, the |