NAME

AnyEvent::Handle - non-blocking I/O on filehandles via AnyEvent

VERSION

Version 0.01

SYNOPSIS

   use AnyEvent;
   use AnyEvent::Handle;

   my $cv = AnyEvent->condvar;

   my $ae_fh = AnyEvent::Handle->new (fh => \*STDIN);

   $ae_fh->on_eof (sub { $cv->broadcast });

   $ae_fh->readlines (sub {
      my ($ae_fh, @lines) = @_;
      for (@lines) {
         chomp;
         print "Line: $_";
      }
   });

   # or use the constructor to pass the callback:

   my $ae_fh2 =
      AnyEvent::Handle->new (
         fh => \*STDIN,
         on_eof => sub {
            $cv->broadcast;
         },
         on_readline => sub {
            my ($ae_fh, @lines) = @_;
            for (@lines) {
               chomp;
               print "Line: $_";
            }
         }
      );

   $cv->wait;

DESCRIPTION

This module is a helper module to make it easier to do non-blocking I/O on filehandles (and sockets, see AnyEvent::Socket).

The event loop is provided by AnyEvent.

METHODS

new (%args)

The constructor has these arguments:

fh => $filehandle

The filehandle this AnyEvent::Handle object will operate on.

NOTE: The filehandle will be set to non-blocking.

read_block_size => $size

The default read block size use for reads via the on_read method.

on_read => $cb

on_eof => $cb

on_error => $cb

These are shortcuts, that will call the corresponding method and set the callback to $cb.

on_readline => $cb

The readlines method is called with the default seperator and $cb as callback for you.

fh

This method returns the filehandle of the AnyEvent::Handle object.

on_read ($callback)

This method installs a $callback that will be called when new data arrived. You can access the read buffer via the rbuf method (see below).

The first argument of the $callback will be the AnyEvent::Handle object.

on_error ($callback)

Whenever a read or write operation resulted in an error the $callback will be called.

The first argument of $callback will be the AnyEvent::Handle object itself. The error is given as errno in $!.

on_eof ($callback)

Installs the $callback that will be called when the end of file is encountered in a read operation this $callback will be called. The first argument will be the AnyEvent::Handle object itself.

rbuf

Returns a reference to the read buffer.

NOTE: The read buffer should only be used or modified if the on_read method is used directly. The read and readlines methods will provide the read data to their callbacks.

read ($len, $callback)

Will read exactly $len bytes from the filehandle and call the $callback if done so. The first argument to the $callback will be the AnyEvent::Handle object itself and the second argument the read data.

NOTE: This method will override any callbacks installed via the on_read method.

readlines ($callback)

readlines ($sep, $callback)

This method will read lines from the filehandle, seperated by $sep or "\n" if $sep is not provided. $sep will be used as "line" seperator.

The $callback will be called when at least one line could be read. The first argument to the $callback will be the AnyEvent::Handle object itself and the rest of the arguments will be the read lines.

NOTE: This method will override any callbacks installed via the on_read method.

write ($data)

write ($callback)

write ($data, $callback)

This method will write $data to the filehandle and call the $callback afterwards. If only $callback is provided it will be called when the write buffer becomes empty the next time (or immediately if it already is empty).

AUTHOR

Robin Redeker, <elmex at ta-sa.org>