NAME
    IO::BindHandles - Bind a set of handles for buffered tunneling

VERSION
    version 0.005

SYNOPSIS
    Simple usage:

      use IO::BindHandles;
      # connect $r1 to $w1 and $r2 to $w2
      my $bh = IO::BindHandles->new(
        handles => [
          $r1, $w1, # read from $r1, write to $w1
          $r2, $w2, # read from $r2, write to $r2
        ]
      );
  
      # block until the handles close themselves
      $bh->loop;

    More complex scenario with non-blocking calls

      # connect STDIN and STDOUT to a socket in non-blocking way
      $socket->blocking(0);
      STDIN->blocking(0);
      STDOUT->blocking(0);
      my $bh = IO::BindHandles->new(
        timeout => 0, # non-blocking
        handles => [
          *STDIN, $socket,  # read from STDIN, write to socket
          $socket, *STDOUT, # read from socket, write to STDOUT
        ]
      );
  
      # do it in an explicit unblocking loop
      while (1) {
        $bh->rwcycle;
        # do something else that takes some time
        my $cond = do_something_else();
        # you can check if the bind is still valid
        last if $cond && $bh->bound;
      }

DESCRIPTION
    This module implements a buffered tunneling between a set of arbitrary
    IO handles. It basically implements a select loop on a set of handles,
    reading and writing from them using an internal buffer.

    This replicates what a dup or fdopen call would do when you can't
    actually do it, i.e.: attach STDIN/STDOUT to a socket or attach two
    different sockets toguether.

    This module doesn't perform any low-level operation on the handles, so
    it should support any IO::Handle that is supported by IO::Select.

METHODS
  new(timeout => $val, handles => [ $h1, $h2 ])
    Initializes a new BindHandles instance. The timeout value defaults to
    0.5. The handles argument receives an arrayref with pairs of handles.
    Each pair represents a binding between a read and a write handle.

    You can pass as many handle pairs as you want, and you can even use the
    same handle for a read and a write role. But you should not use the same
    handle for more then one read or one write operation.

    Future versions of this module might support "read one write many",
    "read many write one" or even "read many write many". Contact me if you
    think this features are important and I might even implement it.

    This method will call autoflush(1) on all handles.

  loop()
    Blocking loop to consume all read handles and write the data to their
    bound handles until they are no longer bound, i.e.: when the remote
    socket is closed.

    In order to avoid consuming all the CPU, this method will override the
    timeout configuration to 0.1 if it is set to 0.

  bound()
    Checks if there are still bound handles. It will return false when no
    more write handles are open or when read handles close without any write
    buffer left. This can be used as a "while" condition.

    It returns the number of valid bindings.

  rwcycle()
    Selects handles ready to read, write or with exceptions and act
    accordingly. The select might block according to the configured timeout
    value.

    This method will close handles in the following situations:

    *   When a read operation returns undef or 0 it will close the read
        handle. It will also close the write handle if there are no contents
        in the related write buffer.

    *   When a write operation returns undef or 0 it will close both the
        read and write handle.

    *   When an exception is detected in one handle, it will close it. It
        will also close the bound handle unless the exception hapenned in
        the read handle and there are contents in the write buffer.

  timeout
    Accessor for the timeout value.

BUGS
    Please submit all bugs regarding IO::BindHandles to
    bug-io-bindhandles@rt.cpan.org

AUTHOR
    Daniel Ruoso <daniel@ruoso.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Daniel Ruoso.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.