=head1 NAME

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

=head1 DESCRIPTION


=head2 The Structure of the Remote Server

As with most servers, the server side of the C<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" );
  }

=head2 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 L<EXTENDING THE PROTOCOL>). The following 
operations are currently supported:

=over 2

=item * C<GRID::Machine::EVAL>

Used by the local method C<eval>

=item * C<GRID::Machine::STORE>

Used by the local methods C<compile> and C<sub> to install code on the remote side.

=item * C<GRID::Machine::EXISTS>

Used by the local method C<exists>

=item * C<GRID::Machine::CALL>

Used by the local method C<call>

=item * C<GRID::Machine::MODPUT>

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


=item * C<GRID::Machine::OPEN>

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

=item * C<GRID::Machine::QUIT>

Usually is automatically called when the C<GRID::Machine> object
goes out of scope 

=item * C<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 L<Functions gprint and gprintf>)


=item * C<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 L<Functions gprint and gprintf>)

=item * C<GRID::Machine::CALLBACK>

Used to implement callbacks

=back 

=head2 The C<SERVER> function

The C<SERVER> function is available on the remote machine. Returns
the object representing the remote side of the C<GRID::Machine> object.
This way code on the remote side can gain access to the C<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 C<stored_procedures> method returns a reference to the hash containing
the subroutines installed via the C<sub> and C<compile> methods. The keys are
the names of the subroutines, the values are the C<CODE> references implementing
them.  When executed the former program produces the list of installed subroutines:

                    $ accessobject.pl
                    tar
                    system
                    installed
                    getcwd
                    etc.

=head2 The C<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.

=head2 The C<send_error> Method 

Syntax:

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

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

=head2 The C<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
C<send_result> to send  results to the client

=head1 EXTENDING THE PROTOCOL

Let us see a simple example. We will extend the
protocol with a new tag C<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 C<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!

=head1 INMEDIATE PRINTING

=head2 Functions C<gprint> and C<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 C<gprint> and C<gprintf> 
if what you want is inmediate output (for debugging purposes, for instance).
They work as C<print> and C<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 C<'Inside rmap!'> generated at line 15 using C<print> is the last 
(actually is sent to C<STDOUT> in line 38).
The messages generated using C<gprint> and C<gprintf> (lines 20, 26 and 29)
were inmediately sent to C<STDOUT>.

=head1 REMOTE DEBUGGING 

To run the remote side under the control of the perl debugger use the C<debug>
option of C<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 C<netcat> to listen (option C<-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 C<GRID::Machine> code and - until you gain some familiarity 
with C<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.




=head1 SEE ALSO

=over 2

=item * L<GRID::Machine>

=item * L<GRID::Machine::IOHandle>

=item * L<GRID::Machine::perlparintro>

=item * L<http://nereida.deioc.ull.es/~pp2/GRID_Machine/Machine.dvi>

=item * L<http://nereida.deioc.ull.es/~pp2/GRID_Machine/perlparintro.dvi>

=item * L<http://nereida.deioc.ull.es/~pp2/GRID_Machine/remotedebugtut.dvi>

=item * L<IPC::PerlSSH>

=item * Man pages of C<ssh>, C<ssh-key-gen>, C<ssh_config>, C<scp>, 
C<ssh-agent>, C<ssh-add>, C<sshd>

=item * L<http://www.openssh.com>

=back



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

I wish to thank Paul Evans for his C<IPC::PerlSSH> module: it was the source
of inspiration for this module. To Dmitri Kargapolov, Eric Busto and
Alex White 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.

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