/ 
AnyEvent-3.3
/ AnyEvent::Handle

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>