view release on metacpan or  search on metacpan

Scooby.pm  view on Meta::CPAN

package Devel::Scooby;

# Scooby.pm - a relocation mechanism for use with the Mobile::Location
#             and Mobile::Executive modules.
#
# Author: Paul Barry, paul.barry@itcarlow.ie
# Create: October 2002.
# Update: April/May 2003 - Version 4.x series.
#
# Notes:  This code takes advantage of the CPAN modules
#         PadWalker and Storable (with a little help from the
#         Data::Dumper module when it comes to Objects).  The Crypt::RSA
#         module provides PK+/PK- support.
#
#         Version 1.x supported relocating simple Perl code.
#         Version 2.x supported relocating SCALARs, ARRAYs, and
#             HASHes and references to same.
#         Version 3.x supported relocating Perl OO objects.  Note 
#             that this will only occur after Scooby has contacted
#             the receiving Location and determined that any 
#             required classes exist on the remote Perl system.
#         Version 4.x supports authenticated relocation using Crypt::RSA, 
#             as well as encryption of the mobile agent source code.
#             

our $VERSION = 4.12;

# The "constant.pm" module does not want to work with the debugger mechanism, 
# so "our" variables are used instead.  

our $SCOOBY_CONFIG_FILE   = "$ENV{'HOME'}/.scoobyrc";

our $SIGNATURE_DELIMITER  = "\n--end-sig--\n";

our $ALARM_WAIT           = 30;
our $LOCALHOST            = '127.0.0.1';

our $RESPONDER_PPORT      = '30001';
our $REGISTER_PPORT       = '30002';

our $MAX_RECV_LEN         = 65536;

our $TRUE                 = 1;
our $FALSE                = 0;

##########################################################################
# The Scooby Debugger starts here.
##########################################################################

{
    package DB;  # Remember: Scooby is a DEBUGGER.
        
    our ( $package, $file, $line );  # XXXXX: Note these are 'global'.

    sub DB {

        # Called for every line in the program that can be breakpointed.
        #
        # IN:  nothing.
        #
        # OUT: nothing.

        ( $package, $file, $line ) = caller;  # XXXXX: Writing to globals!
    }

    sub sub {

        # Called before every subroutine call in the program.
        #
        # IN:  nothing.  Although "$sub" is set to the name of the
        #      subroutine that was just called (thanks to Perl's debugging
        #      mechanisms).
        #
        # OUT: nothing.

        if ( $sub =~ /^Mobile::Executive::relocate$/ )
        {
            use Socket;                      # Functional interface to Socket API.
            use Storable qw( freeze thaw );  # Provides a persistence mechanism.
            use PadWalker qw( peek_my );     # Provides access to all lexically scoped variables.

            use Crypt::RSA;                  # Provides authentication and 
                                             # encryption services.

            my $remote = shift; 

            # Next two lines turn the IP name into a dotted-decimal.

            my $tmp = gethostbyname( $remote ) or inet_aton( $remote );
            $remote = inet_ntoa( $tmp );

            my $remote_port = shift;

            my $filename_mem = $file;
            my $linenum_mem = ( $line + 1 );

            my $stringified;
            
            # We first determine the list of lexicals in the caller.

            my $them = peek_my( 0 );  

            # Then we turn the list of lexicals into "Storable" output.

            my $str = freeze( \%{ $them } );

            # Then we turn the thawed output back into Perl code.  This 
            # code is referred to as the "lexical init" code.

            $stringified = _storable_decode( 
                                                $remote,
                                                $remote_port,
                                                thaw( $str ) 
                                           );

            # Determine the KEYSERVER address from the .scoobyrc file.

            open KEYFILE, "$SCOOBY_CONFIG_FILE"
                or die "Scooby: unable to access ~/.scoobyrc. Does it exist?\n";

            my $keyline = <KEYFILE>;

            close KEYFILE;

            # Note: format of 'rc' file is very strict.  No spaces!

            $keyline =~ /^KEYSERVER=(.+)/;

            my $key_server = $1;

            # Now that we know the address of the key server, we can 
            # request the PK+ of the key server and the next location.

            _get_store_pkplus( $key_server, $LOCALHOST, $RESPONDER_PPORT );
            _get_store_pkplus( $key_server, $remote, $remote_port );

            open RELOCATE_FILE, "$Mobile::Executive::absolute_fn" 
                or die "Scooby: Unable to open file for relocation: $!.\n";

            # Dump the current state of the agent to a temporary disk-file

Scooby.pm  view on Meta::CPAN

The B<-d> switch to C<perl> invokes Scooby as a debugger.  Unlike a traditional debugger that expects to interact with a human, Scooby runs automatically.  It NEVER interacts with a human, it interacts with the mobile agent machinery.

Scooby can be used to relocate Perl source code which contains the following:

=over 4

SCALARs (both numbers and strings).

An ARRAY of SCALARs (known as a simple ARRAY).

A HASH of SCALARs (known as a simple HASH).

References to SCALARs.

References to a simple ARRAY.

References to a simple HASH.

Objects.

References to objects are B<not> supported and are in no way guaranteed to behave the way you expect them to after relocation (even though they do relocate).

The relocation of more complex data structures is B<not> supported at this time (refer to the TO DO LIST section, below).

=back 

=head1 Internal methods/subroutines

=over 4

B<DB::DB> - called for every executable statement contained in the mobile agent source code file.

B<DB::sub> - called for every subroutine call contained in the mobile agent source code file.

B<_DB::storable_decode> - takes the stringified output from B<Storable>'s B<thaw> subroutine and turns it back into Perl code (with a little help from Data::Dumper for objects). 

B<DB::_check_modules_on_remote> - checks to see if a list of modules/classes "used" within the mobile agent actually exist on the remote Location's Perl system.

B<DB::_get_store_pkplus> - contacts the key server and requests a PK+, then stores the PK+ in a named disk-file.

B<DB::_wait_for_pkplus_confirm> - repeatedly contacts the key server until requested PK+ is returned (i.e., ACKed).

=back

=head1 ENVIRONMENT

This module must be installed in your Perl system's B<Devel/> directory.  This module will only work on an operating system that supports the Perl modules listed in the SEE ALSO section, below.  (To date, I've only tested it on various Linux distribu...

=head1 TO DO LIST

Loads.  The biggest item on the list would be to enhance Scooby to allow it to handle more complex data structures, such as ARRAYs of HASHes and HASHes of ARRAYs, etc., etc.

My initial plan was to allow for the automatic relocation of open disk-files.  However, on reflection, I decided not to do this at this time, but may return to the idea at some stage in the future.

The current implementation checks to see if "used" classes are available on the next Location before attempting relocation, but does not check to see if "used" modules are available.  It would be nice if it did.

It would also be nice to incorporate an updated B<Class::Tom> (by James Duncan) to handle the relocation of objects to a Location without the need to have the module exist on the remote Location.  On my system (Linux), the most recent B<Class::Tom> g...

=head1 SEE ALSO

The B<Mobile::Executive> module and the B<Mobile::Location> class.  Internally, this module uses the following CPAN modules: B<PadWalker> and B<Storable>, in addition to the standard B<Data::Dumper> module.  The B<Crypt::RSA> modules provides encrypt...

The Scooby Website: B<http://glasnost.itcarlow.ie/~scooby/>.

=head1 AUTHOR

Paul Barry, Institute of Technology, Carlow in Ireland, B<paul.barry@itcarlow.ie>, B<http://glasnost.itcarlow.ie/~barryp/>.

=head1 COPYRIGHT

Copyright (c) 2003, Paul Barry.  All Rights Reserved.

This module is free software.  It may be used, redistributed and/or modified under the same terms as Perl itself.