NAME

Distributed::Process - a framework for running a process simultaneously on several machines.

VERSION

Version 0.20

SYNOPSIS

First, write a subclass of Distributed::Process::Worker that will implement the tasks to be run remotely in its run() method.

    package MyWorker;
    use Distributed::Process;
    use Distributed::Process::Worker;

    sub run {
        my $self = shift;

        # do interesting stuff
        ...

        # report about what happened
        $self->result("logs the results");
    }

Write a small server to pilot the workers:

    # Server
    use Distributed::Process;
    use Distributed::Process::Server;
    use Distributed::Process::Master;
    use MyWorker;

    $master = new Distributed::Process::Master 
        -in_handle => \*STDIN, -out_handle => \*STDOUT,
        -worker_class => 'MyWorker',
        -n_workers => 2;
    $server = new Distributed::Process::Server -port => 8147, -master => $master;

    $server->listen();

Write a small client as well that uses the custom worker class and install it on all the client machines:

    # Client
    use Distributed::Process;
    use Distributed::Process::Client;
    use MyWorker;

    $client = new Distributed::Process::Client -worker_class => 'MyWorker',
        -host => 'the-server', -port => 8147;
    $client->run();

DESCRIPTION

This modules distribution provides a framework to run tasks simultaneously on several computers, while centrally keeping control from another machine.

Architecture Overview

The tasks to run are implemented in a "worker" class, that derives from D::P::Worker; let's call it MyWorker. The subclass must overload the run() method that will be invoked from the server.

Server Side

On the server side, a D::P::Server object will handle the network connections, i.e. sockets. Each handle is associated with a D::P::Interface object. This object can be either be a D::P::Master, or a D::P::RemoteWorker.

Instead of being bound to a network socket, the D::P::Master object is typically bound to the standard input and output, and can thus receive orders from the user and give feedback on the terminal. It maintains a list of D::P::RemoteWorker objects, one for each network connection.

The D::P::RemoteWorker objects implement the communication between the server and the clients. Its inheritance is changed at run-time, so that it is a subclass of the MyWorker class, and thus benefits from all the methods implemented in the worker class.

When the D::P::Master receives the /run command (on standard input), it invokes the run() method on each of the D::P::RemoteWorker objects, which in turn will send a /run command to their connected client.

After the run() is over, the D::P::Master broadcasts the /get_result command and gathers the results from all D::P::RemoteWorker objects, and prints out the results.

Client Side

On the client side, a D::P::Client object manages to connection to the server and instanciates the MyWorker class, derived from D::P::Worker.

When the client receives the /run command from the server, it invokes the run() method of the MyWorker class. This method can in turn invoke methods from D::P::LocalWorker (which it derives from) to talk back to the server:

synchro(): enables all the workers to wait for all the others to reach the same point in the execution of run() before proceeding.

delay(): just like synchro(), but after the synchronization point is reached, each worker will go on a short time after the previous worker. This prevents all the workers to run a task exactly at once, but rather spreads the work on a longer period of time.

run_on_server(): let a method be run on the server, instead of the client.

time(): measures the time another method takes to complete and reports it.

result(): records a string as a "result". It will be sent back to the server after the run is complete.

Constructor

new LIST

Although this class is not supposed to be instanciated, it provides a constructor for its subclasses to inherit from. This constructor takes a LIST of named arguments. The names will be converted to lowercase and stripped off from their leading hyphens, if any. The constructor then calls the method by the same name with the value as argument. These calls are the same:

    $obj = new Distributed::Process  method => $value;
    $obj = new Distributed::Process -method => $value;
    $obj = new Distributed::Process -METHOD => $value;

    $obj = new Distributed::Process;
    $obj->method($value);

Exports

This module exports the DEBUG(), ERROR(), WARN() and INFO() functions that are no ops by default. If you import the :debug, :error, :warn and/or :info special tags, the corresponding functions are turned into one that prints its arguments to standard error.

You need importing the special tags only once for this to take effect. For exemple the main program can say:

    use Distributed::Process qw/ :debug /;

While all the other modules just say:

    use Distributed::Process;

Still, the DEBUG function will become active everywhere.

Functions

DEBUG LIST

ERROR LIST

WARN LIST

INFO LIST

By default, these functions do nothing. However, if at some point the :debug, :error, :warn, or :info tag were imported, these functions will print their arguments to standard error, prepended with the Process ID, the fully qualified name of its caller, and the thread id, e.g.:

    <DBG>3147:Package::function(1): message
    <ERR>3147:Package::function(1): message
    <WRN>3147:Package::function(1): message
    <INF>3147:Package::function(1): message

If the global variable $ID is declared in the main program, it will be used instead of the Process ID:

    our $ID = 'server';

    <DBG>server:Package::function(1): message
    <ERR>server:Package::function(1): message
    <WRN>server:Package::function(1): message
    <INF>server:Package::function(1): message

AUTHOR

Cédric Bouvier, <cbouvi@cpan.org>

BUGS

Please report any bugs or feature requests to bug-distributed-process@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2005 Cédric Bouvier, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Distributed::Process

perl -MCPAN -e shell
install Distributed::Process