GRID::Machine::IOHandle(3p)

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

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);

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

METHODS
See perlfunc for complete descriptions of each of the following supported "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 perlvar for complete descriptions of each of the following supported "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 "open", "close", "print", "printf" and "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:

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

$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.

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

$io->flush
    "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, "undef" on error.

$io->blocking ( [ BOOL ] )
    If called with an argument "blocking" will turn on non-blocking IO if "BOOL" is false, and turn it off if "BOOL" is true.

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

    If an error occurs "blocking" will return undef and $! will be set.

REMOTE PIPES

  Opening pipes for input
The "open" method of "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 "open" returns the handler. In list context returns the pair "(handler, PID)". See 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

  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 "STDOUT" of the program. Otherwise, "GRID::Machine" will redirect it to the "null" device and the output will be lost.

  Bidirectional pipes: "open2"
Synopsis:

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

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

  Bidirectional pipes: "open3"
Synopsis:

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

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

See an example that opens the Unix calculator "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

SEE ALSO
perlfunc, "I/O Operators" in perlop, IO::File

AUTHOR
Casiano Rodriguez Leon <casiano@ull.es>

ACKNOWLEDGMENTS
This work has been supported by CEE (FEDER) and the Spanish Ministry of Educacion y Ciencia through Plan Nacional I+D+I number TIN2005-08818-C04-04 (ULL::OPLINK project <http://www.oplink.ull.es/>). Support from Gobierno de Canarias was through GC02210601 (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.

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 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.