NAME

       Coro::Handle - non-blocking I/O with a blocking interface.

SYNOPSIS

        use Coro::Handle;

DESCRIPTION

       This module is an AnyEvent user, you need to make sure that you use and run a supported
       event loop.

       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 so by using AnyEvent to wait for readable/writable data, allowing other coroutines
       to run while one coroutine waits for I/O.

       Coro::Handle does NOT inherit from IO::Handle but uses tied objects.

       If at all possible, you should always prefer method calls on the handle object over
       invoking tied methods, i.e.:

          $fh->print ($str);         # NOT print $fh $str;
          my $line = $fh->readline;  # NOT my $line = <$fh>;

       The reason is that perl recurses within the interpreter when invoking tie magic, forcing
       the (temporary) allocation of a (big) stack. If you have lots of socket connections and
       they happen to wait in e.g. <$fh>, then they would all have a costly C coroutine
       associated with them.

       $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 filehandle is given. The only other supported argument is "timeout", which sets
           a timeout for each operation.

       $fh = unblock $fh
           This is a convenience function that just calls "new_from_fh" on the given filehandle.
           Use it to replace a normal perl filehandle by a non-(coroutine-)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])
           Similar to 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). Paragraph
           mode is not supported, use "\n\n" to achieve the same effect.

       $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::Handle's, it will work but it's not
           efficient).

       connect, listen, bind, getsockopt, setsockopt, send, recv, peername, sockname, shutdown,
       peerport, peerhost
           Do the same thing as the perl builtins or IO::Socket methods (but return true on
           EINPROGRESS). Remember that these must be method calls.

       peeraddr, peerhost, peerport
           Return the peer host (as numericla IP address) and peer port (as integer).

       ($fh, $peername) = $listen_fh->accept
           In scalar context, returns the newly accepted socket (or undef) and in list context
           return the ($fh, $peername) pair (or nothing).

       $fh->timeout ([...])
           The optional argument 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;

             while () {
                # 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/SUPPORT/CONTACT

          Marc A. Lehmann <schmorp@schmorp.de>
          http://software.schmorp.de/pkg/Coro.html