=head1 NAME

GRID::Machine::IOHandle - Supply object methods for Remote I/O handles

=head1 SYNOPSIS

  use GRID::Machine;

  my $machine = shift || 'remote.machine';
  my $m = GRID::Machine->new( host => $machine );

  my $f = $m->open('> tutu.txt'); # Creates a GRID::Machine::IOHandle object
  $f->print("Hola Mundo!\n");
  $f->print("Hello World!\n");
  $f->printf("%s %d %4d\n","Bona Sera Signorina", 44, 77);
  $f->close();

  $f = $m->open('tutu.txt');
  my $x = <$f>;
  print "\n******diamond scalar********\n$x\n";
  $f->close();

  $f = $m->open('tutu.txt');
  my $old = $m->input_record_separator(undef);
  $x = <$f>;
  print "\n******diamond scalar context and \$/ = undef********\n$x\n";
  $f->close();
  $old = $m->input_record_separator($old);

=head1 DESCRIPTION

C<GRID::Machine::IOHandle> object very much resembles C<IO::Handle> objects. The difference
being that the object refers to a remote C<IO::Handle> object. They can be used 
not only for remote files but for remote pipes.

=head1 METHODS

See L<perlfunc> for complete descriptions of each of the following
supported C<GRID::Machine::IOHandle> methods, which are just front ends for the
corresponding built-in functions:

    $io->close
    $io->getc
    $io->print ( ARGS )
    $io->printf ( FMT, [ARGS] )
    $io->stat

See L<perlvar> for complete descriptions of each of the following
supported C<GRID::Machine::IOHandle> methods.  All of them return the previous
value of the attribute and takes an optional single argument that when
given will set the value.  If no argument is given the previous value
is unchanged (except for $io->autoflush will actually turn ON
autoflush by default).

    $io->autoflush ( [BOOL] )                         $|

The following methods are not supported on a per-filehandle basis.

    GRID::Machine::IOHandle->format_line_break_characters( [STR] ) $:
    GRID::Machine::IOHandle->format_formfeed( [STR])               $^L
    GRID::Machine::IOHandle->output_field_separator( [STR] )       $,
    GRID::Machine::IOHandle->output_record_separator( [STR] )      $\

    GRID::Machine::IOHandle->input_record_separator( [STR] )       $/

Follows an example that uses methods C<open>, C<close>, C<print>, C<printf> and C<getc>:

  $ cat getc.pl
  #!/usr/local/bin/perl -w
  use strict;
  use GRID::Machine;

  my $machine = shift || 'remote.machine';
  my $m = GRID::Machine->new( host => $machine );

  my $f = $m->open('> tutu.txt');
  $f->print("Hola Mundo!\n");
  $f->print("Hello World!\n");
  $f->printf("%s %d %4d\n","Bona Sera Signorina", 44, 77);
  $f->close();

  $f = $m->open('tutu.txt');
  my $x;
  {
    $x = $f->getc();
    last unless defined($x);
    print $x;
    redo;
  }
  $f->close();

Furthermore, for doing normal I/O you might need these:


=over 4

=item $io->getline

This works like <$io> on the remote machine,
described in L<perlop/"I/O Operators">
except that it's more readable and can be safely called in a
list context but still returns just one line.  

=item $io->getlines

This works like <$io> when called in a list context to read all
the remaining lines in a file, except that it's more readable.
It will also croak() if accidentally called in a scalar context.

=item The diamond operatos

You can read from a remote file
using <$io>, but it only works on scalar context. See the L<SYNOPSIS>
example.


=item $io->flush

C<flush> causes perl to flush any buffered data at the perlio api level.
Any unread data in the buffer will be discarded, and any unwritten data
will be written to the underlying file descriptor. Returns "0 but true"
on success, C<undef> on error.

=item $io->blocking ( [ BOOL ] )

If called with an argument C<blocking> will turn on non-blocking IO if
C<BOOL> is false, and turn it off if C<BOOL> is true.

C<blocking> will return the value of the previous setting, or the
current setting if C<BOOL> is not given. 

If an error occurs C<blocking> will return undef and C<$!> will be set.

=back

=head1 REMOTE PIPES

=head2 Opening pipes for input

The C<open> method of C<GRID::Machine> objects can be used to pipe programs as in the following
example:

  pp2@nereida:~/LGRID_Machine/examples$ cat -n pipes1.pl
     1  #!/usr/local/bin/perl -w
     2  use strict;
     3  use GRID::Machine;
     4
     5  my $machine = shift || 'remote.machine.domain';
     6  my $m = GRID::Machine->new( host => $machine );
     7
     8  my $f = $m->open('uname -a |');
     9  my $x = <$f>;
    10  print "UNAME result: $x\n"

In a scalar context C<open> returns the handler.
In list context returns the pair C<(handler, PID)>.
See L<GRID::Machine::perlparintro> for a more detailed example.

When executed the program produces an output similar to this:

  pp2@nereida:~/LGRID_Machine/examples$ pipes1.pl
  UNAME result: Linux remote 2.6.8-2-686 #1 Tue Aug 16 13:22:48 UTC 2005 i686 GNU/Linux

=head2 Opening pipes for output

Pipes can be also for input as the following example shows:

  pp2@nereida:~/LGRID_Machine/examples$ cat -n pipes.pl
   1  #!/usr/local/bin/perl -w
   2  use strict;
   3  use GRID::Machine;
   4
   5  my $machine = shift || 'remote.machine';
   6  my $m = GRID::Machine->new( host => $machine );
   7
   8  my $i;
   9  my $f = $m->open('| sort -n > /tmp/sorted.txt');
  10  for($i=10; $i>=0;$i--) {
  11    $f->print("$i\n")
  12  }
  13  $f->close();
  14
  15  my $g = $m->open('/tmp/sorted.txt');
  16  print while <$g>;

when executed, the program produces the following output:

  pp2@nereida:~/LGRID_Machine/examples$ pipes.pl
  0
  1
  2
  3
  4
  5
  6
  7
  8
  9
10

When opening a pipe for output like in line 9 in the 
former example 

  my $f = $m->open('| sort -n > /tmp/sorted.txt')

be sure to redirect the C<STDOUT> of the program. 
Otherwise, C<GRID::Machine> will redirect it to the
C<null> device and the output will be lost.

=head2 Bidirectional pipes: C<open2> 

Synopsis:


  my $WTR = IO::Handle->new();
  my $RDR = IO::Handle->new();
  my $pid = $m->open2($fromchild, $tochild, 'command and args');

The C<open2> method runs the given command in machine C<$m>
and connects C<$fromchild> for
reading from C<command> and C<$tochild> 
for writing from C<command>.
Returns the PID of the process executing C<command>.

=head2 Bidirectional pipes: C<open3>

Synopsis:

  my $pid = $m->open3($tochild, $fromchild, $errfromchild, 'command and args');

Spawns the given command and connects C<$fromchild> for reading from the child,
C<$tochild> for writing to the child, and C<$errfromchild> for errors.  

See an example that opens the Unix calculator C<bc> in a remote machine:

  $ cat -n open3bc.pl
     1  #!/usr/bin/perl -w
     2  use strict;
     3  use GRID::Machine;
     4
     5  my $machine = shift || 'orion.pcg.ull.es';
     6  my $m = GRID::Machine->new( host => $machine );
     7
     8  my $WTR = IO::Handle->new();
     9  my $RDR = IO::Handle->new();
    10  my $ERR = IO::Handle->new();
    11  my $pid = $m->open3($WTR, $RDR, $ERR, 'bc');
    12
    13  my $line;
    14
    15  print $WTR "3*2\n";
    16  $line = <$RDR>;
    17  print STDOUT "3*2 = $line";
    18
    19  print $WTR "3/(2-2)\n";
    20  $line = <$ERR>;
    21  print STDOUT "3/(2-2) produces error = $line\n";
    22
    23  print $WTR "quit\n";
    24  wait;

When executed, the former program produces an output like this:

  $ open3bc.pl
  3*2 = 6
  3/(2-2) produces error = Runtime error (func=(main), adr=11): Divide by zero




=head1 SEE ALSO

L<perlfunc>, 
L<perlop/"I/O Operators">,
L<IO::File>

=head1 AUTHOR

Casiano Rodriguez Leon E<lt>casiano@ull.esE<gt>

=head1 ACKNOWLEDGMENTS

This work has been supported by CEE (FEDER) and the Spanish Ministry of
I<Educacion y Ciencia> through I<Plan Nacional I+D+I> number TIN2005-08818-C04-04
(ULL::OPLINK project L<http://www.oplink.ull.es/>).
Support from Gobierno de Canarias was through GC02210601
(I<Grupos Consolidados>).
The University of La Laguna has also supported my work in many ways
and for many years.

Thanks also to Juana, Coro, my students at La Laguna and to the Perl Community.

=head1 LICENCE AND COPYRIGHT

Copyright (c) 2007 Casiano Rodriguez-Leon (casiano@ull.es). All rights reserved.

These modules are free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

=cut

