NAME

Coro::Handle - non-blocking io with a blocking interface.

SYNOPSIS

 use Coro::Handle;

DESCRIPTION

This module implements io-handles in a coroutine-compatible way, that is, other coroutines can run while reads or writes block on the handle. It does NOT inherit from IO::Handle but uses tied objects.

$fh = new_from_fh Coro::Handle $fhandle [, arg => value...]

Create a new non-blocking io-handle using the given perl-filehandle. Returns undef if no fhandle is given. The only other supported argument is "timeout", which sets a timeout for each operation.

$fh = unblock $fh

This is a convinience function that just calls new_from_fh on the given filehandle. Use it to replace a normal perl filehandle by a non-blocking equivalent.

$fh->writable, $fh->readable

Wait until the filehandle is readable or writable (and return true) or until an error condition happens (and return false).

$fh->readline([$terminator])

Like the builtin of the same name, but allows you to specify the input record separator in a coroutine-safe manner (i.e. not using a global variable).

$fh->autoflush([...])

Always returns true, arguments are being ignored (exists for compatibility only). Might change in the future.

$fh->fileno, $fh->close, $fh->read, $fh->sysread, $fh->syswrite, $fh->print, $fh->printf

Work like their function equivalents (except read, which works like sysread. You should not use the read function with Coro::Handles, it will work but it's not efficient).

$fh->timeout([...])

The optional agrument sets the new timeout (in seconds) for this handle. Returns the current (new) value.

0 is a valid timeout, use undef to disable the timeout.

$fh->fh

Returns the "real" (non-blocking) filehandle. Use this if you want to do operations on the file handle you cannot do using the Coro::Handle interface.

$fh->rbuf

Returns the current contents of the read buffer (this is an lvalue, so you can change the read buffer if you like).

You can use this function to implement your own optimized reader when neither readline nor sysread are viable candidates, like this:

  # first get the _real_ non-blocking filehandle
  # and fetch a reference to the read buffer
  my $nb_fh = $fh->fh;
  my $buf = \$fh->rbuf;

  for(;;) {
     # now use buffer contents, modifying
     # if necessary to reflect the removed data

     last if $$buf ne ""; # we have leftover data

     # read another buffer full of data
     $fh->readable or die "end of file";
     sysread $nb_fh, $$buf, 8192;
  }

BUGS

 - Perl's IO-Handle model is THE bug.

AUTHOR

 Marc Lehmann <pcg@goof.com>
 http://www.goof.com/pcg/marc/