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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.188 by root, Thu Sep 17 08:20:14 2009 UTC vs.
Revision 1.195 by root, Sat Jun 5 09:08:14 2010 UTC

 =head1 NAME
-AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
+AnyEvent::Handle - non-blocking I/O on streaming handles via AnyEvent
 =head1 SYNOPSIS
    use AnyEvent;
    use AnyEvent::Handle;
    $cv->recv;
 =head1 DESCRIPTION
 This module is a helper module to make it easier to do event-based I/O on
-filehandles.
+stream-based filehandles (sockets, pipes or other stream things).
 The L<AnyEvent::Intro> tutorial contains some well-documented
 AnyEvent::Handle examples.
 In the following, when the documentation refers to of "bytes" then this
 =head1 METHODS
 =over 4
-=item $handle = B<new> AnyEvent::TLS fh => $filehandle, key => value...
+=item $handle = B<new> AnyEvent::Handle fh => $filehandle, key => value...
 The constructor supports these arguments (all as C<< key => value >> pairs).
 =over 4
 }
 sub _start {
    my ($self) = @_;
+   # too many clueless people try to use udp and similar sockets
+   # with AnyEvent::Handle, do them a favour.
+   my $type = getsockopt $self->{fh}, Socket::SOL_SOCKET (), Socket::SO_TYPE ();
+   Carp::croak "AnyEvent::Handle: only stream sockets supported, anything else will NOT work!"
+      if Socket::SOCK_STREAM != (unpack "I", $type) && defined $type;
    AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
    $self->{_activity}  =
    $self->{_ractivity} =
    $self->{_wactivity} = AE::now;
 Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
 =cut
-sub on_starttls {
+sub on_stoptls {
    $_[0]{on_stoptls} = $_[1];
 }
 =item $handle->rbuf_max ($max_octets)
 =item $handle->on_drain ($cb)
 Sets the C<on_drain> callback or clears it (see the description of
 C<on_drain> in the constructor).
+This method may invoke callbacks (and therefore the handle might be
+destroyed after it returns).
 =cut
 sub on_drain {
    my ($self, $cb) = @_;
 =item $handle->push_write ($data)
 Queues the given scalar to be written. You can push as much data as you
 want (only limited by the available memory), as C<AnyEvent::Handle>
 buffers it independently of the kernel.
+This method may invoke callbacks (and therefore the handle might be
+destroyed after it returns).
 =cut
 sub _drain_wbuf {
    my ($self) = @_;
       @_ = ($WH{$type} ||= _load_func "$type\::anyevent_write_type"
             or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::push_write")
            ->($self, @_);
    }
+   # we downgrade here to avoid hard-to-track-down bugs,
+   # and diagnose the problem earlier and better.
    if ($self->{tls}) {
-      $self->{_tls_wbuf} .= $_[0];
+      utf8::downgrade $self->{_tls_wbuf} .= $_[0];
       &_dotls ($self)    if $self->{fh};
    } else {
-      $self->{wbuf}      .= $_[0];
+      utf8::downgrade $self->{wbuf}      .= $_[0];
       $self->_drain_wbuf if $self->{fh};
    }
 }
 =item $handle->push_write (type => @args)
 This simply shuts down the write side and signals an EOF condition to the
 the peer.
 You can rely on the normal read queue and C<on_eof> handling
 afterwards. This is the cleanest way to close a connection.
+This method may invoke callbacks (and therefore the handle might be
+destroyed after it returns).
 =cut
 sub push_shutdown {
    my ($self) = @_;
 This replaces the currently set C<on_read> callback, or clears it (when
 the new callback is C<undef>). See the description of C<on_read> in the
 constructor.
+This method may invoke callbacks (and therefore the handle might be
+destroyed after it returns).
 =cut
 sub on_read {
    my ($self, $cb) = @_;
 available (or an error condition is detected).
 If enough data was available, then the callback must remove all data it is
 interested in (which can be none at all) and return a true value. After returning
 true, it will be removed from the queue.
+These methods may invoke callbacks (and therefore the handle might be
+destroyed after it returns).
 =cut
 our %RH;
 }
 sub start_read {
    my ($self) = @_;
-   unless ($self->{_rw} || $self->{_eof}) {
+   unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) {
       Scalar::Util::weaken $self;
       $self->{_rw} = AE::io $self->{fh}, 0, sub {
          my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
          my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf;
          && ($tmp != $ERROR_SYSCALL || $!);
    while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
       $self->{wbuf} .= $tmp;
       $self->_drain_wbuf;
+      $self->{tls} or return; # tls session might have gone away in callback
    }
    $self->{_on_starttls}
       and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
       and (delete $self->{_on_starttls})->($self, 1, "TLS/SSL connection established");
 when this function returns.
 Due to bugs in OpenSSL, it might or might not be possible to do multiple
 handshakes on the same stream. Best do not attempt to use the stream after
 stopping TLS.
+This method may invoke callbacks (and therefore the handle might be
+destroyed after it returns).
 =cut
 our %TLS_CACHE; #TODO not yet documented, should we?
 =item $handle->stoptls
 Shuts down the SSL connection - this makes a proper EOF handshake by
 sending a close notify to the other side, but since OpenSSL doesn't
-support non-blocking shut downs, it is not guarenteed that you can re-use
+support non-blocking shut downs, it is not guaranteed that you can re-use
 the stream afterwards.
+This method may invoke callbacks (and therefore the handle might be
+destroyed after it returns).
 =cut
 sub stoptls {
    my ($self) = @_;
-   if ($self->{tls}) {
+   if ($self->{tls} && $self->{fh}) {
       Net::SSLeay::shutdown ($self->{tls});
       &_dotls;
 #      # we don't give a shit. no, we do, but we can't. no...#d#
 sub AnyEvent::Handle::destroyed::AUTOLOAD {
    #nop
 }
+=item $handle->destroyed
+Returns false as long as the handle hasn't been destroyed by a call to C<<
+->destroy >>, true otherwise.
+Can be useful to decide whether the handle is still valid after some
+callback possibly destroyed the handle. For example, C<< ->push_write >>,
+C<< ->starttls >> and other methods can call user callbacks, which in turn
+can destroy the handle, so work can be avoided by checking sometimes:
+   $hdl->starttls ("accept");
+   return if $hdl->destroyed;
+   $hdl->push_write (...
+Note that the call to C<push_write> will silently be ignored if the handle
+has been destroyed, so often you can just ignore the possibility of the
+handle being destroyed.
+=cut
+sub destroyed { 0 }
+sub AnyEvent::Handle::destroyed::destroyed { 1 }
 =item AnyEvent::Handle::TLS_CTX
 This function creates and returns the AnyEvent::TLS object used by default
 for TLS mode.

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.188 by root, Thu Sep 17 08:20:14 2009 UTC vs. Revision 1.195 by root, Sat Jun 5 09:08:14 2010 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.188 by root, Thu Sep 17 08:20:14 2009 UTC vs.
Revision 1.195 by root, Sat Jun 5 09:08:14 2010 UTC