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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.93 by root, Wed Oct 1 14:49:23 2008 UTC vs.
Revision 1.99 by root, Thu Oct 23 02:41:00 2008 UTC

 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)>
    $self->{fh} or Carp::croak "mandatory argument fh is missing";
    AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
-   if ($self->{tls}) {
-      require Net::SSLeay;
-      $self->starttls (delete $self->{tls}, delete $self->{tls_ctx});
+   $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
-   }
+      if $self->{tls};
    $self->{_activity} = AnyEvent->now;
    $self->_timeout;
    $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
            ->($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 {
          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])
 =cut
 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"
       if $self->{tls};
    if ($ssl eq "accept") {
 sub stoptls {
    my ($self) = @_;
    if ($self->{tls}) {
-      Net::SSLeay::shutdown $self->{tls};
+      Net::SSLeay::shutdown ($self->{tls});
       &_dotls;
       # we don't give a shit. no, we do, but we can't. no...
       # we, we... have to use openssl :/
          @linger = ();
       });
    }
 }
+=item $handle->destroy
+Shut's 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.
+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 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 transfering 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;
+   });
+=item I get different callback invocations in TLS mode/Why can't I pause
+reading?
+Unlike, say, TCP, TLS conenctions 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.
+=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.93 by root, Wed Oct 1 14:49:23 2008 UTC vs. Revision 1.99 by root, Thu Oct 23 02:41:00 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.93 by root, Wed Oct 1 14:49:23 2008 UTC vs.
Revision 1.99 by root, Thu Oct 23 02:41:00 2008 UTC