The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

GRID::Machine::Core - Module loaded when bootstraping the remote Perl server

DESCRIPTION

The creation of a GRID::Machine object through a call to GRID::Machine->new implies the loading of a Remote Module called GRID::Machine::Core which is delivered with the GRID::Machine distribution. Another module that is being included at construction time is GRID::Machine::RIOHandle.

One of the final goals of the GRID::Machine::Core remote module is to provide homonymous methods per each of the Perl CORE:: functions. At present time only a few are supported.

The following functions defined in the Remote Module GRID::Machine::Core are loaded via the include mechanism on the remote machine. Therefore, they work as methods of the GRID::Machine object on the local machine. They perform the same operations than their Perl aliases:

Function getcwd

Function chdir

Function umask

Function mkdir

Function system

Executes system on the remote machine. See an example:

  $ cat -n examples/transfer2.pl 
     1  #!/usr/local/bin/perl -w
     2  use strict;
     3  use GRID::Machine qw(is_operative);
     4  use Data::Dumper;
     5  
     6  my $host = shift || $ENV{GRID_REMOTE_MACHINE};
     7  
     8  my $machine = GRID::Machine->new( 
     9        host => $host,
    10        cleanup => 1,
    11        sendstdout => 1,
    12        startdir => '/tmp/perl5lib',
    13        prefix => '/tmp/perl5lib/',
    14     );
    15  
    16  my $dir = $machine->getcwd->result;
    17  print "$dir\n";
    18  
    19  $machine->modput('Parse::Eyapp::') or die "can't send module\n";
    20  
    21  print $machine->system('tree');
    22  my $r =  $machine->system('doesnotexist');
    23  print Dumper $r;

Observe the overloading of bool at line 19. modput returns a GRID::Machine::Result object which is evaluated in a Boolean context as a call to the result getter.

When executed produces an output like:

  $ perl -w examples/transfer2.pl 
  /tmp/perl5lib
  .
  `---- Parse
      `---- Eyapp
          |---- Base.pm
          |---- Cleaner.pm
          |---- Driver.pm
          |---- Grammar.pm
          |---- Lalr.pm
          |---- Node.pm
          |---- Options.pm
          |---- Output.pm
          |---- Parse.pm
          |---- Scope.pm
          |---- TokenGen.pm
          |---- Treeregexp.pm
          |---- _TreeregexpSupport.pm
          |---- Unify.pm
          `---- YATW.pm

  2 directories, 15 files
  $VAR1 = bless( {
                   'stderr' => 'Can\'t exec "doesnotexist":',
                   'errmsg' => '',
                   'type' => 'RETURNED',
                   'stdout' => '',
                   'errcode' => -1,
                   'results' => [ -1 ]
                 }, 'GRID::Machine::Result' );

Function qx

Similar to backtick quotes. The result depends on the context. In a list context returns a list with the lines of the output. In a scalar context reurns a string with the output. The value of $" on the local machine decides the register separator used. See an example:

  $ cat -n transfer3.pl
     1  #!/usr/local/bin/perl -w
     2  use strict;
     3  use GRID::Machine qw(is_operative);
     4  use Data::Dumper;
     5
     6  my $host = shift || 'casiano@remote.machine.es';
     7
     8  my $machine = GRID::Machine->new( host => $host );
     9  my $DOC = << "DOC";
    10  one. two. three.
    11  four. five. six.
    12  seven.
    13  DOC
    14
    15  # List context: returns  a list with the lines
    16  {
    17    local $/ = '.';
    18    my @a = $machine->qx("echo '$DOC'");
    19    local $"= ",";
    20    print "@a";
    21  }
    22
    23  # scalar context: returns a string with the output
    24  my $a = $machine->qx("echo '$DOC'");
    25  print $a;

When executed produces the following output:

  $ transfer3.pl
  one., two., three.,
  four., five., six.,
  seven.,

  one. two. three.
  four. five. six.
  seven.

Function glob

Function tar

Is equivalent to:

            system('tar', $options, ,'-f', $file)

Where $options is a string containing the options. Returns the error code from tar. Example:

  $m->tar($dist, '-xz')->ok or warn "$host: Can't extract files from $dist\n";

Function version

Syntax:

              $machine->version('Some::Module')

Returns the VERSION of the module if the given module is installed on the remote machine and has a VERSION number.

See an example of use:

  $ cat version.pl
  #!/usr/bin/perl -w
  use strict;
  use GRID::Machine;
  use Data::Dumper;

  my $host = $ENV{GRID_REMOTE_MACHINE} ||shift;

  my $machine = GRID::Machine->new(host => $host,);

  print Dumper($machine->version('Data::Dumper'));
  print Dumper($machine->version('Does::Not::Exist::Yet'));

When executed the program produces an output similar to this:

  $ version.pl
  $VAR1 = bless( {
                   'stderr' => '',
                   'errmsg' => '',
                   'type' => 'RETURNED',
                   'stdout' => '',
                   'errcode' => 0,
                   'results' => [ '2.121_08' ]
                 }, 'GRID::Machine::Result' );
  $VAR1 = bless( {
                   'stderr' => 'Can\'t locate Does/Not/Exist/Yet.pm in @INC \
                                (@INC contains: /etc/perl /usr/local/lib/perl/5.8.8 ...
                                BEGIN failed--compilation aborted.
                               ',
                   'errmsg' => '',
                   'type' => 'RETURNED',
                   'stdout' => '',
                   'errcode' => 0,
                   'results' => [ '' ]
                 }, 'GRID::Machine::Result' );

Function installed

Syntax:

              $machine->installed('Some::Module')

Returns TRUE if the given module is installed on the remote machine. Is equivalent to:

            system("$^X -M$module -e 0")

File Status Methods

Methods that are equivalent to the tests function

      -r -w -e -x -z -s -f -d  -t -T -B -M -A -C

are provided. Since hyphens aren't legal in Perl identifiers the hyphen has been substituted by an underscore. See an example:

  $ cat -n copyandmkdir.pl
     1  #!/usr/local/bin/perl -w
     2  use strict;
     3  use GRID::Machine;
     4
     5  my $host = 'remote.machine.es';
     6  my $dir = shift || "somedir";
     7  my $file = shift || $0; # By default copy this program
     8
     9  my $machine = GRID::Machine->new(
    10    host => $host,
    11    uses => [qw(Sys::Hostname)],
    12  );
    13
    14  my $r;
    15  $r = $machine->mkdir($dir, 0777) unless $machine->_w($dir);
    16  die "Can't make dir\n" unless $r->ok;
    17  $machine->chdir($dir)->ok or die "Can't change dir\n";
    18  $machine->put([$file]) or die "Can't copy file\n";
    19  print "HOST: ",$machine->eval(" hostname ")->result,"\n",
    20        "DIR: ",$machine->getcwd->result,"\n",
    21        "FILE: ",$machine->glob('*')->result,"\n";

When this program runs we get an output similar to this:

                    $ copyandmkdir.pl
                    HOST: orion
                    DIR: /home/casiano/somedir
                    FILE: copyandmkdir.pl

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.

I wish to thank Paul Evans for his IPC::PerlSSH module: it was the source of inspiration for this module. To Alex White, Dmitri Kargapolov, Eric Busto and Erik Welch for their contributions. To the Perl Monks, and the Perl Community for generously sharing their knowledge. Finally, thanks to Juana, Coro and my students at La Laguna.

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.