Daniel Ruoso > IO-BindHandles-0.006 > IO::BindHandles

Download:
IO-BindHandles-0.006.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Source  

NAME ^

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

VERSION ^

version 0.006

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:

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.

syntax highlighting: