package AnyEvent::Handle;

no warnings;
use strict;

use AnyEvent ();
use AnyEvent::Util qw(WSAEWOULDBLOCK);
use Scalar::Util ();
use Carp ();
use Fcntl ();
use Errno qw(EAGAIN EINTR);

=head1 NAME

AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent

=cut

our $VERSION = 4.151;

=head1 SYNOPSIS

   use AnyEvent;
   use AnyEvent::Handle;

   my $cv = AnyEvent->condvar;

   my $handle =
      AnyEvent::Handle->new (
         fh => \*STDIN,
         on_eof => sub {
            $cv->broadcast;
         },
      );

   # send some request line
   $handle->push_write ("getinfo\015\012");

   # read the response line
   $handle->push_read (line => sub {
      my ($handle, $line) = @_;
      warn "read line <$line>\n";
      $cv->send;
   });

   $cv->recv;

=head1 DESCRIPTION

This module is a helper module to make it easier to do event-based I/O on
filehandles. For utility functions for doing non-blocking connects and accepts
on sockets see L<AnyEvent::Util>.

In the following, when the documentation refers to of "bytes" then this
means characters. As sysread and syswrite are used for all I/O, their
treatment of characters applies to this module as well.

All callbacks will be invoked with the handle object as their first
argument.

=head1 METHODS

=over 4

=item B<new (%args)>

The constructor supports these arguments (all as key => value pairs).

=over 4

=item fh => $filehandle [MANDATORY]

The filehandle this L<AnyEvent::Handle> object will operate on.

NOTE: The filehandle will be set to non-blocking (using
AnyEvent::Util::fh_nonblocking).

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

Set the callback to be called when an end-of-file condition is detcted,
i.e. in the case of a socket, when the other side has closed the
connection cleanly.

While not mandatory, it is highly recommended to set an eof callback,
otherwise you might end up with a closed socket while you are still
waiting for data.

=item on_error => $cb->($handle, $fatal)

This is the error callback, which is called when, well, some error
occured, such as not being able to resolve the hostname, failure to
connect or a read error.

Some errors are fatal (which is indicated by C<$fatal> being true). On
fatal errors the handle object will be shut down and will not be
usable. Non-fatal errors can be retried by simply returning, but it is
recommended to simply ignore this parameter and instead abondon the handle
object when this callback is invoked.

On callback entrance, the value of C<$!> contains the operating system