GRID::Machine::REMOTE(3p)

NAME
GRID::Machine::REMOTE - The server that runs on the other side of the SSH link

DESCRIPTION

  The Structure of the Remote Server
As with most servers, the server side of the "GRID::Machine" object consists of an infinite loop waiting for requests:

  while( 1 ) {
     my ( $operation, @args ) = $server->read_operation();

     if ($server->can($operation)) {
       $server->$operation(@args);
       next;
     }

     $server->send_error( "Unknown operation $operation\nARGS: @args\n" );
  }

  The Protocol
The protocol simply consists of the name of the method to execute and the arguments for such method. The programmer - using inheritance - can extend the protocol with new methods (see the section "EXTENDING THE PROTOCOL"). The following operations are currently supported:

•   "GRID::Machine::EVAL"

    Used by the local method "eval"

•   "GRID::Machine::STORE"

    Used by the local methods "compile" and "sub" to install code on the remote side.

•   "GRID::Machine::EXISTS"

    Used by the local method "exists"

•   "GRID::Machine::CALL"

    Used by the local method "call"

•   "GRID::Machine::MODPUT"

    Used by the "modput" method. A list of pairs ("Module::Name, code for Module::Name") is sent to the remote machine. For each pair, the remote side writes to disk a file "Module/Name.pm" with the contents of the string "code for Module::Name". The file is stored in the directory referenced by the "prefix" attribute of the "GRID::Machine" object.

•   "GRID::Machine::OPEN"

    Used by the "open" method. As arguments receives a string defining the way the file will be accessed.

•   "GRID::Machine::QUIT"

    Usually is automatically called when the "GRID::Machine" object goes out of scope

•   "GRID::Machine::GPRINT"

    Most requests go from the local machine to the remote Perl server. However, this and the next go in the other direction. This request is generated in the remote machine and served by the local machine. It is used when inmediate printing is required (see section "Functions gprint and gprintf")

•   "GRID::Machine::GPRINTF"

    This request is generated in the remote machine and served by the local machine. It is used when inmediate printing is required (see section "Functions gprint and gprintf")

•   "GRID::Machine::CALLBACK"

    Used to implement callbacks

  The "SERVER" function
The "SERVER" function is available on the remote machine. Returns the object representing the remote side of the "GRID::Machine" object. This way code on the remote side can gain access to the "GRID::Machine" object. See an example:

    my $m = GRID::Machine->new( host => 'beowulf');

    $m->sub(installed => q { return  keys %{SERVER->stored_procedures}; });
    my @functions = $m->installed()->Results;
    local $" = "\n";
    print "@functions\n";

The "stored_procedures" method returns a reference to the hash containing the subroutines installed via the "sub" and "compile" methods. The keys are the names of the subroutines, the values are the "CODE" references implementing them. When executed the former program produces the list of installed subroutines:

                    $ accessobject.pl
                    tar
                    system
                    installed
                    getcwd
                    etc.

  The "read_operation" Method
Syntax:

     my ( $operation, @args ) = $server->read_operation( );

Reads from the link. Returns the type of operation/tag and the results of the operation.

  The "send_error" Method
Syntax:

     $server->send_error( "Error message" );

Inside code to be executed on the remote machine we can use the function "send_error" to send error messages to the client

  The "send_result" Method
Syntax:

    $server->send_result(
        stdout  => $stdout,
        stderr  => $stderr,
        errmsg  => $errmsg,
        results => [ @results ],
    );

Inside code to be executed on the remote machine we can use the function "send_result" to send results to the client

EXTENDING THE PROTOCOL
Let us see a simple example. We will extend the protocol with a new tag "MYTAG". We have to write a module that will be used in the remote side of the link:

  $ cat -n MyRemote.pm
     1  package GRID::Machine;
     2  use strict;
     3
     4  sub MYTAG {
     5    my ($server, $name) = @_;
     6
     7    $server->send_operation("RETURNED", "Hello $name!\n") if defined($name);
     8    $server->send_operation("DIED", "Error: Provide a name to greet!\n");
     9  }
    10
    11  1;

This component will be loaded on the remote machine via the ssh link. The name of the handling method "MYTAG" must be the same than the name of the tag (operation type) used to send the request. Here is a client program using the new tag:

  $ cat -n extendprotocol.pl
     1  #!/usr/local/bin/perl -w
     2  use strict;
     3  use GRID::Machine;
     4
     5  my $name = shift;
     6  my $host = 'user@remote.machine';
     7
     8  my $machine = GRID::Machine->new(host => $host, remotelibs => [ qw(MyRemote) ]);
     9
    10  $machine->send_operation( "MYTAG", $name);
    11  my ($type, $result) = $machine->read_operation();
    12
    13  die $result unless $type eq 'RETURNED';
    14  print $result;

When the program is executed we get the following output:

                          $ extendprotocol.pl Larry
                          Hello Larry!
                          $ extendprotocol.pl
                          Error: Provide a name to greet!

INMEDIATE PRINTING

  Functions "gprint" and "gprintf"
When running a RPC the output generated during the execution of the remote subroutine isn't available until the return of the RPC. Use "gprint" and "gprintf" if what you want is inmediate output (for debugging purposes, for instance). They work as "print" and "printf" respectively.

See an example:

  $ cat -n gprint.pl
     1  #!/usr/local/bin/perl -w
     2  use strict;
     3  use GRID::Machine;
     4
     5  my $host = $ENV{GRID_REMOTE_MACHINE};
     6
     7  my $machine = GRID::Machine->new(host => $host, uses => [ 'Sys::Hostname' ]);
     8
     9  my $r = $machine->sub(
    10    rmap => q{
    11      my $f = shift; # function to apply
    12      die "Code reference expected\n" unless UNIVERSAL::isa($f, 'CODE');
    13
    14
    15      print "Inside rmap!\n"; # last message
    16      my @result;
    17      for (@_) {
    18        die "Array reference expected\n" unless UNIVERSAL::isa($_, 'ARRAY');
    19
    20        gprint hostname(),": Processing @$_\n";
    21
    22
    23        push @result, [ map { $f->($_) } @$_ ];
    24      }
    25
    26      gprintf "%12s:\n",hostname();
    27      for (@result) {
    28        my $format = "%5d"x(@$_)."\n";
    29        gprintf $format, @$_
    30      }
    31      return @result;
    32    },
    33  );
    34  die $r->errmsg unless $r->ok;
    35
    36  my $cube = sub { $_[0]**3 };
    37  $r = $machine->rmap($cube, [1..3], [4..6], [7..9]);
    38  print $r;

When executed the program produces the following output:

          $ gprint.pl
          orion: Processing 1 2 3
          orion: Processing 4 5 6
          orion: Processing 7 8 9
                 orion:
              1    8   27
             64  125  216
            343  512  729
          Inside rmap!

Observe how the message 'Inside rmap!' generated at line 15 using "print" is the last (actually is sent to "STDOUT" in line 38). The messages generated using "gprint" and "gprintf" (lines 20, 26 and 29) were inmediately sent to "STDOUT".

REMOTE DEBUGGING
To run the remote side under the control of the perl debugger use the "debug" option of "new". The associated value must be a port number higher than 1024:

     my $machine = GRID::Machine->new(
        host => $host,
        debug => $port,
        includes => [ qw{SomeFunc} ],
     );

Before running the example open a SSH session to the remote machine in a different terminal and execute "netcat" to listen (option "-l") in the chosen port:

  pp2@nereida:~/LGRID_Machine$ ssh beowulf 'netcat -v -l -p 12345'
  listening on [any] 12345 ...

Now run the program in the first terminal:

  pp2@nereida:~/LGRID_Machine/examples$ debug1.pl beowulf:12345
  Debugging with 'ssh beowulf PERLDB_OPTS="RemotePort=beowulf:12345" perl -d'
  Remember to run 'netcat -v -l -p 12345' in beowulf

The program looks blocked. If you go to the other terminal you will find the familiar perl debugger prompt:

  casiano@beowulf:~$ netcat -v -l -p 12345
  listening on [any] 12345 ...
  connect to [193.145.102.240] from beowulf.pcg.ull.es [193.145.102.240] 38979

  Loading DB routines from perl5db.pl version 1.28
  Editor support available.

  Enter h or `h h' for help, or `man perldebug' for more help.

  GRID::Machine::MakeAccessors::(/home/pp2/LGRID_Machine/lib/GRID/Machine/MakeAccessors.pm:33):
  33:     1;
  auto(-1)  DB<1> c GRID::Machine::main
  GRID::Machine::main(/home/pp2/LGRID_Machine/lib/GRID/Machine/REMOTE.pm:490):
  490:      my $server = shift;
    DB<2>

From now on you can execute almost any debugger command. Unfortunately you are now inside "GRID::Machine" code and - until you gain some familiarity with "GRID::Machine" code - it is a bit difficult to find where your code is and where to put your breakpoints. Future work: write a proper debugger front end.

SEE ALSO

•   GRID::Machine

•   GRID::Machine::IOHandle

•   GRID::Machine::Group

•   GRID::Machine::Process

•   GRID::Machine::perlparintro

•   Net::OpenSSH

•   IPC::PerlSSH

•   IPC::PerlSSH::Async

•   Man pages of "ssh", "ssh-key-gen", "ssh_config", "scp", "ssh-agent", "ssh-add", "sshd"

•   <http://www.openssh.com>

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.