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.212 by root, Fri Dec 31 04:50:44 2010 UTC vs.
Revision 1.233 by root, Thu Apr 5 06:14:10 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 => $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
… …
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
… …
164with active (but unsatisfiable) read watchers (C<EPIPE>) or I/O errors. In 170with active (but unsatisfiable) read watchers (C<EPIPE>) or I/O errors. In
165cases where the other side can close the connection at will, it is 171cases where the other side can close the connection at will, it is
166often easiest to not report C<EPIPE> errors in this callback. 172often easiest to not report C<EPIPE> errors in this callback.
167 173
168AnyEvent::Handle tries to find an appropriate error code for you to check 174AnyEvent::Handle tries to find an appropriate error code for you to check
169against, but in some cases (TLS errors), this does not work well. It is 175against, but in some cases (TLS errors), this does not work well.
170recommended to always output the C<$message> argument in human-readable 176
171error messages (it's usually the same as C<"$!">). 177If you report the error to the user, it is recommended to always output
178the C<$message> argument in human-readable error messages (you don't need
179to report C<"$!"> if you report C<$message>).
180
181If you want to react programmatically to the error, then looking at C<$!>
182and comparing it against some of the documented C<Errno> values is usually
183better than looking at the C<$message>.
172 184
173Non-fatal errors can be retried by returning, but it is recommended 185Non-fatal errors can be retried by returning, but it is recommended
174to simply ignore this parameter and instead abondon the handle object 186to simply ignore this parameter and instead abondon the handle object
175when this callback is invoked. Examples of non-fatal errors are timeouts 187when this callback is invoked. Examples of non-fatal errors are timeouts
176C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>). 188C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
… …
224If an EOF condition has been detected but no C<on_eof> callback has been 236If 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>. 237set, then a fatal error will be raised with C<$!> set to <0>.
226 238
227=item on_drain => $cb->($handle) 239=item on_drain => $cb->($handle)
228 240
229This sets the callback that is called when the write buffer becomes empty 241This sets the callback that is called once when the write buffer becomes
230(or immediately if the buffer is empty already). 242empty (and immediately when the handle object is created).
231 243
232To append to the write buffer, use the C<< ->push_write >> method. 244To append to the write buffer, use the C<< ->push_write >> method.
233 245
234This callback is useful when you don't want to put all of your write data 246This 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 247into 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 259many 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 260file 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> 261will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT>
250error will be raised). 262error will be raised).
251 263
252There are three variants of the timeouts that work independently 264There are three variants of the timeouts that work independently of each
253of each other, for both read and write, just read, and just write: 265other, for both read and write (triggered when nothing was read I<OR>
266written), just read (triggered when nothing was read), and just write:
254C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks 267C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks
255C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions 268C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions
256C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>. 269C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>.
257 270
258Note that timeout processing is active even when you do not have 271Note 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 272outstanding read or write requests: If you plan to keep the connection
260idle then you should disable the timeout temporarily or ignore the timeout 273idle then you should disable the timeout temporarily or ignore the
261in the C<on_timeout> callback, in which case AnyEvent::Handle will simply 274timeout in the corresponding C<on_timeout> callback, in which case
262restart the timeout. 275AnyEvent::Handle will simply restart the timeout.
263 276
264Zero (the default) disables this timeout. 277Zero (the default) disables the corresponding timeout.
265 278
266=item on_timeout => $cb->($handle) 279=item on_timeout => $cb->($handle)
280
281=item on_rtimeout => $cb->($handle)
282
283=item on_wtimeout => $cb->($handle)
267 284
268Called whenever the inactivity timeout passes. If you return from this 285Called whenever the inactivity timeout passes. If you return from this
269callback, then the timeout will be reset as if some activity had happened, 286callback, then the timeout will be reset as if some activity had happened,
270so this condition is not fatal in any way. 287so this condition is not fatal in any way.
271 288
… …
354already have occured on BSD systems), but at least it will protect you 371already have occured on BSD systems), but at least it will protect you
355from most attacks. 372from most attacks.
356 373
357=item read_size => <bytes> 374=item read_size => <bytes>
358 375
359The initial read block size, the number of bytes this module will try to 376The initial read block size, the number of bytes this module will try
360read during each loop iteration. Each handle object will consume at least 377to read during each loop iteration. Each handle object will consume
361this amount of memory for the read buffer as well, so when handling many 378at least this amount of memory for the read buffer as well, so when
362connections requirements). See also C<max_read_size>. Default: C<2048>. 379handling many connections watch out for memory requirements). See also
380C<max_read_size>. Default: C<2048>.
363 381
364=item max_read_size => <bytes> 382=item max_read_size => <bytes>
365 383
366The maximum read buffer size used by the dynamic adjustment 384The maximum read buffer size used by the dynamic adjustment
367algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in 385algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in
… …
536 }); 554 });
537 555
538 } else { 556 } else {
539 if ($self->{on_connect_error}) { 557 if ($self->{on_connect_error}) {
540 $self->{on_connect_error}($self, "$!"); 558 $self->{on_connect_error}($self, "$!");
541 $self->destroy; 559 $self->destroy if $self;
542 } else { 560 } else {
543 $self->_error ($!, 1); 561 $self->_error ($!, 1);
544 } 562 }
545 } 563 }
546 }, 564 },
… …
765 783
766sub rbuf_max { 784sub rbuf_max {
767 $_[0]{rbuf_max} = $_[1]; 785 $_[0]{rbuf_max} = $_[1];
768} 786}
769 787
770sub rbuf_max { 788sub wbuf_max {
771 $_[0]{wbuf_max} = $_[1]; 789 $_[0]{wbuf_max} = $_[1];
772} 790}
773 791
774############################################################################# 792#############################################################################
775 793
… …
778=item $handle->rtimeout ($seconds) 796=item $handle->rtimeout ($seconds)
779 797
780=item $handle->wtimeout ($seconds) 798=item $handle->wtimeout ($seconds)
781 799
782Configures (or disables) the inactivity timeout. 800Configures (or disables) the inactivity timeout.
801
802The timeout will be checked instantly, so this method might destroy the
803handle before it returns.
783 804
784=item $handle->timeout_reset 805=item $handle->timeout_reset
785 806
786=item $handle->rtimeout_reset 807=item $handle->rtimeout_reset
787 808
… …
871 892
872The write queue is very simple: you can add data to its end, and 893The write queue is very simple: you can add data to its end, and
873AnyEvent::Handle will automatically try to get rid of it for you. 894AnyEvent::Handle will automatically try to get rid of it for you.
874 895
875When data could be written and the write buffer is shorter then the low 896When data could be written and the write buffer is shorter then the low
876water mark, the C<on_drain> callback will be invoked. 897water mark, the C<on_drain> callback will be invoked once.
877 898
878=over 4 899=over 4
879 900
880=item $handle->on_drain ($cb) 901=item $handle->on_drain ($cb)
881 902
… …
1072=cut 1093=cut
1073 1094
1074register_write_type storable => sub { 1095register_write_type storable => sub {
1075 my ($self, $ref) = @_; 1096 my ($self, $ref) = @_;
1076 1097
1077 require Storable; 1098 require Storable unless $Storable::VERSION;
1078 1099
1079 pack "w/a*", Storable::nfreeze ($ref) 1100 pack "w/a*", Storable::nfreeze ($ref)
1080}; 1101};
1081 1102
1082=back 1103=back
… …
1087before it was actually written. One way to do that is to replace your 1108before 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 1109C<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 1110C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1090replaces the C<on_drain> callback with: 1111replaces the C<on_drain> callback with:
1091 1112
1092 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 1113 sub { shutdown $_[0]{fh}, 1 }
1093 1114
1094This simply shuts down the write side and signals an EOF condition to the 1115This simply shuts down the write side and signals an EOF condition to the
1095the peer. 1116the peer.
1096 1117
1097You can rely on the normal read queue and C<on_eof> handling 1118You can rely on the normal read queue and C<on_eof> handling
… …
1119 1140
1120Whenever the given C<type> is used, C<push_write> will the function with 1141Whenever the given C<type> is used, C<push_write> will the function with
1121the handle object and the remaining arguments. 1142the handle object and the remaining arguments.
1122 1143
1123The function is supposed to return a single octet string that will be 1144The function is supposed to return a single octet string that will be
1124appended to the write buffer, so you cna mentally treat this function as a 1145appended to the write buffer, so you can mentally treat this function as a
1125"arguments to on-the-wire-format" converter. 1146"arguments to on-the-wire-format" converter.
1126 1147
1127Example: implement a custom write type C<join> that joins the remaining 1148Example: implement a custom write type C<join> that joins the remaining
1128arguments using the first one. 1149arguments using the first one.
1129 1150
… …
1423data. 1444data.
1424 1445
1425Example: read 2 bytes. 1446Example: read 2 bytes.
1426 1447
1427 $handle->push_read (chunk => 2, sub { 1448 $handle->push_read (chunk => 2, sub {
1428 warn "yay ", unpack "H*", $_[1]; 1449 say "yay " . unpack "H*", $_[1];
1429 }); 1450 });
1430 1451
1431=cut 1452=cut
1432 1453
1433register_read_type chunk => sub { 1454register_read_type chunk => sub {
… …
1467 if (@_ < 3) { 1488 if (@_ < 3) {
1468 # this is more than twice as fast as the generic code below 1489 # this is more than twice as fast as the generic code below
1469 sub { 1490 sub {
1470 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1491 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
1471 1492
1472 $cb->($_[0], $1, $2); 1493 $cb->($_[0], "$1", "$2");
1473 1 1494 1
1474 } 1495 }
1475 } else { 1496 } else {
1476 $eol = quotemeta $eol unless ref $eol; 1497 $eol = quotemeta $eol unless ref $eol;
1477 $eol = qr|^(.*?)($eol)|s; 1498 $eol = qr|^(.*?)($eol)|s;
1478 1499
1479 sub { 1500 sub {
1480 $_[0]{rbuf} =~ s/$eol// or return; 1501 $_[0]{rbuf} =~ s/$eol// or return;
1481 1502
1482 $cb->($_[0], $1, $2); 1503 $cb->($_[0], "$1", "$2");
1483 1 1504 1
1484 } 1505 }
1485 } 1506 }
1486}; 1507};
1487 1508
… …
1535 1556
1536 sub { 1557 sub {
1537 # accept 1558 # accept
1538 if ($$rbuf =~ $accept) { 1559 if ($$rbuf =~ $accept) {
1539 $data .= substr $$rbuf, 0, $+[0], ""; 1560 $data .= substr $$rbuf, 0, $+[0], "";
1540 $cb->($self, $data); 1561 $cb->($_[0], $data);
1541 return 1; 1562 return 1;
1542 } 1563 }
1543 1564
1544 # reject 1565 # reject
1545 if ($reject && $$rbuf =~ $reject) { 1566 if ($reject && $$rbuf =~ $reject) {
1546 $self->_error (Errno::EBADMSG); 1567 $_[0]->_error (Errno::EBADMSG);
1547 } 1568 }
1548 1569
1549 # skip 1570 # skip
1550 if ($skip && $$rbuf =~ $skip) { 1571 if ($skip && $$rbuf =~ $skip) {
1551 $data .= substr $$rbuf, 0, $+[0], ""; 1572 $data .= substr $$rbuf, 0, $+[0], "";
… …
1567 my ($self, $cb) = @_; 1588 my ($self, $cb) = @_;
1568 1589
1569 sub { 1590 sub {
1570 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 1591 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1571 if ($_[0]{rbuf} =~ /[^0-9]/) { 1592 if ($_[0]{rbuf} =~ /[^0-9]/) {
1572 $self->_error (Errno::EBADMSG); 1593 $_[0]->_error (Errno::EBADMSG);
1573 } 1594 }
1574 return; 1595 return;
1575 } 1596 }
1576 1597
1577 my $len = $1; 1598 my $len = $1;
1578 1599
1579 $self->unshift_read (chunk => $len, sub { 1600 $_[0]->unshift_read (chunk => $len, sub {
1580 my $string = $_[1]; 1601 my $string = $_[1];
1581 $_[0]->unshift_read (chunk => 1, sub { 1602 $_[0]->unshift_read (chunk => 1, sub {
1582 if ($_[1] eq ",") { 1603 if ($_[1] eq ",") {
1583 $cb->($_[0], $string); 1604 $cb->($_[0], $string);
1584 } else { 1605 } else {
1585 $self->_error (Errno::EBADMSG); 1606 $_[0]->_error (Errno::EBADMSG);
1586 } 1607 }
1587 }); 1608 });
1588 }); 1609 });
1589 1610
1590 1 1611 1
… …
1663 1684
1664 my $data; 1685 my $data;
1665 my $rbuf = \$self->{rbuf}; 1686 my $rbuf = \$self->{rbuf};
1666 1687
1667 sub { 1688 sub {
1668 my $ref = eval { $json->incr_parse ($self->{rbuf}) }; 1689 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
1669 1690
1670 if ($ref) { 1691 if ($ref) {
1671 $self->{rbuf} = $json->incr_text; 1692 $_[0]{rbuf} = $json->incr_text;
1672 $json->incr_text = ""; 1693 $json->incr_text = "";
1673 $cb->($self, $ref); 1694 $cb->($_[0], $ref);
1674 1695
1675 1 1696 1
1676 } elsif ($@) { 1697 } elsif ($@) {
1677 # error case 1698 # error case
1678 $json->incr_skip; 1699 $json->incr_skip;
1679 1700
1680 $self->{rbuf} = $json->incr_text; 1701 $_[0]{rbuf} = $json->incr_text;
1681 $json->incr_text = ""; 1702 $json->incr_text = "";
1682 1703
1683 $self->_error (Errno::EBADMSG); 1704 $_[0]->_error (Errno::EBADMSG);
1684 1705
1685 () 1706 ()
1686 } else { 1707 } else {
1687 $self->{rbuf} = ""; 1708 $_[0]{rbuf} = "";
1688 1709
1689 () 1710 ()
1690 } 1711 }
1691 } 1712 }
1692}; 1713};
… …
1702=cut 1723=cut
1703 1724
1704register_read_type storable => sub { 1725register_read_type storable => sub {
1705 my ($self, $cb) = @_; 1726 my ($self, $cb) = @_;
1706 1727
1707 require Storable; 1728 require Storable unless $Storable::VERSION;
1708 1729
1709 sub { 1730 sub {
1710 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1731 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1711 defined (my $len = eval { unpack "w", $_[0]{rbuf} }) 1732 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1712 or return; 1733 or return;
… …
1715 1736
1716 # bypass unshift if we already have the remaining chunk 1737 # bypass unshift if we already have the remaining chunk
1717 if ($format + $len <= length $_[0]{rbuf}) { 1738 if ($format + $len <= length $_[0]{rbuf}) {
1718 my $data = substr $_[0]{rbuf}, $format, $len; 1739 my $data = substr $_[0]{rbuf}, $format, $len;
1719 substr $_[0]{rbuf}, 0, $format + $len, ""; 1740 substr $_[0]{rbuf}, 0, $format + $len, "";
1741
1720 $cb->($_[0], Storable::thaw ($data)); 1742 eval { $cb->($_[0], Storable::thaw ($data)); 1 }
1743 or return $_[0]->_error (Errno::EBADMSG);
1721 } else { 1744 } else {
1722 # remove prefix 1745 # remove prefix
1723 substr $_[0]{rbuf}, 0, $format, ""; 1746 substr $_[0]{rbuf}, 0, $format, "";
1724 1747
1725 # read remaining chunk 1748 # read remaining chunk
1726 $_[0]->unshift_read (chunk => $len, sub { 1749 $_[0]->unshift_read (chunk => $len, sub {
1727 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1750 eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
1728 $cb->($_[0], $ref);
1729 } else {
1730 $self->_error (Errno::EBADMSG); 1751 or $_[0]->_error (Errno::EBADMSG);
1731 }
1732 }); 1752 });
1733 } 1753 }
1734 1754
1735 1 1755 1
1736 } 1756 }
… …
1773Note that AnyEvent::Handle will automatically C<start_read> for you when 1793Note 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 1794you 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 1795will automatically C<stop_read> for you when neither C<on_read> is set nor
1776there are any read requests in the queue. 1796there are any read requests in the queue.
1777 1797
1778These methods will have no effect when in TLS mode (as TLS doesn't support 1798In older versions of this module (<= 5.3), these methods had no effect,
1779half-duplex connections). 1799as TLS does not support half-duplex connections. In current versions they
1800work as expected, as this behaviour is required to avoid certain resource
1801attacks, where the program would be forced to read (and buffer) arbitrary
1802amounts of data before being able to send some data. The drawback is that
1803some readings of the the SSL/TLS specifications basically require this
1804attack to be working, as SSL/TLS implementations might stall sending data
1805during a rehandshake.
1806
1807As a guideline, during the initial handshake, you should not stop reading,
1808and as a client, it might cause problems, depending on your application.
1780 1809
1781=cut 1810=cut
1782 1811
1783sub stop_read { 1812sub stop_read {
1784 my ($self) = @_; 1813 my ($self) = @_;
1785 1814
1786 delete $self->{_rw} unless $self->{tls}; 1815 delete $self->{_rw};
1787} 1816}
1788 1817
1789sub start_read { 1818sub start_read {
1790 my ($self) = @_; 1819 my ($self) = @_;
1791 1820
… …
1832 my ($self, $err) = @_; 1861 my ($self, $err) = @_;
1833 1862
1834 return $self->_error ($!, 1) 1863 return $self->_error ($!, 1)
1835 if $err == Net::SSLeay::ERROR_SYSCALL (); 1864 if $err == Net::SSLeay::ERROR_SYSCALL ();
1836 1865
1837 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ()); 1866 my $err = Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1838 1867
1839 # reduce error string to look less scary 1868 # reduce error string to look less scary
1840 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /; 1869 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1841 1870
1842 if ($self->{_on_starttls}) { 1871 if ($self->{_on_starttls}) {
… …
1993 Net::SSLeay::CTX_set_mode ($tls, 1|2); 2022 Net::SSLeay::CTX_set_mode ($tls, 1|2);
1994 2023
1995 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2024 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1996 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2025 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1997 2026
1998 Net::SSLeay::BIO_write ($self->{_rbio}, delete $self->{rbuf}); 2027 Net::SSLeay::BIO_write ($self->{_rbio}, $self->{rbuf});
2028 $self->{rbuf} = "";
1999 2029
2000 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio}); 2030 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio});
2001 2031
2002 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) } 2032 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
2003 if $self->{on_starttls}; 2033 if $self->{on_starttls};
… …
2040 $self->{tls_ctx}->_put_session (delete $self->{tls}) 2070 $self->{tls_ctx}->_put_session (delete $self->{tls})
2041 if $self->{tls} > 0; 2071 if $self->{tls} > 0;
2042 2072
2043 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)}; 2073 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
2044} 2074}
2075
2076=item $handle->resettls
2077
2078This rarely-used method simply resets and TLS state on the handle, usually
2079causing data loss.
2080
2081One case where it may be useful is when you want to skip over the data in
2082the stream but you are not interested in interpreting it, so data loss is
2083no concern.
2084
2085=cut
2086
2087*resettls = \&_freetls;
2045 2088
2046sub DESTROY { 2089sub DESTROY {
2047 my ($self) = @_; 2090 my ($self) = @_;
2048 2091
2049 &_freetls; 2092 &_freetls;
… …
2172Probably because your C<on_error> callback is being called instead: When 2215Probably because your C<on_error> callback is being called instead: When
2173you have outstanding requests in your read queue, then an EOF is 2216you have outstanding requests in your read queue, then an EOF is
2174considered an error as you clearly expected some data. 2217considered an error as you clearly expected some data.
2175 2218
2176To avoid this, make sure you have an empty read queue whenever your handle 2219To 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 2220is supposed to be "idle" (i.e. connection closes are O.K.). You can set
2178an C<on_read> handler that simply pushes the first read requests in the 2221an C<on_read> handler that simply pushes the first read requests in the
2179queue. 2222queue.
2180 2223
2181See also the next question, which explains this in a bit more detail. 2224See also the next question, which explains this in a bit more detail.
2182 2225
… …
2213some data and raises the C<EPIPE> error when the connction is dropped 2256some data and raises the C<EPIPE> error when the connction is dropped
2214unexpectedly. 2257unexpectedly.
2215 2258
2216The second variant is a protocol where the client can drop the connection 2259The 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 2260at 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 2261sockets easier, and in general, it means you cannot distinguish a protocl
2219failure/client crash from a normal connection close. Nevertheless, these 2262failure/client crash from a normal connection close. Nevertheless, these
2220kinds of protocols are common (and sometimes even the best solution to the 2263kinds of protocols are common (and sometimes even the best solution to the
2221problem). 2264problem).
2222 2265
2223Having an outstanding read request at all times is possible if you ignore 2266Having an outstanding read request at all times is possible if you ignore
… …
2275 $handle->on_eof (undef); 2318 $handle->on_eof (undef);
2276 $handle->on_error (sub { 2319 $handle->on_error (sub {
2277 my $data = delete $_[0]{rbuf}; 2320 my $data = delete $_[0]{rbuf};
2278 }); 2321 });
2279 2322
2323Note that this example removes the C<rbuf> member from the handle object,
2324which is not normally allowed by the API. It is expressly permitted in
2325this case only, as the handle object needs to be destroyed afterwards.
2326
2280The reason to use C<on_error> is that TCP connections, due to latencies 2327The reason to use C<on_error> is that TCP connections, due to latencies
2281and packets loss, might get closed quite violently with an error, when in 2328and packets loss, might get closed quite violently with an error, when in
2282fact all data has been received. 2329fact all data has been received.
2283 2330
2284It is usually better to use acknowledgements when transferring data, 2331It is usually better to use acknowledgements when transferring data,
… …
2294C<low_water_mark> this will be called precisely when all data has been 2341C<low_water_mark> this will be called precisely when all data has been
2295written to the socket: 2342written to the socket:
2296 2343
2297 $handle->push_write (...); 2344 $handle->push_write (...);
2298 $handle->on_drain (sub { 2345 $handle->on_drain (sub {
2299 warn "all data submitted to the kernel\n"; 2346 AE::log debug => "All data submitted to the kernel.";
2300 undef $handle; 2347 undef $handle;
2301 }); 2348 });
2302 2349
2303If you just want to queue some data and then signal EOF to the other side, 2350If you just want to queue some data and then signal EOF to the other side,
2304consider using C<< ->push_shutdown >> instead. 2351consider using C<< ->push_shutdown >> instead.
… …
2388When you have intermediate CA certificates that your clients might not 2435When you have intermediate CA certificates that your clients might not
2389know about, just append them to the C<cert_file>. 2436know about, just append them to the C<cert_file>.
2390 2437
2391=back 2438=back
2392 2439
2393
2394=head1 SUBCLASSING AnyEvent::Handle 2440=head1 SUBCLASSING AnyEvent::Handle
2395 2441
2396In many cases, you might want to subclass AnyEvent::Handle. 2442In many cases, you might want to subclass AnyEvent::Handle.
2397 2443
2398To make this easier, a given version of AnyEvent::Handle uses these 2444To make this easier, a given version of AnyEvent::Handle uses these
… …
2424 2470
2425Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 2471Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
2426 2472
2427=cut 2473=cut
2428 2474
24291; # End of AnyEvent::Handle 24751
2476

Diff Legend

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