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.207 by root, Mon Nov 15 22:29:36 2010 UTC vs.
Revision 1.232 by root, Fri Mar 30 03:11:17 2012 UTC

… …
11 11
12 my $hdl; $hdl = new AnyEvent::Handle 12 my $hdl; $hdl = new AnyEvent::Handle
13 fh => \*STDIN, 13 fh => \*STDIN,
14 on_error => sub { 14 on_error => sub {
15 my ($hdl, $fatal, $msg) = @_; 15 my ($hdl, $fatal, $msg) = @_;
16 warn "got error $msg\n"; 16 AE::log error => "Got error $msg!";
17 $hdl->destroy; 17 $hdl->destroy;
18 $cv->send; 18 $cv->send;
19 }; 19 };
20 20
21 # send some request line 21 # send some request line
22 $hdl->push_write ("getinfo\015\012"); 22 $hdl->push_write ("getinfo\015\012");
23 23
24 # read the response line 24 # read the response line
25 $hdl->push_read (line => sub { 25 $hdl->push_read (line => sub {
26 my ($hdl, $line) = @_; 26 my ($hdl, $line) = @_;
27 warn "got line <$line>\n"; 27 say "got line <$line>";
28 $cv->send; 28 $cv->send;
29 }); 29 });
30 30
31 $cv->recv; 31 $cv->recv;
32 32
… …
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
128=item on_connect => $cb->($handle, $host, $port, $retry->()) 128=item on_connect => $cb->($handle, $host, $port, $retry->())
129 129
130This callback is called when a connection has been successfully established. 130This callback is called when a connection has been successfully established.
131 131
132The peer's numeric host and port (the socket peername) are passed as 132The peer's numeric host and port (the socket peername) are passed as
133parameters, together with a retry callback. 133parameters, together with a retry callback. At the time it is called the
134read and write queues, EOF status, TLS status and similar properties of
135the handle will have been reset.
134 136
137It is not allowed to use the read or write queues while the handle object
138is connecting.
139
135If, for some reason, the handle is not acceptable, calling C<$retry> 140If, for some reason, the handle is not acceptable, calling C<$retry> will
136will continue with the next connection target (in case of multi-homed 141continue with the next connection target (in case of multi-homed hosts or
137hosts or SRV records there can be multiple connection endpoints). At the 142SRV records there can be multiple connection endpoints). The C<$retry>
138time it is called the read and write queues, eof status, tls status and 143callback can be invoked after the connect callback returns, i.e. one can
139similar properties of the handle will have been reset. 144start a handshake and then decide to retry with the next host if the
145handshake fails.
140 146
141In most cases, you should ignore the C<$retry> parameter. 147In most cases, you should ignore the C<$retry> parameter.
142 148
143=item on_connect_error => $cb->($handle, $message) 149=item on_connect_error => $cb->($handle, $message)
144 150
… …
224If an EOF condition has been detected but no C<on_eof> callback has been 230If an EOF condition has been detected but no C<on_eof> callback has been
225set, then a fatal error will be raised with C<$!> set to <0>. 231set, then a fatal error will be raised with C<$!> set to <0>.
226 232
227=item on_drain => $cb->($handle) 233=item on_drain => $cb->($handle)
228 234
229This sets the callback that is called when the write buffer becomes empty 235This sets the callback that is called once when the write buffer becomes
230(or immediately if the buffer is empty already). 236empty (and immediately when the handle object is created).
231 237
232To append to the write buffer, use the C<< ->push_write >> method. 238To append to the write buffer, use the C<< ->push_write >> method.
233 239
234This callback is useful when you don't want to put all of your write data 240This callback is useful when you don't want to put all of your write data
235into the queue at once, for example, when you want to write the contents 241into the queue at once, for example, when you want to write the contents
… …
247many seconds pass without a successful read or write on the underlying 253many 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 254file 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> 255will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT>
250error will be raised). 256error will be raised).
251 257
252There are three variants of the timeouts that work independently 258There are three variants of the timeouts that work independently of each
253of each other, for both read and write, just read, and just write: 259other, for both read and write (triggered when nothing was read I<OR>
260written), just read (triggered when nothing was read), and just write:
254C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks 261C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks
255C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions 262C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions
256C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>. 263C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>.
257 264
258Note that timeout processing is active even when you do not have 265Note 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 266outstanding read or write requests: If you plan to keep the connection
260idle then you should disable the timeout temporarily or ignore the timeout 267idle then you should disable the timeout temporarily or ignore the
261in the C<on_timeout> callback, in which case AnyEvent::Handle will simply 268timeout in the corresponding C<on_timeout> callback, in which case
262restart the timeout. 269AnyEvent::Handle will simply restart the timeout.
263 270
264Zero (the default) disables this timeout. 271Zero (the default) disables the corresponding timeout.
265 272
266=item on_timeout => $cb->($handle) 273=item on_timeout => $cb->($handle)
274
275=item on_rtimeout => $cb->($handle)
276
277=item on_wtimeout => $cb->($handle)
267 278
268Called whenever the inactivity timeout passes. If you return from this 279Called whenever the inactivity timeout passes. If you return from this
269callback, then the timeout will be reset as if some activity had happened, 280callback, then the timeout will be reset as if some activity had happened,
270so this condition is not fatal in any way. 281so this condition is not fatal in any way.
271 282
… …
278For example, a server accepting connections from untrusted sources should 289For example, a server accepting connections from untrusted sources should
279be configured to accept only so-and-so much data that it cannot act on 290be 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 291(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 292amount of data without a callback ever being called as long as the line
282isn't finished). 293isn't finished).
294
295=item wbuf_max => <bytes>
296
297If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
298when the write buffer ever (strictly) exceeds this size. This is useful to
299avoid some forms of denial-of-service attacks.
300
301Although the units of this parameter is bytes, this is the I<raw> number
302of bytes not yet accepted by the kernel. This can make a difference when
303you e.g. use TLS, as TLS typically makes your write data larger (but it
304can also make it smaller due to compression).
305
306As an example of when this limit is useful, take a chat server that sends
307chat messages to a client. If the client does not read those in a timely
308manner then the send buffer in the server would grow unbounded.
283 309
284=item autocork => <boolean> 310=item autocork => <boolean>
285 311
286When disabled (the default), C<push_write> will try to immediately 312When disabled (the default), C<push_write> will try to immediately
287write the data to the handle if possible. This avoids having to register 313write the data to the handle if possible. This avoids having to register
… …
339already have occured on BSD systems), but at least it will protect you 365already have occured on BSD systems), but at least it will protect you
340from most attacks. 366from most attacks.
341 367
342=item read_size => <bytes> 368=item read_size => <bytes>
343 369
344The initial read block size, the number of bytes this module will try to 370The initial read block size, the number of bytes this module will try
345read during each loop iteration. Each handle object will consume at least 371to read during each loop iteration. Each handle object will consume
346this amount of memory for the read buffer as well, so when handling many 372at least this amount of memory for the read buffer as well, so when
347connections requirements). See also C<max_read_size>. Default: C<2048>. 373handling many connections watch out for memory requirements). See also
374C<max_read_size>. Default: C<2048>.
348 375
349=item max_read_size => <bytes> 376=item max_read_size => <bytes>
350 377
351The maximum read buffer size used by the dynamic adjustment 378The maximum read buffer size used by the dynamic adjustment
352algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in 379algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in
… …
521 }); 548 });
522 549
523 } else { 550 } else {
524 if ($self->{on_connect_error}) { 551 if ($self->{on_connect_error}) {
525 $self->{on_connect_error}($self, "$!"); 552 $self->{on_connect_error}($self, "$!");
526 $self->destroy; 553 $self->destroy if $self;
527 } else { 554 } else {
528 $self->_error ($!, 1); 555 $self->_error ($!, 1);
529 } 556 }
530 } 557 }
531 }, 558 },
532 sub { 559 sub {
533 local $self->{fh} = $_[0]; 560 local $self->{fh} = $_[0];
534 561
535 $self->{on_prepare} 562 $self->{on_prepare}
536 ? $self->{on_prepare}->($self) 563 ? $self->{on_prepare}->($self)
537 : () 564 : ()
538 } 565 }
539 ); 566 );
540 } 567 }
541 568
… …
740 767
741=item $handle->rbuf_max ($max_octets) 768=item $handle->rbuf_max ($max_octets)
742 769
743Configures the C<rbuf_max> setting (C<undef> disables it). 770Configures the C<rbuf_max> setting (C<undef> disables it).
744 771
772=item $handle->wbuf_max ($max_octets)
773
774Configures the C<wbuf_max> setting (C<undef> disables it).
775
745=cut 776=cut
746 777
747sub rbuf_max { 778sub rbuf_max {
748 $_[0]{rbuf_max} = $_[1]; 779 $_[0]{rbuf_max} = $_[1];
749} 780}
750 781
782sub wbuf_max {
783 $_[0]{wbuf_max} = $_[1];
784}
785
751############################################################################# 786#############################################################################
752 787
753=item $handle->timeout ($seconds) 788=item $handle->timeout ($seconds)
754 789
755=item $handle->rtimeout ($seconds) 790=item $handle->rtimeout ($seconds)
756 791
757=item $handle->wtimeout ($seconds) 792=item $handle->wtimeout ($seconds)
758 793
759Configures (or disables) the inactivity timeout. 794Configures (or disables) the inactivity timeout.
795
796The timeout will be checked instantly, so this method might destroy the
797handle before it returns.
760 798
761=item $handle->timeout_reset 799=item $handle->timeout_reset
762 800
763=item $handle->rtimeout_reset 801=item $handle->rtimeout_reset
764 802
… …
848 886
849The write queue is very simple: you can add data to its end, and 887The write queue is very simple: you can add data to its end, and
850AnyEvent::Handle will automatically try to get rid of it for you. 888AnyEvent::Handle will automatically try to get rid of it for you.
851 889
852When data could be written and the write buffer is shorter then the low 890When data could be written and the write buffer is shorter then the low
853water mark, the C<on_drain> callback will be invoked. 891water mark, the C<on_drain> callback will be invoked once.
854 892
855=over 4 893=over 4
856 894
857=item $handle->on_drain ($cb) 895=item $handle->on_drain ($cb)
858 896
… …
873 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf}); 911 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
874} 912}
875 913
876=item $handle->push_write ($data) 914=item $handle->push_write ($data)
877 915
878Queues the given scalar to be written. You can push as much data as you 916Queues the given scalar to be written. You can push as much data as
879want (only limited by the available memory), as C<AnyEvent::Handle> 917you want (only limited by the available memory and C<wbuf_max>), as
880buffers it independently of the kernel. 918C<AnyEvent::Handle> buffers it independently of the kernel.
881 919
882This method may invoke callbacks (and therefore the handle might be 920This method may invoke callbacks (and therefore the handle might be
883destroyed after it returns). 921destroyed after it returns).
884 922
885=cut 923=cut
… …
913 $cb->() unless $self->{autocork}; 951 $cb->() unless $self->{autocork};
914 952
915 # if still data left in wbuf, we need to poll 953 # if still data left in wbuf, we need to poll
916 $self->{_ww} = AE::io $self->{fh}, 1, $cb 954 $self->{_ww} = AE::io $self->{fh}, 1, $cb
917 if length $self->{wbuf}; 955 if length $self->{wbuf};
956
957 if (
958 defined $self->{wbuf_max}
959 && $self->{wbuf_max} < length $self->{wbuf}
960 ) {
961 $self->_error (Errno::ENOSPC, 1), return;
962 }
918 }; 963 };
919} 964}
920 965
921our %WH; 966our %WH;
922 967
… …
1042=cut 1087=cut
1043 1088
1044register_write_type storable => sub { 1089register_write_type storable => sub {
1045 my ($self, $ref) = @_; 1090 my ($self, $ref) = @_;
1046 1091
1047 require Storable; 1092 require Storable unless $Storable::VERSION;
1048 1093
1049 pack "w/a*", Storable::nfreeze ($ref) 1094 pack "w/a*", Storable::nfreeze ($ref)
1050}; 1095};
1051 1096
1052=back 1097=back
… …
1057before it was actually written. One way to do that is to replace your 1102before 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 1103C<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 1104C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1060replaces the C<on_drain> callback with: 1105replaces the C<on_drain> callback with:
1061 1106
1062 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 1107 sub { shutdown $_[0]{fh}, 1 }
1063 1108
1064This simply shuts down the write side and signals an EOF condition to the 1109This simply shuts down the write side and signals an EOF condition to the
1065the peer. 1110the peer.
1066 1111
1067You can rely on the normal read queue and C<on_eof> handling 1112You can rely on the normal read queue and C<on_eof> handling
… …
1089 1134
1090Whenever the given C<type> is used, C<push_write> will the function with 1135Whenever the given C<type> is used, C<push_write> will the function with
1091the handle object and the remaining arguments. 1136the handle object and the remaining arguments.
1092 1137
1093The function is supposed to return a single octet string that will be 1138The function is supposed to return a single octet string that will be
1094appended to the write buffer, so you cna mentally treat this function as a 1139appended to the write buffer, so you can mentally treat this function as a
1095"arguments to on-the-wire-format" converter. 1140"arguments to on-the-wire-format" converter.
1096 1141
1097Example: implement a custom write type C<join> that joins the remaining 1142Example: implement a custom write type C<join> that joins the remaining
1098arguments using the first one. 1143arguments using the first one.
1099 1144
… …
1393data. 1438data.
1394 1439
1395Example: read 2 bytes. 1440Example: read 2 bytes.
1396 1441
1397 $handle->push_read (chunk => 2, sub { 1442 $handle->push_read (chunk => 2, sub {
1398 warn "yay ", unpack "H*", $_[1]; 1443 say "yay " . unpack "H*", $_[1];
1399 }); 1444 });
1400 1445
1401=cut 1446=cut
1402 1447
1403register_read_type chunk => sub { 1448register_read_type chunk => sub {
… …
1437 if (@_ < 3) { 1482 if (@_ < 3) {
1438 # this is more than twice as fast as the generic code below 1483 # this is more than twice as fast as the generic code below
1439 sub { 1484 sub {
1440 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1485 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
1441 1486
1442 $cb->($_[0], $1, $2); 1487 $cb->($_[0], "$1", "$2");
1443 1 1488 1
1444 } 1489 }
1445 } else { 1490 } else {
1446 $eol = quotemeta $eol unless ref $eol; 1491 $eol = quotemeta $eol unless ref $eol;
1447 $eol = qr|^(.*?)($eol)|s; 1492 $eol = qr|^(.*?)($eol)|s;
1448 1493
1449 sub { 1494 sub {
1450 $_[0]{rbuf} =~ s/$eol// or return; 1495 $_[0]{rbuf} =~ s/$eol// or return;
1451 1496
1452 $cb->($_[0], $1, $2); 1497 $cb->($_[0], "$1", "$2");
1453 1 1498 1
1454 } 1499 }
1455 } 1500 }
1456}; 1501};
1457 1502
… …
1505 1550
1506 sub { 1551 sub {
1507 # accept 1552 # accept
1508 if ($$rbuf =~ $accept) { 1553 if ($$rbuf =~ $accept) {
1509 $data .= substr $$rbuf, 0, $+[0], ""; 1554 $data .= substr $$rbuf, 0, $+[0], "";
1510 $cb->($self, $data); 1555 $cb->($_[0], $data);
1511 return 1; 1556 return 1;
1512 } 1557 }
1513 1558
1514 # reject 1559 # reject
1515 if ($reject && $$rbuf =~ $reject) { 1560 if ($reject && $$rbuf =~ $reject) {
1516 $self->_error (Errno::EBADMSG); 1561 $_[0]->_error (Errno::EBADMSG);
1517 } 1562 }
1518 1563
1519 # skip 1564 # skip
1520 if ($skip && $$rbuf =~ $skip) { 1565 if ($skip && $$rbuf =~ $skip) {
1521 $data .= substr $$rbuf, 0, $+[0], ""; 1566 $data .= substr $$rbuf, 0, $+[0], "";
… …
1537 my ($self, $cb) = @_; 1582 my ($self, $cb) = @_;
1538 1583
1539 sub { 1584 sub {
1540 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 1585 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1541 if ($_[0]{rbuf} =~ /[^0-9]/) { 1586 if ($_[0]{rbuf} =~ /[^0-9]/) {
1542 $self->_error (Errno::EBADMSG); 1587 $_[0]->_error (Errno::EBADMSG);
1543 } 1588 }
1544 return; 1589 return;
1545 } 1590 }
1546 1591
1547 my $len = $1; 1592 my $len = $1;
1548 1593
1549 $self->unshift_read (chunk => $len, sub { 1594 $_[0]->unshift_read (chunk => $len, sub {
1550 my $string = $_[1]; 1595 my $string = $_[1];
1551 $_[0]->unshift_read (chunk => 1, sub { 1596 $_[0]->unshift_read (chunk => 1, sub {
1552 if ($_[1] eq ",") { 1597 if ($_[1] eq ",") {
1553 $cb->($_[0], $string); 1598 $cb->($_[0], $string);
1554 } else { 1599 } else {
1555 $self->_error (Errno::EBADMSG); 1600 $_[0]->_error (Errno::EBADMSG);
1556 } 1601 }
1557 }); 1602 });
1558 }); 1603 });
1559 1604
1560 1 1605 1
… …
1633 1678
1634 my $data; 1679 my $data;
1635 my $rbuf = \$self->{rbuf}; 1680 my $rbuf = \$self->{rbuf};
1636 1681
1637 sub { 1682 sub {
1638 my $ref = eval { $json->incr_parse ($self->{rbuf}) }; 1683 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
1639 1684
1640 if ($ref) { 1685 if ($ref) {
1641 $self->{rbuf} = $json->incr_text; 1686 $_[0]{rbuf} = $json->incr_text;
1642 $json->incr_text = ""; 1687 $json->incr_text = "";
1643 $cb->($self, $ref); 1688 $cb->($_[0], $ref);
1644 1689
1645 1 1690 1
1646 } elsif ($@) { 1691 } elsif ($@) {
1647 # error case 1692 # error case
1648 $json->incr_skip; 1693 $json->incr_skip;
1649 1694
1650 $self->{rbuf} = $json->incr_text; 1695 $_[0]{rbuf} = $json->incr_text;
1651 $json->incr_text = ""; 1696 $json->incr_text = "";
1652 1697
1653 $self->_error (Errno::EBADMSG); 1698 $_[0]->_error (Errno::EBADMSG);
1654 1699
1655 () 1700 ()
1656 } else { 1701 } else {
1657 $self->{rbuf} = ""; 1702 $_[0]{rbuf} = "";
1658 1703
1659 () 1704 ()
1660 } 1705 }
1661 } 1706 }
1662}; 1707};
… …
1672=cut 1717=cut
1673 1718
1674register_read_type storable => sub { 1719register_read_type storable => sub {
1675 my ($self, $cb) = @_; 1720 my ($self, $cb) = @_;
1676 1721
1677 require Storable; 1722 require Storable unless $Storable::VERSION;
1678 1723
1679 sub { 1724 sub {
1680 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1725 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1681 defined (my $len = eval { unpack "w", $_[0]{rbuf} }) 1726 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1682 or return; 1727 or return;
… …
1685 1730
1686 # bypass unshift if we already have the remaining chunk 1731 # bypass unshift if we already have the remaining chunk
1687 if ($format + $len <= length $_[0]{rbuf}) { 1732 if ($format + $len <= length $_[0]{rbuf}) {
1688 my $data = substr $_[0]{rbuf}, $format, $len; 1733 my $data = substr $_[0]{rbuf}, $format, $len;
1689 substr $_[0]{rbuf}, 0, $format + $len, ""; 1734 substr $_[0]{rbuf}, 0, $format + $len, "";
1735
1690 $cb->($_[0], Storable::thaw ($data)); 1736 eval { $cb->($_[0], Storable::thaw ($data)); 1 }
1737 or return $_[0]->_error (Errno::EBADMSG);
1691 } else { 1738 } else {
1692 # remove prefix 1739 # remove prefix
1693 substr $_[0]{rbuf}, 0, $format, ""; 1740 substr $_[0]{rbuf}, 0, $format, "";
1694 1741
1695 # read remaining chunk 1742 # read remaining chunk
1696 $_[0]->unshift_read (chunk => $len, sub { 1743 $_[0]->unshift_read (chunk => $len, sub {
1697 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1744 eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
1698 $cb->($_[0], $ref);
1699 } else {
1700 $self->_error (Errno::EBADMSG); 1745 or $_[0]->_error (Errno::EBADMSG);
1701 }
1702 }); 1746 });
1703 } 1747 }
1704 1748
1705 1 1749 1
1706 } 1750 }
… …
1743Note that AnyEvent::Handle will automatically C<start_read> for you when 1787Note 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 1788you 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 1789will automatically C<stop_read> for you when neither C<on_read> is set nor
1746there are any read requests in the queue. 1790there are any read requests in the queue.
1747 1791
1748These methods will have no effect when in TLS mode (as TLS doesn't support 1792In older versions of this module (<= 5.3), these methods had no effect,
1749half-duplex connections). 1793as TLS does not support half-duplex connections. In current versions they
1794work as expected, as this behaviour is required to avoid certain resource
1795attacks, where the program would be forced to read (and buffer) arbitrary
1796amounts of data before being able to send some data. The drawback is that
1797some readings of the the SSL/TLS specifications basically require this
1798attack to be working, as SSL/TLS implementations might stall sending data
1799during a rehandshake.
1800
1801As a guideline, during the initial handshake, you should not stop reading,
1802and as a client, it might cause problems, depending on your application.
1750 1803
1751=cut 1804=cut
1752 1805
1753sub stop_read { 1806sub stop_read {
1754 my ($self) = @_; 1807 my ($self) = @_;
1755 1808
1756 delete $self->{_rw} unless $self->{tls}; 1809 delete $self->{_rw};
1757} 1810}
1758 1811
1759sub start_read { 1812sub start_read {
1760 my ($self) = @_; 1813 my ($self) = @_;
1761 1814
… …
1963 Net::SSLeay::CTX_set_mode ($tls, 1|2); 2016 Net::SSLeay::CTX_set_mode ($tls, 1|2);
1964 2017
1965 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2018 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1966 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2019 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1967 2020
1968 Net::SSLeay::BIO_write ($self->{_rbio}, delete $self->{rbuf}); 2021 Net::SSLeay::BIO_write ($self->{_rbio}, $self->{rbuf});
2022 $self->{rbuf} = "";
1969 2023
1970 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio}); 2024 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio});
1971 2025
1972 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) } 2026 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1973 if $self->{on_starttls}; 2027 if $self->{on_starttls};
… …
2010 $self->{tls_ctx}->_put_session (delete $self->{tls}) 2064 $self->{tls_ctx}->_put_session (delete $self->{tls})
2011 if $self->{tls} > 0; 2065 if $self->{tls} > 0;
2012 2066
2013 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)}; 2067 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
2014} 2068}
2069
2070=item $handle->resettls
2071
2072This rarely-used method simply resets and TLS state on the handle, usually
2073causing data loss.
2074
2075One case where it may be useful is when you want to skip over the data in
2076the stream but you are not interested in interpreting it, so data loss is
2077no concern.
2078
2079=cut
2080
2081*resettls = \&_freetls;
2015 2082
2016sub DESTROY { 2083sub DESTROY {
2017 my ($self) = @_; 2084 my ($self) = @_;
2018 2085
2019 &_freetls; 2086 &_freetls;
… …
2135 2202
2136It is only safe to "forget" the reference inside EOF or error callbacks, 2203It is only safe to "forget" the reference inside EOF or error callbacks,
2137from within all other callbacks, you need to explicitly call the C<< 2204from within all other callbacks, you need to explicitly call the C<<
2138->destroy >> method. 2205->destroy >> method.
2139 2206
2207=item Why is my C<on_eof> callback never called?
2208
2209Probably because your C<on_error> callback is being called instead: When
2210you have outstanding requests in your read queue, then an EOF is
2211considered an error as you clearly expected some data.
2212
2213To avoid this, make sure you have an empty read queue whenever your handle
2214is supposed to be "idle" (i.e. connection closes are O.K.). You can set
2215an C<on_read> handler that simply pushes the first read requests in the
2216queue.
2217
2218See also the next question, which explains this in a bit more detail.
2219
2220=item How can I serve requests in a loop?
2221
2222Most protocols consist of some setup phase (authentication for example)
2223followed by a request handling phase, where the server waits for requests
2224and handles them, in a loop.
2225
2226There are two important variants: The first (traditional, better) variant
2227handles requests until the server gets some QUIT command, causing it to
2228close the connection first (highly desirable for a busy TCP server). A
2229client dropping the connection is an error, which means this variant can
2230detect an unexpected detection close.
2231
2232To handle this case, always make sure you have a on-empty read queue, by
2233pushing the "read request start" handler on it:
2234
2235 # we assume a request starts with a single line
2236 my @start_request; @start_request = (line => sub {
2237 my ($hdl, $line) = @_;
2238
2239 ... handle request
2240
2241 # push next request read, possibly from a nested callback
2242 $hdl->push_read (@start_request);
2243 });
2244
2245 # auth done, now go into request handling loop
2246 # now push the first @start_request
2247 $hdl->push_read (@start_request);
2248
2249By always having an outstanding C<push_read>, the handle always expects
2250some data and raises the C<EPIPE> error when the connction is dropped
2251unexpectedly.
2252
2253The second variant is a protocol where the client can drop the connection
2254at any time. For TCP, this means that the server machine may run out of
2255sockets easier, and in general, it means you cannot distinguish a protocl
2256failure/client crash from a normal connection close. Nevertheless, these
2257kinds of protocols are common (and sometimes even the best solution to the
2258problem).
2259
2260Having an outstanding read request at all times is possible if you ignore
2261C<EPIPE> errors, but this doesn't help with when the client drops the
2262connection during a request, which would still be an error.
2263
2264A better solution is to push the initial request read in an C<on_read>
2265callback. This avoids an error, as when the server doesn't expect data
2266(i.e. is idly waiting for the next request, an EOF will not raise an
2267error, but simply result in an C<on_eof> callback. It is also a bit slower
2268and simpler:
2269
2270 # auth done, now go into request handling loop
2271 $hdl->on_read (sub {
2272 my ($hdl) = @_;
2273
2274 # called each time we receive data but the read queue is empty
2275 # simply start read the request
2276
2277 $hdl->push_read (line => sub {
2278 my ($hdl, $line) = @_;
2279
2280 ... handle request
2281
2282 # do nothing special when the request has been handled, just
2283 # let the request queue go empty.
2284 });
2285 });
2286
2140=item I get different callback invocations in TLS mode/Why can't I pause 2287=item I get different callback invocations in TLS mode/Why can't I pause
2141reading? 2288reading?
2142 2289
2143Unlike, say, TCP, TLS connections do not consist of two independent 2290Unlike, say, TCP, TLS connections do not consist of two independent
2144communication channels, one for each direction. Or put differently, the 2291communication channels, one for each direction. Or put differently, the
… …
2165 $handle->on_eof (undef); 2312 $handle->on_eof (undef);
2166 $handle->on_error (sub { 2313 $handle->on_error (sub {
2167 my $data = delete $_[0]{rbuf}; 2314 my $data = delete $_[0]{rbuf};
2168 }); 2315 });
2169 2316
2317Note that this example removes the C<rbuf> member from the handle object,
2318which is not normally allowed by the API. It is expressly permitted in
2319this case only, as the handle object needs to be destroyed afterwards.
2320
2170The reason to use C<on_error> is that TCP connections, due to latencies 2321The reason to use C<on_error> is that TCP connections, due to latencies
2171and packets loss, might get closed quite violently with an error, when in 2322and packets loss, might get closed quite violently with an error, when in
2172fact all data has been received. 2323fact all data has been received.
2173 2324
2174It is usually better to use acknowledgements when transferring data, 2325It is usually better to use acknowledgements when transferring data,
… …
2184C<low_water_mark> this will be called precisely when all data has been 2335C<low_water_mark> this will be called precisely when all data has been
2185written to the socket: 2336written to the socket:
2186 2337
2187 $handle->push_write (...); 2338 $handle->push_write (...);
2188 $handle->on_drain (sub { 2339 $handle->on_drain (sub {
2189 warn "all data submitted to the kernel\n"; 2340 AE::log debug => "All data submitted to the kernel.";
2190 undef $handle; 2341 undef $handle;
2191 }); 2342 });
2192 2343
2193If you just want to queue some data and then signal EOF to the other side, 2344If you just want to queue some data and then signal EOF to the other side,
2194consider using C<< ->push_shutdown >> instead. 2345consider using C<< ->push_shutdown >> instead.
… …
2278When you have intermediate CA certificates that your clients might not 2429When you have intermediate CA certificates that your clients might not
2279know about, just append them to the C<cert_file>. 2430know about, just append them to the C<cert_file>.
2280 2431
2281=back 2432=back
2282 2433
2283
2284=head1 SUBCLASSING AnyEvent::Handle 2434=head1 SUBCLASSING AnyEvent::Handle
2285 2435
2286In many cases, you might want to subclass AnyEvent::Handle. 2436In many cases, you might want to subclass AnyEvent::Handle.
2287 2437
2288To make this easier, a given version of AnyEvent::Handle uses these 2438To make this easier, a given version of AnyEvent::Handle uses these
… …
2314 2464
2315Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 2465Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
2316 2466
2317=cut 2467=cut
2318 2468
23191; # End of AnyEvent::Handle 24691
2470

Diff Legend

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