--- AnyEvent/lib/AnyEvent/Handle.pm	2012/01/10 13:32:23	1.227
+++ AnyEvent/lib/AnyEvent/Handle.pm	2012/03/30 03:11:17	1.232
@@ -13,7 +13,7 @@
       fh => \*STDIN,
       on_error => sub {
          my ($hdl, $fatal, $msg) = @_;
-         AE::log error => "got error $msg\n";
+         AE::log error => "Got error $msg!";
          $hdl->destroy;
          $cv->send;
       };
@@ -130,13 +130,19 @@
 This callback is called when a connection has been successfully established.
 
 The peer's numeric host and port (the socket peername) are passed as
-parameters, together with a retry callback.
-
-If, for some reason, the handle is not acceptable, calling C<$retry>
-will continue with the next connection target (in case of multi-homed
-hosts or SRV records there can be multiple connection endpoints). At the
-time it is called the read and write queues, eof status, tls status and
-similar properties of the handle will have been reset.
+parameters, together with a retry callback. At the time it is called the
+read and write queues, EOF status, TLS status and similar properties of
+the handle will have been reset.
+
+It is not allowed to use the read or write queues while the handle object
+is connecting.
+
+If, for some reason, the handle is not acceptable, calling C<$retry> will
+continue with the next connection target (in case of multi-homed hosts or
+SRV records there can be multiple connection endpoints). The C<$retry>
+callback can be invoked after the connect callback returns, i.e. one can
+start a handshake and then decide to retry with the next host if the
+handshake fails.
 
 In most cases, you should ignore the C<$retry> parameter.
 
@@ -226,8 +232,8 @@
 
 =item on_drain => $cb->($handle)
 
-This sets the callback that is called when the write buffer becomes empty
-(or immediately if the buffer is empty already).
+This sets the callback that is called once when the write buffer becomes
+empty (and immediately when the handle object is created).
 
 To append to the write buffer, use the C<< ->push_write >> method.
 
@@ -882,7 +888,7 @@
 AnyEvent::Handle will automatically try to get rid of it for you.
 
 When data could be written and the write buffer is shorter then the low
-water mark, the C<on_drain> callback will be invoked.
+water mark, the C<on_drain> callback will be invoked once.
 
 =over 4
 
@@ -1726,18 +1732,17 @@
       if ($format + $len <= length $_[0]{rbuf}) {
          my $data = substr $_[0]{rbuf}, $format, $len;
          substr $_[0]{rbuf}, 0, $format + $len, "";
-         $cb->($_[0], Storable::thaw ($data));
+
+         eval { $cb->($_[0], Storable::thaw ($data)); 1 }
+            or return $_[0]->_error (Errno::EBADMSG);
       } else {
          # remove prefix
          substr $_[0]{rbuf}, 0, $format, "";
 
          # read remaining chunk
          $_[0]->unshift_read (chunk => $len, sub {
-            if (my $ref = eval { Storable::thaw ($_[1]) }) {
-               $cb->($_[0], $ref);
-            } else {
-               $_[0]->_error (Errno::EBADMSG);
-            }
+            eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
+               or $_[0]->_error (Errno::EBADMSG);
          });
       }
 
@@ -2332,7 +2337,7 @@
 
    $handle->push_write (...);
    $handle->on_drain (sub {
-      AE::log debug => "all data submitted to the kernel\n";
+      AE::log debug => "All data submitted to the kernel.";
       undef $handle;
    });
 
@@ -2426,7 +2431,6 @@
 
 =back
 
-
 =head1 SUBCLASSING AnyEvent::Handle
 
 In many cases, you might want to subclass AnyEvent::Handle.
@@ -2462,4 +2466,5 @@
 
 =cut
 
-1; # End of AnyEvent::Handle
+1
+