The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
GRID-Machine-0.127
River stage one • 1 direct dependent • 1 total dependent
5 ++
/ GRID::Machine::IOHandle

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.