--- AnyEvent/lib/AnyEvent/Handle.pm	2012/02/06 00:17:26	1.228
+++ AnyEvent/lib/AnyEvent/Handle.pm	2012/04/18 09:44:10	1.234
@@ -13,7 +13,7 @@
       fh => \*STDIN,
       on_error => sub {
          my ($hdl, $fatal, $msg) = @_;
-         AE::log error => "got error $msg\n";
+         AE::log error => $msg;
          $hdl->destroy;
          $cv->send;
       };
@@ -172,9 +172,15 @@
 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
-recommended to always output the C<$message> argument in human-readable
-error messages (it's usually the same as C<"$!">).
+against, but in some cases (TLS errors), this does not work well.
+
+If you report the error to the user, it is recommended to always output
+the C<$message> argument in human-readable error messages (you don't need
+to report C<"$!"> if you report C<$message>).
+
+If you want to react programmatically to the error, then looking at C<$!>
+and comparing it against some of the documented C<Errno> values is usually
+better than looking at the C<$message>.
 
 Non-fatal errors can be retried by returning, but it is recommended
 to simply ignore this parameter and instead abondon the handle object
@@ -232,8 +238,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.
 
@@ -425,7 +431,8 @@
 TLS mode requires Net::SSLeay to be installed (it will be loaded
 automatically when you try to create a TLS handle): this module doesn't
 have a dependency on that module, so if your module requires it, you have
-to add the dependency yourself.
+to add the dependency yourself. If Net::SSLeay cannot be loaded or is too
+old, you get an C<EPROTO> error.
 
 Unlike TCP, TLS has a server and client side: for the TLS server side, use
 C<accept>, and for the TLS client side of a connection, use C<connect>
@@ -888,7 +895,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
 
@@ -1732,18 +1739,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);
          });
       }
 
@@ -1858,7 +1864,7 @@
    return $self->_error ($!, 1)
       if $err == Net::SSLeay::ERROR_SYSCALL ();
 
-   my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
+   my $err = Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
 
    # reduce error string to look less scary
    $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
@@ -1934,11 +1940,13 @@
 
 Instead of starting TLS negotiation immediately when the AnyEvent::Handle
 object is created, you can also do that at a later time by calling
-C<starttls>.
+C<starttls>. See the C<tls> constructor argument for general info.
 
 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.
+immediately, after which the queued write data is then sent. This might
+change in future versions, so best make sure you have no outstanding write
+data when calling this method.
 
 The first argument is the same as the C<tls> constructor argument (either
 C<"connect">, C<"accept"> or an existing Net::SSLeay object).
@@ -1970,13 +1978,19 @@
    Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught"
       if $self->{tls};
 
+   unless (defined $AnyEvent::TLS::VERSION) {
+      eval {
+         require Net::SSLeay;
+         require AnyEvent::TLS;
+         1
+      } or return $self->_error (Errno::EPROTO, 1, "TLS support not available on this system");
+   }
+
    $self->{tls}     = $tls;
    $self->{tls_ctx} = $ctx if @_ > 2;
 
    return unless $self->{fh};
 
-   require Net::SSLeay;
-
    $ERROR_SYSCALL   = Net::SSLeay::ERROR_SYSCALL     ();
    $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ   ();
 
@@ -1986,8 +2000,6 @@
    local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session
 
    if ("HASH" eq ref $ctx) {
-      require AnyEvent::TLS;
-
       if ($ctx->{cache}) {
          my $key = $ctx+0;
          $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
@@ -2338,7 +2350,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;
    });
 
@@ -2432,7 +2444,6 @@
 
 =back
 
-
 =head1 SUBCLASSING AnyEvent::Handle
 
 In many cases, you might want to subclass AnyEvent::Handle.
@@ -2468,4 +2479,5 @@
 
 =cut
 
-1; # End of AnyEvent::Handle
+1
+