=head1 NAME

GRID::Machine::Result - The object describing the result of a GRID::Machine RPC

=head1 DESCRIPTION


The class C<GRID::Machine::Result> is used by both the local and remote
sides of the C<GRID::Machine>, though most of its methods are called 
on the remote side. 

The result of a RPC is a C<GRID::Machine::Result> object. 
Such object has the following attributes:

=over 2

=item * I<type>

The C<type> of result returned. A string. Fixed by the protocol.
Common values are C<RETURNED> and C<DIED>.

=item * I<stdout>

A string containing the contents of C<STDOUT>
produced during the duration of the RPC

=item * I<stderr>

A string containing the contents of C<STDERR>
produced during the duration of the RPC

=item * I<results>

A reference to an C<ARRAY> containing the results returned by the RPC

=item * I<errcode>

The contents of C<$?> as produced during the RPC

=item * I<errmsg>

The contents of C<$@> as produced during the RPC

=back

=head2 The Constructor C<new>

Syntax:

  GRID::Machine::Result->new(
    stdout => $rstdout, 
    errmsg  => $err, 
    stderr => $rstderr, 
    results => \@results
  )

Builds a new result object.  

=head2 The C<ok> Method

Returns C<TRUE> if the RPC didn't died, i.e. if the C<type> attribute is not
the string C<'DIED'>

=head2 The C<noerr> Method

Returns C<TRUE> if the RPC didn't died and didn't send any messages 
through stderr.
See an example. When running the following program:

  $ cat noerrvsok.pl
  #!/usr/local/bin/perl -w
  use strict;
  use GRID::Machine;

  my $machine = shift || $ENV{GRID_REMOTE_MACHINE};
  my $m = GRID::Machine->new( host => $machine );

  my $r = $m->eval( q{print STDERR "This is the end\n" });

  print "print to STDERR:\n";
  print "<".$r->ok.">\n";
  print "<".$r->noerr.">\n";

  $r = $m->eval( q{warn "This is a warning\n" });

  print "Warn:\n";
  print "<".$r->ok.">\n";
  print "<".$r->noerr.">\n";

we get the following output:



                $ errvsok.pl
                print to STDERR:
                <1>
                <>
                Warn:
                <1>
                <>

=head2 The C<result> Method

Returns the first element of the list referenced by the C<results> attribute

=head2 The C<Results> Method

Returns the list referenced by the C<results> attribute

=head2 The C<str> Method. Stringification of a C<Result> object

Returns the string made of concatenating C<stdout>, C<stderr> and C<errmsg>.
The Perl operator C<q("")> is overloaded using this method. Thus,
wherever a C<GRID::Machine::Result> object is used on a scalar string 
context the C<str> will be called.




=head1 SEE ALSO

=over 2

=item * L<GRID::Machine>

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

=item * L<http://nereida.deioc.ull.es/~pp2/GRID_Machine/Machine.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<Educación 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 for his contributions.
Thanks also to Juana, Coro, my students at La Laguna and to the Perl Community. 

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




