[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Handle.pm

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.94 by root, Wed Oct 1 15:50:33 2008 UTC vs.
Revision 1.112 by root, Wed Jan 21 06:01:35 2009 UTC

 AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
 =cut
-our $VERSION = 4.3;
+our $VERSION = 4.331;
 =head1 SYNOPSIS
    use AnyEvent;
    use AnyEvent::Handle;
    my $handle =
       AnyEvent::Handle->new (
          fh => \*STDIN,
          on_eof => sub {
-            $cv->broadcast;
+            $cv->send;
          },
       );
    # send some request line
    $handle->push_write ("getinfo\015\012");
 treatment of characters applies to this module as well.
 All callbacks will be invoked with the handle object as their first
 argument.
-=head2 SIGPIPE is not handled by this module
-SIGPIPE is not handled by this module, so one of the practical
-requirements of using it is to ignore SIGPIPE (C<$SIG{PIPE} =
-'IGNORE'>). At least, this is highly recommend in a networked program: If
-you use AnyEvent::Handle in a filter program (like sort), exiting on
-SIGPIPE is probably the right thing to do.
 =head1 METHODS
 =over 4
 =item B<new (%args)>
 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.
 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
+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.
-While not mandatory, it is I<highly> recommended to set an eof callback,
+While not mandatory, it is I<highly> recommended to set an EOF callback,
 otherwise you might end up with a closed socket while you are still
 waiting for data.
 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>.
 You can also provide your own TLS connection object, but you have
 to make sure that you call either C<Net::SSLeay::set_connect_state>
 or C<Net::SSLeay::set_accept_state> on it before you pass it to
 AnyEvent::Handle.
+B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
+passing in the wrong integer will lead to certain crash. This most often
+happens when one uses a stylish C<< tls => 1 >> and is surprised about the
+segmentation fault.
 See the C<< ->starttls >> method for when need to start TLS negotiation later.
 =item tls_ctx => $ssl_ctx
 Use the given C<Net::SSLeay::CTX> object to create the new TLS connection
    $! = $errno;
    if ($self->{on_error}) {
       $self->{on_error}($self, $fatal);
-   } else {
+   } elsif ($self->{fh}) {
       Carp::croak "AnyEvent::Handle uncaught error: $!";
    }
 }
 =item $fh = $handle->fh
 }
 =item $handle->autocork ($boolean)
 Enables or disables the current autocork behaviour (see C<autocork>
-constructor argument).
+constructor argument). Changes will only take effect on the next write.
 =cut
+sub autocork {
+   $_[0]{autocork} = $_[1];
+}
 =item $handle->no_delay ($boolean)
 Enables or disables the C<no_delay> setting (see constructor argument of
 the same name for details).
            ->($self, @_);
    }
    if ($self->{tls}) {
       $self->{_tls_wbuf} .= $_[0];
       &_dotls ($self);
    } else {
       $self->{wbuf} .= $_[0];
       $self->_drain_wbuf;
    }
 =cut
 register_write_type netstring => sub {
    my ($self, $string) = @_;
-   sprintf "%d:%s,", (length $string), $string
+   (length $string) . ":$string,"
 };
 =item packstring => $format, $data
 An octet string prefixed with an encoded length. The encoding C<$format>
 An octet string prefixed with an encoded length. The encoding C<$format>
 uses the same format as a Perl C<pack> format, but must specify a single
 integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an
 optional C<!>, C<< < >> or C<< > >> modifier).
-DNS over TCP uses a prefix of C<n>, EPP uses a prefix of C<N>.
+For example, DNS over TCP uses a prefix of C<n> (2 octet network order),
+EPP uses a prefix of C<N> (4 octtes).
 Example: read a block of data prefixed by its length in BER-encoded
 format (very efficient).
    $handle->push_read (packstring => "w", sub {
    }
 };
 =item json => $cb->($handle, $hash_or_arrayref)
-Reads a JSON object or array, decodes it and passes it to the callback.
+Reads a JSON object or array, decodes it and passes it to the
+callback. When a parse error occurs, an C<EBADMSG> error will be raised.
 If a C<json> object was passed to the constructor, then that will be used
 for the final decode, otherwise it will create a JSON coder expecting UTF-8.
 This read type uses the incremental parser available with JSON version
    my $rbuf = \$self->{rbuf};
    my $json = $self->{json} ||= JSON->new->utf8;
    sub {
+      eval {
-      my $ref = $json->incr_parse ($self->{rbuf});
+         my $ref = $json->incr_parse ($self->{rbuf});
-      if ($ref) {
+         if ($ref) {
+            $self->{rbuf} = $json->incr_text;
+            $json->incr_text = "";
+            $cb->($self, $ref);
+            1
+         } else {
+            $self->{rbuf} = "";
+            ()
+         }
+         1
+      } or do {
+         # error case
+         $json->incr_skip;
          $self->{rbuf} = $json->incr_text;
          $json->incr_text = "";
-         $cb->($self, $ref);
-         1
+         $self->_error (&Errno::EBADMSG);
-      } else {
-         $self->{rbuf} = "";
-         ()
-      }
+      };
    }
 };
 =item storable => $cb->($handle, $ref)
          if ($len > 0) {
             $self->{_activity} = AnyEvent->now;
             if ($self->{tls}) {
                Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
                &_dotls ($self);
             } else {
                $self->_drain_rbuf unless $self->{_in_drain};
             }
          }
       });
    }
 }
+# poll the write BIO and send the data if applicable
 sub _dotls {
    my ($self) = @_;
-   my $buf;
+   my $tmp;
    if (length $self->{_tls_wbuf}) {
-      while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
+      while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
-         substr $self->{_tls_wbuf}, 0, $len, "";
+         substr $self->{_tls_wbuf}, 0, $tmp, "";
       }
    }
-   while (defined ($buf = Net::SSLeay::read ($self->{tls}))) {
+   while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
-      unless (length $buf) {
+      unless (length $tmp) {
          # let's treat SSL-eof as we treat normal EOF
          delete $self->{_rw};
          $self->{_eof} = 1;
          &_freetls;
       }
-      $self->{rbuf} .= $buf;
+      $self->{rbuf} .= $tmp;
       $self->_drain_rbuf unless $self->{_in_drain};
       $self->{tls} or return; # tls session might have gone away in callback
    }
-   my $err = Net::SSLeay::get_error ($self->{tls}, -1);
+   $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
-   if ($err!= Net::SSLeay::ERROR_WANT_READ ()) {
+   if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
-      if ($err == Net::SSLeay::ERROR_SYSCALL ()) {
+      if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
          return $self->_error ($!, 1);
-      } elsif ($err == Net::SSLeay::ERROR_SSL ())  {
+      } elsif ($tmp == Net::SSLeay::ERROR_SSL ())  {
          return $self->_error (&Errno::EIO, 1);
       }
-      # all others are fine for our purposes
+      # all other errors are fine for our purposes
    }
-   if (length ($buf = Net::SSLeay::BIO_read ($self->{_wbio}))) {
+   while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
-      $self->{wbuf} .= $buf;
+      $self->{wbuf} .= $tmp;
       $self->_drain_wbuf;
    }
 }
 =item $handle->starttls ($tls[, $tls_ctx])
 sub starttls {
    my ($self, $ssl, $ctx) = @_;
    require Net::SSLeay;
-   Carp::croak "it is an error to call starttls more than once on an Anyevent::Handle object"
+   Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
       if $self->{tls};
    if ($ssl eq "accept") {
       $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
       Net::SSLeay::set_accept_state ($ssl);
          @linger = ();
       });
    }
 }
+=item $handle->destroy
+Shuts down the handle object as much as possible - this call ensures that
+no further callbacks will be invoked and resources will be freed as much
+as possible. You must not call any methods on the object afterwards.
+Normally, you can just "forget" any references to an AnyEvent::Handle
+object and it will simply shut down. This works in fatal error and EOF
+callbacks, as well as code outside. It does I<NOT> work in a read or write
+callback, so when you want to destroy the AnyEvent::Handle object from
+within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
+that case.
+The handle might still linger in the background and write out remaining
+data, as specified by the C<linger> option, however.
+=cut
+sub destroy {
+   my ($self) = @_;
+   $self->DESTROY;
+   %$self = ();
+}
 =item AnyEvent::Handle::TLS_CTX
 This function creates and returns the Net::SSLeay::CTX object used by
 default for TLS mode.
    }
 }
 =back
+=head1 NONFREQUENTLY ASKED QUESTIONS
+=over 4
+=item I C<undef> the AnyEvent::Handle reference inside my callback and
+still get further invocations!
+That's because AnyEvent::Handle keeps a reference to itself when handling
+read or write callbacks.
+It is only safe to "forget" the reference inside EOF or error callbacks,
+from within all other callbacks, you need to explicitly call the C<<
+->destroy >> method.
+=item I get different callback invocations in TLS mode/Why can't I pause
+reading?
+Unlike, say, TCP, TLS connections do not consist of two independent
+communication channels, one for each direction. Or put differently. The
+read and write directions are not independent of each other: you cannot
+write data unless you are also prepared to read, and vice versa.
+This can mean than, in TLS mode, you might get C<on_error> or C<on_eof>
+callback invocations when you are not expecting any read data - the reason
+is that AnyEvent::Handle always reads in TLS mode.
+During the connection, you have to make sure that you always have a
+non-empty read-queue, or an C<on_read> watcher. At the end of the
+connection (or when you no longer want to use it) you can call the
+C<destroy> method.
+=item How do I read data until the other side closes the connection?
+If you just want to read your data into a perl scalar, the easiest way
+to achieve this is by setting an C<on_read> callback that does nothing,
+clearing the C<on_eof> callback and in the C<on_error> callback, the data
+will be in C<$_[0]{rbuf}>:
+   $handle->on_read (sub { });
+   $handle->on_eof (undef);
+   $handle->on_error (sub {
+      my $data = delete $_[0]{rbuf};
+      undef $handle;
+   });
+The reason to use C<on_error> is that TCP connections, due to latencies
+and packets loss, might get closed quite violently with an error, when in
+fact, all data has been received.
+It is usually better to use acknowledgements when transferring data,
+to make sure the other side hasn't just died and you got the data
+intact. This is also one reason why so many internet protocols have an
+explicit QUIT command.
+=item I don't want to destroy the handle too early - how do I wait until
+all data has been written?
+After writing your last bits of data, set the C<on_drain> callback
+and destroy the handle in there - with the default setting of
+C<low_water_mark> this will be called precisely when all data has been
+written to the socket:
+   $handle->push_write (...);
+   $handle->on_drain (sub {
+      warn "all data submitted to the kernel\n";
+      undef $handle;
+   });
+=back
 =head1 SUBCLASSING AnyEvent::Handle
 In many cases, you might want to subclass AnyEvent::Handle.
 To make this easier, a given version of AnyEvent::Handle uses these

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.94 by root, Wed Oct 1 15:50:33 2008 UTC vs. Revision 1.112 by root, Wed Jan 21 06:01:35 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.94 by root, Wed Oct 1 15:50:33 2008 UTC vs.
Revision 1.112 by root, Wed Jan 21 06:01:35 2009 UTC