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.226 by root, Mon Dec 12 12:56:04 2011 UTC vs.
Revision 1.235 by root, Tue May 8 19:41:22 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 AE::log error => "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
… …
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
… …
417appropriate error message. 429appropriate error message.
418 430
419TLS mode requires Net::SSLeay to be installed (it will be loaded 431TLS mode requires Net::SSLeay to be installed (it will be loaded
420automatically 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
421have 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
422to 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.
423 436
424Unlike 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
425C<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>
426mode. 439mode.
427 440
… …
880 893
881The 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
882AnyEvent::Handle will automatically try to get rid of it for you. 895AnyEvent::Handle will automatically try to get rid of it for you.
883 896
884When 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
885water mark, the C<on_drain> callback will be invoked. 898water mark, the C<on_drain> callback will be invoked once.
886 899
887=over 4 900=over 4
888 901
889=item $handle->on_drain ($cb) 902=item $handle->on_drain ($cb)
890 903
… …
1476 if (@_ < 3) { 1489 if (@_ < 3) {
1477 # 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
1478 sub { 1491 sub {
1479 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1492 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
1480 1493
1481 $cb->($_[0], $1, $2); 1494 $cb->($_[0], "$1", "$2");
1482 1 1495 1
1483 } 1496 }
1484 } else { 1497 } else {
1485 $eol = quotemeta $eol unless ref $eol; 1498 $eol = quotemeta $eol unless ref $eol;
1486 $eol = qr|^(.*?)($eol)|s; 1499 $eol = qr|^(.*?)($eol)|s;
1487 1500
1488 sub { 1501 sub {
1489 $_[0]{rbuf} =~ s/$eol// or return; 1502 $_[0]{rbuf} =~ s/$eol// or return;
1490 1503
1491 $cb->($_[0], $1, $2); 1504 $cb->($_[0], "$1", "$2");
1492 1 1505 1
1493 } 1506 }
1494 } 1507 }
1495}; 1508};
1496 1509
… …
1724 1737
1725 # bypass unshift if we already have the remaining chunk 1738 # bypass unshift if we already have the remaining chunk
1726 if ($format + $len <= length $_[0]{rbuf}) { 1739 if ($format + $len <= length $_[0]{rbuf}) {
1727 my $data = substr $_[0]{rbuf}, $format, $len; 1740 my $data = substr $_[0]{rbuf}, $format, $len;
1728 substr $_[0]{rbuf}, 0, $format + $len, ""; 1741 substr $_[0]{rbuf}, 0, $format + $len, "";
1742
1729 $cb->($_[0], Storable::thaw ($data)); 1743 eval { $cb->($_[0], Storable::thaw ($data)); 1 }
1744 or return $_[0]->_error (Errno::EBADMSG);
1730 } else { 1745 } else {
1731 # remove prefix 1746 # remove prefix
1732 substr $_[0]{rbuf}, 0, $format, ""; 1747 substr $_[0]{rbuf}, 0, $format, "";
1733 1748
1734 # read remaining chunk 1749 # read remaining chunk
1735 $_[0]->unshift_read (chunk => $len, sub { 1750 $_[0]->unshift_read (chunk => $len, sub {
1736 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1751 eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
1737 $cb->($_[0], $ref);
1738 } else {
1739 $_[0]->_error (Errno::EBADMSG); 1752 or $_[0]->_error (Errno::EBADMSG);
1740 }
1741 }); 1753 });
1742 } 1754 }
1743 1755
1744 1 1756 1
1745 } 1757 }
… …
1850 my ($self, $err) = @_; 1862 my ($self, $err) = @_;
1851 1863
1852 return $self->_error ($!, 1) 1864 return $self->_error ($!, 1)
1853 if $err == Net::SSLeay::ERROR_SYSCALL (); 1865 if $err == Net::SSLeay::ERROR_SYSCALL ();
1854 1866
1855 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 ());
1856 1868
1857 # reduce error string to look less scary 1869 # reduce error string to look less scary
1858 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /; 1870 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1859 1871
1860 if ($self->{_on_starttls}) { 1872 if ($self->{_on_starttls}) {
… …
1926 1938
1927=item $handle->starttls ($tls[, $tls_ctx]) 1939=item $handle->starttls ($tls[, $tls_ctx])
1928 1940
1929Instead of starting TLS negotiation immediately when the AnyEvent::Handle 1941Instead of starting TLS negotiation immediately when the AnyEvent::Handle
1930object 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
1931C<starttls>. 1943C<starttls>. See the C<tls> constructor argument for general info.
1932 1944
1933Starting TLS is currently an asynchronous operation - when you push some 1945Starting TLS is currently an asynchronous operation - when you push some
1934write data and then call C<< ->starttls >> then TLS negotiation will start 1946write data and then call C<< ->starttls >> then TLS negotiation will start
1935immediately, 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.
1936 1950
1937The 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
1938C<"connect">, C<"accept"> or an existing Net::SSLeay object). 1952C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1939 1953
1940The 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
… …
1962 my ($self, $tls, $ctx) = @_; 1976 my ($self, $tls, $ctx) = @_;
1963 1977
1964 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"
1965 if $self->{tls}; 1979 if $self->{tls};
1966 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
1967 $self->{tls} = $tls; 1989 $self->{tls} = $tls;
1968 $self->{tls_ctx} = $ctx if @_ > 2; 1990 $self->{tls_ctx} = $ctx if @_ > 2;
1969 1991
1970 return unless $self->{fh}; 1992 return unless $self->{fh};
1971 1993
1972 require Net::SSLeay;
1973
1974 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL (); 1994 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1975 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ (); 1995 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1976 1996
1977 $tls = delete $self->{tls}; 1997 $tls = delete $self->{tls};
1978 $ctx = $self->{tls_ctx}; 1998 $ctx = $self->{tls_ctx};
1979 1999
1980 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
1981 2001
1982 if ("HASH" eq ref $ctx) { 2002 if ("HASH" eq ref $ctx) {
1983 require AnyEvent::TLS;
1984
1985 if ($ctx->{cache}) { 2003 if ($ctx->{cache}) {
1986 my $key = $ctx+0; 2004 my $key = $ctx+0;
1987 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx; 2005 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1988 } else { 2006 } else {
1989 $ctx = new AnyEvent::TLS %$ctx; 2007 $ctx = new AnyEvent::TLS %$ctx;
… …
2222handles requests until the server gets some QUIT command, causing it to 2240handles requests until the server gets some QUIT command, causing it to
2223close the connection first (highly desirable for a busy TCP server). A 2241close the connection first (highly desirable for a busy TCP server). A
2224client dropping the connection is an error, which means this variant can 2242client dropping the connection is an error, which means this variant can
2225detect an unexpected detection close. 2243detect an unexpected detection close.
2226 2244
2227To handle this case, always make sure you have a on-empty read queue, by 2245To handle this case, always make sure you have a non-empty read queue, by
2228pushing the "read request start" handler on it: 2246pushing the "read request start" handler on it:
2229 2247
2230 # we assume a request starts with a single line 2248 # we assume a request starts with a single line
2231 my @start_request; @start_request = (line => sub { 2249 my @start_request; @start_request = (line => sub {
2232 my ($hdl, $line) = @_; 2250 my ($hdl, $line) = @_;
… …
2330C<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
2331written to the socket: 2349written to the socket:
2332 2350
2333 $handle->push_write (...); 2351 $handle->push_write (...);
2334 $handle->on_drain (sub { 2352 $handle->on_drain (sub {
2335 AE::log debug => "all data submitted to the kernel\n"; 2353 AE::log debug => "All data submitted to the kernel.";
2336 undef $handle; 2354 undef $handle;
2337 }); 2355 });
2338 2356
2339If 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,
2340consider using C<< ->push_shutdown >> instead. 2358consider using C<< ->push_shutdown >> instead.
… …
2424When you have intermediate CA certificates that your clients might not 2442When you have intermediate CA certificates that your clients might not
2425know about, just append them to the C<cert_file>. 2443know about, just append them to the C<cert_file>.
2426 2444
2427=back 2445=back
2428 2446
2429
2430=head1 SUBCLASSING AnyEvent::Handle 2447=head1 SUBCLASSING AnyEvent::Handle
2431 2448
2432In many cases, you might want to subclass AnyEvent::Handle. 2449In many cases, you might want to subclass AnyEvent::Handle.
2433 2450
2434To make this easier, a given version of AnyEvent::Handle uses these 2451To make this easier, a given version of AnyEvent::Handle uses these
… …
2460 2477
2461Robin 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>.
2462 2479
2463=cut 2480=cut
2464 2481
24651; # End of AnyEvent::Handle 24821
2483

Diff Legend

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