--- AnyEvent/lib/AnyEvent/Handle.pm	2009/07/22 05:37:32	1.156
+++ AnyEvent/lib/AnyEvent/Handle.pm	2009/07/24 12:35:58	1.159
@@ -46,8 +46,7 @@
 =head1 DESCRIPTION
 
 This module is a helper module to make it easier to do event-based I/O on
-filehandles. For utility functions for doing non-blocking connects and accepts
-on sockets see L<AnyEvent::Util>.
+filehandles.
 
 The L<AnyEvent::Intro> tutorial contains some well-documented
 AnyEvent::Handle examples.
@@ -56,6 +55,9 @@
 means characters. As sysread and syswrite are used for all I/O, their
 treatment of characters applies to this module as well.
 
+At the very minimum, you should specify C<fh> or C<connect>, and the
+C<on_error> callback.
+
 All callbacks will be invoked with the handle object as their first
 argument.
 
@@ -69,29 +71,60 @@
 
 =over 4
 
-=item fh => $filehandle [MANDATORY]
+=item fh => $filehandle     [C<fh> or C<connect> MANDATORY]
 
 The filehandle this L<AnyEvent::Handle> object will operate on.
-
 NOTE: The filehandle will be set to non-blocking mode (using
 C<AnyEvent::Util::fh_nonblocking>) by the constructor and needs to stay in
 that mode.
 
-=item on_eof => $cb->($handle)
+=item connect => [$host, $service]      [C<fh> or C<connect> MANDATORY]
 
-Set the callback to be called when an end-of-file condition is detected,
-i.e. in the case of a socket, when the other side has closed the
-connection cleanly, and there are no outstanding read requests in the
-queue (if there are read requests, then an EOF counts as an unexpected
-connection close and will be flagged as an error).
+Try to connect to the specified host and service (port), using
+C<AnyEvent::Socket::tcp_connect>. The C<$host> additionally becomes the
+default C<peername>.
 
-For sockets, this just means that the other side has stopped sending data,
-you can still try to write data, and, in fact, one can return from the EOF
-callback and continue writing data, as only the read part has been shut
-down.
+You have to specify either this parameter, or C<fh>, above.
 
-If an EOF condition has been detected but no C<on_eof> callback has been
-set, then a fatal error will be raised with C<$!> set to <0>.
+When this parameter is specified, then the C<on_prepare>,
+C<on_connect_error> and C<on_connect> callbacks will be called under the
+appropriate circumstances:
+
+=over 4
+
+=item on_prepare => $cb->($handle)
+
+This (rarely used) callback is called before a new connection is
+attempted, but after the file handle has been created. It could be used to
+prepare the file handle with parameters required for the actual connect
+(as opposed to settings that can be changed when the connection is already
+established).
+
+=item on_connect => $cb->($handle, $host, $port, $retry->())
+
+This callback is called when a connection has been successfully established.
+
+The actual numeric host and port (the socket peername) are passed as
+parameters, together with a retry callback.
+
+When, for some reason, the handle is not acceptable, then calling
+C<$retry> will continue with the next conenction target (in case of
+multi-homed hosts or SRV records there can be multiple connection
+endpoints). When it is called then the read and write queues, eof status,
+tls status and similar properties of the handle are being reset.
+
+In most cases, ignoring the C<$retry> parameter is the way to go.
+
+=item on_connect_error => $cb->($handle, $message)
+
+This callback is called when the conenction could not be
+established. C<$!> will contain the relevant error code, and C<$message> a
+message describing it (usually the same as C<"$!">).
+
+If this callback isn't specified, then C<on_error> will be called with a
+fatal error instead.
+
+=back
 
 =item on_error => $cb->($handle, $fatal, $message)
 
@@ -103,7 +136,9 @@
 fatal errors the handle object will be destroyed (by a call to C<< ->
 destroy >>) after invoking the error callback (which means you are free to
 examine the handle object). Examples of fatal errors are an EOF condition
-with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors.
+with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors. In
+cases where the other side can close the connection at their will it is
+often easiest to not report C<EPIPE> errors in this callback.
 
 AnyEvent::Handle tries to find an appropriate error code for you to check
 against, but in some cases (TLS errors), this does not work well. It is
@@ -145,6 +180,22 @@
 are outstanding read requests then an error will be flagged. With an
 C<on_read> callback, the C<on_eof> callback will be invoked.
 
+=item on_eof => $cb->($handle)
+
+Set the callback to be called when an end-of-file condition is detected,
+i.e. in the case of a socket, when the other side has closed the
+connection cleanly, and there are no outstanding read requests in the
+queue (if there are read requests, then an EOF counts as an unexpected
+connection close and will be flagged as an error).
+
+For sockets, this just means that the other side has stopped sending data,
+you can still try to write data, and, in fact, one can return from the EOF
+callback and continue writing data, as only the read part has been shut
+down.
+
+If an EOF condition has been detected but no C<on_eof> callback has been
+set, then a fatal error will be raised with C<$!> set to <0>.
+
 =item on_drain => $cb->($handle)
 
 This sets the callback that is called when the write buffer becomes empty
@@ -352,7 +403,68 @@
    my $class = shift;
    my $self = bless { @_ }, $class;
 
-   $self->{fh} or Carp::croak "mandatory argument fh is missing";
+   if ($self->{fh}) {
+      $self->_start;
+      return unless $self->{fh}; # could be gone by now
+
+   } elsif ($self->{connect}) {
+      require AnyEvent::Socket;
+
+      $self->{peername} = $self->{connect}[0]
+         unless exists $self->{peername};
+
+      $self->{_skip_drain_rbuf} = 1;
+
+      {
+         Scalar::Util::weaken (my $self = $self);
+
+         $self->{_connect} =
+            AnyEvent::Socket::tcp_connect (
+               $self->{connect}[0],
+               $self->{connect}[1],
+               sub {
+                  my ($fh, $host, $port, $retry) = @_;
+
+                  if ($fh) {
+                     $self->{fh} = $fh;
+
+                     delete $self->{_skip_drain_rbuf};
+                     $self->_start;
+
+                     $self->{on_connect}
+                        and $self->{on_connect}($self, $host, $port, sub {
+                               delete @$self{qw(fh _tw _ww _rw _eof _queue rbuf _wbuf tls _tls_rbuf _tls_wbuf)};
+                               $self->{_skip_drain_rbuf} = 1;
+                               &$retry;
+                            });
+
+                  } else {
+                     if ($self->{on_connect_error}) {
+                        $self->{on_connect_error}($self, "$!");
+                        $self->destroy;
+                     } else {
+                        $self->fatal ($!, 1);
+                     }
+                  }
+               },
+               sub {
+                  local $self->{fh} = $_[0];
+
+                  $self->{on_prepare}->($self)
+                     if $self->{on_prepare};
+               }
+            );
+      }
+
+   } else {
+      Carp::croak "AnyEvent::Handle: either an existing fh or the connect parameter must be specified";
+   }
+
+   $self
+}
+
+sub _start {
+   my ($self) = @_;
 
    AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
 
@@ -367,9 +479,7 @@
    $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
 
    $self->start_read
-      if $self->{on_read};
-
-   $self->{fh} && $self
+      if $self->{on_read} || @{ $self->{_queue} };
 }
 
 #sub _shutdown {
@@ -459,7 +569,8 @@
 
    eval {
       local $SIG{__DIE__};
-      setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
+      setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1]
+         if $_[0]{fh};
    };
 }
 
@@ -503,7 +614,7 @@
 sub _timeout {
    my ($self) = @_;
 
-   if ($self->{timeout}) {
+   if ($self->{timeout} && $self->{fh}) {
       my $NOW = AnyEvent->now;
 
       # when would the timeout trigger?
@@ -635,7 +746,7 @@
       &_dotls ($self);
    } else {
       $self->{wbuf} .= $_[0];
-      $self->_drain_wbuf;
+      $self->_drain_wbuf if $self->{fh};
    }
 }
 
@@ -862,7 +973,9 @@
 sub _drain_rbuf {
    my ($self) = @_;
 
-   local $self->{_in_drain} = 1;
+   # avoid recursion
+   return if exists $self->{_skip_drain_rbuf};
+   local $self->{_skip_drain_rbuf} = 1;
 
    if (
       defined $self->{rbuf_max}
@@ -939,7 +1052,7 @@
    my ($self, $cb) = @_;
 
    $self->{on_read} = $cb;
-   $self->_drain_rbuf if $cb && !$self->{_in_drain};
+   $self->_drain_rbuf if $cb;
 }
 
 =item $handle->rbuf
@@ -1001,7 +1114,7 @@
    }
 
    push @{ $self->{_queue} }, $cb;
-   $self->_drain_rbuf unless $self->{_in_drain};
+   $self->_drain_rbuf;
 }
 
 sub unshift_read {
@@ -1017,7 +1130,7 @@
 
 
    unshift @{ $self->{_queue} }, $cb;
-   $self->_drain_rbuf unless $self->{_in_drain};
+   $self->_drain_rbuf;
 }
 
 =item $handle->push_read (type => @args, $cb)
@@ -1420,13 +1533,13 @@
 
                &_dotls ($self);
             } else {
-               $self->_drain_rbuf unless $self->{_in_drain};
+               $self->_drain_rbuf;
             }
 
          } elsif (defined $len) {
             delete $self->{_rw};
             $self->{_eof} = 1;
-            $self->_drain_rbuf unless $self->{_in_drain};
+            $self->_drain_rbuf;
 
          } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
             return $self->_error ($!, 1);
@@ -1496,7 +1609,7 @@
       }
 
       $self->{_tls_rbuf} .= $tmp;
-      $self->_drain_rbuf unless $self->{_in_drain};
+      $self->_drain_rbuf;
       $self->{tls} or return; # tls session might have gone away in callback
    }
 
@@ -1521,6 +1634,10 @@
 object is created, you can also do that at a later time by calling
 C<starttls>.
 
+Starting TLS is currently an asynchronous operation - when you push some
+write data and then call C<< ->starttls >> then TLS negotiation will start
+immediately, after which the queued write data is then sent.
+
 The first argument is the same as the C<tls> constructor argument (either
 C<"connect">, C<"accept"> or an existing Net::SSLeay object).
 
@@ -1554,11 +1671,11 @@
 
    $ctx ||= $self->{tls_ctx};
 
+   local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session
+
    if ("HASH" eq ref $ctx) {
       require AnyEvent::TLS;
 
-      local $Carp::CarpLevel = 1; # skip ourselves when creating a new context
-
       if ($ctx->{cache}) {
          my $key = $ctx+0;
          $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;