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.220 by root, Sun Jul 24 13:10:43 2011 UTC vs.
Revision 1.234 by root, Wed Apr 18 09:44: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
… …
359already 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
360from most attacks. 372from most attacks.
361 373
362=item read_size => <bytes> 374=item read_size => <bytes>
363 375
364The 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
365read during each loop iteration. Each handle object will consume at least 377to read during each loop iteration. Each handle object will consume
366this 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
367connections 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>.
368 381
369=item max_read_size => <bytes> 382=item max_read_size => <bytes>
370 383
371The maximum read buffer size used by the dynamic adjustment 384The maximum read buffer size used by the dynamic adjustment
372algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in 385algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in
… …
416appropriate error message. 429appropriate error message.
417 430
418TLS mode requires Net::SSLeay to be installed (it will be loaded 431TLS mode requires Net::SSLeay to be installed (it will be loaded
419automatically when you try to create a TLS handle): this module doesn't 432automatically when you try to create a TLS handle): this module doesn't
420have a dependency on that module, so if your module requires it, you have 433have a dependency on that module, so if your module requires it, you have
421to add the dependency yourself. 434to add the dependency yourself. If Net::SSLeay cannot be loaded or is too
435old, you get an C<EPROTO> error.
422 436
423Unlike TCP, TLS has a server and client side: for the TLS server side, use 437Unlike TCP, TLS has a server and client side: for the TLS server side, use
424C<accept>, and for the TLS client side of a connection, use C<connect> 438C<accept>, and for the TLS client side of a connection, use C<connect>
425mode. 439mode.
426 440
… …
879 893
880The write queue is very simple: you can add data to its end, and 894The write queue is very simple: you can add data to its end, and
881AnyEvent::Handle will automatically try to get rid of it for you. 895AnyEvent::Handle will automatically try to get rid of it for you.
882 896
883When data could be written and the write buffer is shorter then the low 897When data could be written and the write buffer is shorter then the low
884water mark, the C<on_drain> callback will be invoked. 898water mark, the C<on_drain> callback will be invoked once.
885 899
886=over 4 900=over 4
887 901
888=item $handle->on_drain ($cb) 902=item $handle->on_drain ($cb)
889 903
… …
1080=cut 1094=cut
1081 1095
1082register_write_type storable => sub { 1096register_write_type storable => sub {
1083 my ($self, $ref) = @_; 1097 my ($self, $ref) = @_;
1084 1098
1085 require Storable; 1099 require Storable unless $Storable::VERSION;
1086 1100
1087 pack "w/a*", Storable::nfreeze ($ref) 1101 pack "w/a*", Storable::nfreeze ($ref)
1088}; 1102};
1089 1103
1090=back 1104=back
… …
1127 1141
1128Whenever the given C<type> is used, C<push_write> will the function with 1142Whenever the given C<type> is used, C<push_write> will the function with
1129the handle object and the remaining arguments. 1143the handle object and the remaining arguments.
1130 1144
1131The function is supposed to return a single octet string that will be 1145The function is supposed to return a single octet string that will be
1132appended to the write buffer, so you cna mentally treat this function as a 1146appended to the write buffer, so you can mentally treat this function as a
1133"arguments to on-the-wire-format" converter. 1147"arguments to on-the-wire-format" converter.
1134 1148
1135Example: implement a custom write type C<join> that joins the remaining 1149Example: implement a custom write type C<join> that joins the remaining
1136arguments using the first one. 1150arguments using the first one.
1137 1151
… …
1431data. 1445data.
1432 1446
1433Example: read 2 bytes. 1447Example: read 2 bytes.
1434 1448
1435 $handle->push_read (chunk => 2, sub { 1449 $handle->push_read (chunk => 2, sub {
1436 warn "yay ", unpack "H*", $_[1]; 1450 say "yay " . unpack "H*", $_[1];
1437 }); 1451 });
1438 1452
1439=cut 1453=cut
1440 1454
1441register_read_type chunk => sub { 1455register_read_type chunk => sub {
… …
1475 if (@_ < 3) { 1489 if (@_ < 3) {
1476 # this is more than twice as fast as the generic code below 1490 # this is more than twice as fast as the generic code below
1477 sub { 1491 sub {
1478 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1492 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
1479 1493
1480 $cb->($_[0], $1, $2); 1494 $cb->($_[0], "$1", "$2");
1481 1 1495 1
1482 } 1496 }
1483 } else { 1497 } else {
1484 $eol = quotemeta $eol unless ref $eol; 1498 $eol = quotemeta $eol unless ref $eol;
1485 $eol = qr|^(.*?)($eol)|s; 1499 $eol = qr|^(.*?)($eol)|s;
1486 1500
1487 sub { 1501 sub {
1488 $_[0]{rbuf} =~ s/$eol// or return; 1502 $_[0]{rbuf} =~ s/$eol// or return;
1489 1503
1490 $cb->($_[0], $1, $2); 1504 $cb->($_[0], "$1", "$2");
1491 1 1505 1
1492 } 1506 }
1493 } 1507 }
1494}; 1508};
1495 1509
… …
1710=cut 1724=cut
1711 1725
1712register_read_type storable => sub { 1726register_read_type storable => sub {
1713 my ($self, $cb) = @_; 1727 my ($self, $cb) = @_;
1714 1728
1715 require Storable; 1729 require Storable unless $Storable::VERSION;
1716 1730
1717 sub { 1731 sub {
1718 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1732 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1719 defined (my $len = eval { unpack "w", $_[0]{rbuf} }) 1733 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1720 or return; 1734 or return;
… …
1723 1737
1724 # bypass unshift if we already have the remaining chunk 1738 # bypass unshift if we already have the remaining chunk
1725 if ($format + $len <= length $_[0]{rbuf}) { 1739 if ($format + $len <= length $_[0]{rbuf}) {
1726 my $data = substr $_[0]{rbuf}, $format, $len; 1740 my $data = substr $_[0]{rbuf}, $format, $len;
1727 substr $_[0]{rbuf}, 0, $format + $len, ""; 1741 substr $_[0]{rbuf}, 0, $format + $len, "";
1742
1728 $cb->($_[0], Storable::thaw ($data)); 1743 eval { $cb->($_[0], Storable::thaw ($data)); 1 }
1744 or return $_[0]->_error (Errno::EBADMSG);
1729 } else { 1745 } else {
1730 # remove prefix 1746 # remove prefix
1731 substr $_[0]{rbuf}, 0, $format, ""; 1747 substr $_[0]{rbuf}, 0, $format, "";
1732 1748
1733 # read remaining chunk 1749 # read remaining chunk
1734 $_[0]->unshift_read (chunk => $len, sub { 1750 $_[0]->unshift_read (chunk => $len, sub {
1735 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1751 eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
1736 $cb->($_[0], $ref);
1737 } else {
1738 $_[0]->_error (Errno::EBADMSG); 1752 or $_[0]->_error (Errno::EBADMSG);
1739 }
1740 }); 1753 });
1741 } 1754 }
1742 1755
1743 1 1756 1
1744 } 1757 }
… …
1791some readings of the the SSL/TLS specifications basically require this 1804some readings of the the SSL/TLS specifications basically require this
1792attack to be working, as SSL/TLS implementations might stall sending data 1805attack to be working, as SSL/TLS implementations might stall sending data
1793during a rehandshake. 1806during a rehandshake.
1794 1807
1795As a guideline, during the initial handshake, you should not stop reading, 1808As a guideline, during the initial handshake, you should not stop reading,
1796and as a client, it might cause problems, depending on your applciation. 1809and as a client, it might cause problems, depending on your application.
1797 1810
1798=cut 1811=cut
1799 1812
1800sub stop_read { 1813sub stop_read {
1801 my ($self) = @_; 1814 my ($self) = @_;
… …
1849 my ($self, $err) = @_; 1862 my ($self, $err) = @_;
1850 1863
1851 return $self->_error ($!, 1) 1864 return $self->_error ($!, 1)
1852 if $err == Net::SSLeay::ERROR_SYSCALL (); 1865 if $err == Net::SSLeay::ERROR_SYSCALL ();
1853 1866
1854 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ()); 1867 my $err = Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1855 1868
1856 # reduce error string to look less scary 1869 # reduce error string to look less scary
1857 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /; 1870 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1858 1871
1859 if ($self->{_on_starttls}) { 1872 if ($self->{_on_starttls}) {
… …
1925 1938
1926=item $handle->starttls ($tls[, $tls_ctx]) 1939=item $handle->starttls ($tls[, $tls_ctx])
1927 1940
1928Instead of starting TLS negotiation immediately when the AnyEvent::Handle 1941Instead of starting TLS negotiation immediately when the AnyEvent::Handle
1929object is created, you can also do that at a later time by calling 1942object is created, you can also do that at a later time by calling
1930C<starttls>. 1943C<starttls>. See the C<tls> constructor argument for general info.
1931 1944
1932Starting TLS is currently an asynchronous operation - when you push some 1945Starting TLS is currently an asynchronous operation - when you push some
1933write data and then call C<< ->starttls >> then TLS negotiation will start 1946write data and then call C<< ->starttls >> then TLS negotiation will start
1934immediately, after which the queued write data is then sent. 1947immediately, after which the queued write data is then sent. This might
1948change in future versions, so best make sure you have no outstanding write
1949data when calling this method.
1935 1950
1936The first argument is the same as the C<tls> constructor argument (either 1951The first argument is the same as the C<tls> constructor argument (either
1937C<"connect">, C<"accept"> or an existing Net::SSLeay object). 1952C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1938 1953
1939The second argument is the optional C<AnyEvent::TLS> object that is used 1954The second argument is the optional C<AnyEvent::TLS> object that is used
… …
1961 my ($self, $tls, $ctx) = @_; 1976 my ($self, $tls, $ctx) = @_;
1962 1977
1963 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught" 1978 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught"
1964 if $self->{tls}; 1979 if $self->{tls};
1965 1980
1981 unless (defined $AnyEvent::TLS::VERSION) {
1982 eval {
1983 require Net::SSLeay;
1984 require AnyEvent::TLS;
1985 1
1986 } or return $self->_error (Errno::EPROTO, 1, "TLS support not available on this system");
1987 }
1988
1966 $self->{tls} = $tls; 1989 $self->{tls} = $tls;
1967 $self->{tls_ctx} = $ctx if @_ > 2; 1990 $self->{tls_ctx} = $ctx if @_ > 2;
1968 1991
1969 return unless $self->{fh}; 1992 return unless $self->{fh};
1970 1993
1971 require Net::SSLeay;
1972
1973 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL (); 1994 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1974 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ (); 1995 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1975 1996
1976 $tls = delete $self->{tls}; 1997 $tls = delete $self->{tls};
1977 $ctx = $self->{tls_ctx}; 1998 $ctx = $self->{tls_ctx};
1978 1999
1979 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session 2000 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session
1980 2001
1981 if ("HASH" eq ref $ctx) { 2002 if ("HASH" eq ref $ctx) {
1982 require AnyEvent::TLS;
1983
1984 if ($ctx->{cache}) { 2003 if ($ctx->{cache}) {
1985 my $key = $ctx+0; 2004 my $key = $ctx+0;
1986 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx; 2005 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1987 } else { 2006 } else {
1988 $ctx = new AnyEvent::TLS %$ctx; 2007 $ctx = new AnyEvent::TLS %$ctx;
… …
2203Probably because your C<on_error> callback is being called instead: When 2222Probably because your C<on_error> callback is being called instead: When
2204you have outstanding requests in your read queue, then an EOF is 2223you have outstanding requests in your read queue, then an EOF is
2205considered an error as you clearly expected some data. 2224considered an error as you clearly expected some data.
2206 2225
2207To avoid this, make sure you have an empty read queue whenever your handle 2226To avoid this, make sure you have an empty read queue whenever your handle
2208is supposed to be "idle" (i.e. connection closes are O.K.). You cna set 2227is supposed to be "idle" (i.e. connection closes are O.K.). You can set
2209an C<on_read> handler that simply pushes the first read requests in the 2228an C<on_read> handler that simply pushes the first read requests in the
2210queue. 2229queue.
2211 2230
2212See also the next question, which explains this in a bit more detail. 2231See also the next question, which explains this in a bit more detail.
2213 2232
… …
2244some data and raises the C<EPIPE> error when the connction is dropped 2263some data and raises the C<EPIPE> error when the connction is dropped
2245unexpectedly. 2264unexpectedly.
2246 2265
2247The second variant is a protocol where the client can drop the connection 2266The second variant is a protocol where the client can drop the connection
2248at any time. For TCP, this means that the server machine may run out of 2267at any time. For TCP, this means that the server machine may run out of
2249sockets easier, and in general, it means you cnanot distinguish a protocl 2268sockets easier, and in general, it means you cannot distinguish a protocl
2250failure/client crash from a normal connection close. Nevertheless, these 2269failure/client crash from a normal connection close. Nevertheless, these
2251kinds of protocols are common (and sometimes even the best solution to the 2270kinds of protocols are common (and sometimes even the best solution to the
2252problem). 2271problem).
2253 2272
2254Having an outstanding read request at all times is possible if you ignore 2273Having an outstanding read request at all times is possible if you ignore
… …
2329C<low_water_mark> this will be called precisely when all data has been 2348C<low_water_mark> this will be called precisely when all data has been
2330written to the socket: 2349written to the socket:
2331 2350
2332 $handle->push_write (...); 2351 $handle->push_write (...);
2333 $handle->on_drain (sub { 2352 $handle->on_drain (sub {
2334 warn "all data submitted to the kernel\n"; 2353 AE::log debug => "All data submitted to the kernel.";
2335 undef $handle; 2354 undef $handle;
2336 }); 2355 });
2337 2356
2338If you just want to queue some data and then signal EOF to the other side, 2357If you just want to queue some data and then signal EOF to the other side,
2339consider using C<< ->push_shutdown >> instead. 2358consider using C<< ->push_shutdown >> instead.
… …
2423When you have intermediate CA certificates that your clients might not 2442When you have intermediate CA certificates that your clients might not
2424know about, just append them to the C<cert_file>. 2443know about, just append them to the C<cert_file>.
2425 2444
2426=back 2445=back
2427 2446
2428
2429=head1 SUBCLASSING AnyEvent::Handle 2447=head1 SUBCLASSING AnyEvent::Handle
2430 2448
2431In many cases, you might want to subclass AnyEvent::Handle. 2449In many cases, you might want to subclass AnyEvent::Handle.
2432 2450
2433To make this easier, a given version of AnyEvent::Handle uses these 2451To make this easier, a given version of AnyEvent::Handle uses these
… …
2459 2477
2460Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 2478Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
2461 2479
2462=cut 2480=cut
2463 2481
24641; # End of AnyEvent::Handle 24821
2483

Diff Legend

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