view release on metacpan or  search on metacpan

lib/AnyEvent/Handle.pm  view on Meta::CPAN

=item on_wtimeout => $cb->($handle)

Called whenever the inactivity timeout passes. If you return from this
callback, then the timeout will be reset as if some activity had happened,
so this condition is not fatal in any way.

=item rbuf_max => <bytes>

If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
when the read buffer ever (strictly) exceeds this size. This is useful to
avoid some forms of denial-of-service attacks.

For example, a server accepting connections from untrusted sources should
be configured to accept only so-and-so much data that it cannot act on
(for example, when expecting a line, an attacker could send an unlimited
amount of data without a callback ever being called as long as the line
isn't finished).

=item wbuf_max => <bytes>

If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
when the write buffer ever (strictly) exceeds this size. This is useful to
avoid some forms of denial-of-service attacks.

Although the units of this parameter is bytes, this is the I<raw> number
of bytes not yet accepted by the kernel. This can make a difference when
you e.g. use TLS, as TLS typically makes your write data larger (but it
can also make it smaller due to compression).

As an example of when this limit is useful, take a chat server that sends
chat messages to a client. If the client does not read those in a timely
manner then the send buffer in the server would grow unbounded.

=item autocork => <boolean>

When disabled (the default), C<push_write> will try to immediately
write the data to the handle if possible. This avoids having to register
a write watcher and wait for the next event loop iteration, but can
be inefficient if you write multiple small chunks (on the wire, this
disadvantage is usually avoided by your kernel's nagle algorithm, see
C<no_delay>, but this option can save costly syscalls).

When enabled, writes will always be queued till the next event loop
iteration. This is efficient when you do many small writes per iteration,
but less efficient when you do a single write only per iteration (or when
the write buffer often is full). It also increases write latency.

=item no_delay => <boolean>

When doing small writes on sockets, your operating system kernel might
wait a bit for more data before actually sending it out. This is called
the Nagle algorithm, and usually it is beneficial.

In some situations you want as low a delay as possible, which can be
accomplishd by setting this option to a true value.

The default is your operating system's default behaviour (most likely
enabled). This option explicitly enables or disables it, if possible.

=item keepalive => <boolean>

Enables (default disable) the SO_KEEPALIVE option on the stream socket:
normally, TCP connections have no time-out once established, so TCP
connections, once established, can stay alive forever even when the other
side has long gone. TCP keepalives are a cheap way to take down long-lived
TCP connections when the other side becomes unreachable. While the default
is OS-dependent, TCP keepalives usually kick in after around two hours,
and, if the other side doesn't reply, take down the TCP connection some 10
to 15 minutes later.

It is harmless to specify this option for file handles that do not support
keepalives, and enabling it on connections that are potentially long-lived
is usually a good idea.

=item oobinline => <boolean>

BSD majorly fucked up the implementation of TCP urgent data. The result
is that almost no OS implements TCP according to the specs, and every OS
implements it slightly differently.

If you want to handle TCP urgent data, then setting this flag (the default
is enabled) gives you the most portable way of getting urgent data, by
putting it into the stream.

Since BSD emulation of OOB data on top of TCP's urgent data can have
security implications, AnyEvent::Handle sets this flag automatically
unless explicitly specified. Note that setting this flag after
establishing a connection I<may> be a bit too late (data loss could
already have occured on BSD systems), but at least it will protect you
from most attacks.

=item read_size => <bytes>

The initial read block size, the number of bytes this module will try
to read during each loop iteration. Each handle object will consume
at least this amount of memory for the read buffer as well, so when
handling many connections watch out for memory requirements). See also
C<max_read_size>. Default: C<2048>.

=item max_read_size => <bytes>

The maximum read buffer size used by the dynamic adjustment
algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in
one go it will double C<read_size> up to the maximum given by this
option. Default: C<131072> or C<read_size>, whichever is higher.

=item low_water_mark => <bytes>

Sets the number of bytes (default: C<0>) that make up an "empty" write
buffer: If the buffer reaches this size or gets even samller it is
considered empty.

Sometimes it can be beneficial (for performance reasons) to add data to
the write buffer before it is fully drained, but this is a rare case, as
the operating system kernel usually buffers data as well, so the default
is good in almost all cases.

=item linger => <seconds>

If this is non-zero (default: C<3600>), the destructor of the
AnyEvent::Handle object will check whether there is still outstanding
write data and will install a watcher that will write this data to the
socket. No errors will be reported (this mostly matches how the operating
system treats outstanding data at socket close time).

This will not work for partial TLS data that could not be encoded
yet. This data will be lost. Calling the C<stoptls> method in time might
help.

=item peername => $string

A string used to identify the remote site - usually the DNS hostname

lib/AnyEvent/Handle.pm  view on Meta::CPAN

                     delete $self->{_skip_drain_rbuf};
                     $self->_start;

                     $self->{on_connect}
                        and $self->{on_connect}($self, $host, $port, sub {
                               delete @$self{qw(fh _tw _rtw _wtw _ww _rw _eof _queue rbuf _wbuf tls _tls_rbuf _tls_wbuf)};
                               $self->{_skip_drain_rbuf} = 1;
                               &$retry;
                            });

                  } else {
                     if ($self->{on_connect_error}) {
                        $self->{on_connect_error}($self, "$!");
                        $self->destroy if $self;
                     } else {
                        $self->_error ($!, 1);
                     }
                  }
               },
               sub {
                  local $self->{fh} = $_[0];

                  $self->{on_prepare}
                     ? $self->{on_prepare}->($self)
                     : ()
               }
            );
      }

   } else {
      Carp::croak "AnyEvent::Handle: either an existing fh or the connect parameter must be specified";
   }

   $self
}

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::fh_unblock $self->{fh};

   $self->{_activity}  =
   $self->{_ractivity} =
   $self->{_wactivity} = AE::now;

   $self->{read_size} ||= 2048;
   $self->{max_read_size} = $self->{read_size}
      if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);

   $self->timeout   (delete $self->{timeout}  ) if $self->{timeout};
   $self->rtimeout  (delete $self->{rtimeout} ) if $self->{rtimeout};
   $self->wtimeout  (delete $self->{wtimeout} ) if $self->{wtimeout};

   $self->no_delay  (delete $self->{no_delay} ) if exists $self->{no_delay}  && $self->{no_delay};
   $self->keepalive (delete $self->{keepalive}) if exists $self->{keepalive} && $self->{keepalive};

   $self->oobinline (exists $self->{oobinline} ? delete $self->{oobinline} : 1);

   $self->starttls  (delete $self->{tls}, delete $self->{tls_ctx})
      if $self->{tls};

   $self->on_drain  (delete $self->{on_drain} ) if $self->{on_drain};

   $self->start_read
      if $self->{on_read} || @{ $self->{_queue} };

   $self->_drain_wbuf;
}

sub _error {
   my ($self, $errno, $fatal, $message) = @_;

   $! = $errno;
   $message ||= "$!";

   if ($self->{on_error}) {
      $self->{on_error}($self, $fatal, $message);
      $self->destroy if $fatal;
   } elsif ($self->{fh} || $self->{connect}) {
      $self->destroy;
      Carp::croak "AnyEvent::Handle uncaught error: $message";
   }
}

=item $fh = $handle->fh

This method returns the file handle used to create the L<AnyEvent::Handle> object.

=cut

sub fh { $_[0]{fh} }

=item $handle->on_error ($cb)

Replace the current C<on_error> callback (see the C<on_error> constructor argument).

=cut

sub on_error {
   $_[0]{on_error} = $_[1];
}

=item $handle->on_eof ($cb)

Replace the current C<on_eof> callback (see the C<on_eof> constructor argument).

=cut

sub on_eof {
   $_[0]{on_eof} = $_[1];
}

=item $handle->on_timeout ($cb)

=item $handle->on_rtimeout ($cb)

=item $handle->on_wtimeout ($cb)

Replace the current C<on_timeout>, C<on_rtimeout> or C<on_wtimeout>
callback, or disables the callback (but not the timeout) if C<$cb> =
C<undef>. See the C<timeout> constructor argument and method.

=cut

# see below

=item $handle->autocork ($boolean)

Enables or disables the current autocork behaviour (see C<autocork>
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).

=cut

sub no_delay {
   $_[0]{no_delay} = $_[1];

   setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1]
      if $_[0]{fh};
}

=item $handle->keepalive ($boolean)

Enables or disables the C<keepalive> setting (see constructor argument of
the same name for details).

=cut

sub keepalive {
   $_[0]{keepalive} = $_[1];

   eval {
      local $SIG{__DIE__};
      setsockopt $_[0]{fh}, Socket::SOL_SOCKET (), Socket::SO_KEEPALIVE (), int $_[1]
         if $_[0]{fh};
   };
}

=item $handle->oobinline ($boolean)

Enables or disables the C<oobinline> setting (see constructor argument of
the same name for details).

=cut

sub oobinline {
   $_[0]{oobinline} = $_[1];

   eval {
      local $SIG{__DIE__};
      setsockopt $_[0]{fh}, Socket::SOL_SOCKET (), Socket::SO_OOBINLINE (), int $_[1]
         if $_[0]{fh};
   };
}

=item $handle->on_starttls ($cb)

Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).

=cut

sub on_starttls {
   $_[0]{on_starttls} = $_[1];
}

=item $handle->on_stoptls ($cb)

Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).

=cut

sub on_stoptls {
   $_[0]{on_stoptls} = $_[1];
}

=item $handle->rbuf_max ($max_octets)

Configures the C<rbuf_max> setting (C<undef> disables it).

=item $handle->wbuf_max ($max_octets)

Configures the C<wbuf_max> setting (C<undef> disables it).

=cut

sub rbuf_max {
   $_[0]{rbuf_max} = $_[1];
}

sub wbuf_max {