NAME

Distributed::Process::Master - a class to conduct the chorus of D::P::Workers, under a D::P::Server.

SYNOPSIS

    use Distributed::Process::Master;
    use Distributed::Process::Server;

    use MyWorker; # subclass of Distributed::Process::Worker

    $m = new Distributed::Process::Master
        -in_handle    => \*STDIN,
        -out_handle   => \*STDOUT,
        -worker_class => 'MyWorker',
    ;
    $s = new Distributed::Process::Server
        -master => $m,
        -port   => 8147,
    ;
    $s->listen();

DESCRIPTION

A D::P::Server manages a number of D::P::Interface objects, one of which is a Distributed::Process::Master. The role of the Master is to handle requests from the user, coming in on its in_handle() (usually, the standard input), and act as an interface between the user and the D::P::Worker objects.

Commands

A D::P::Master object will react on the following commands received on its in_handle().

/run

Invokes the run() method (see below).

/reset

Invokes the reset_result() method on all the Worker objects.

/freq NUMBER

Sets the frequency() to a new value

/quit

Invokes the quit() method on the P::D::Server, effectively shutting down the server and the clients.

Methods

add_worker WORKER

add_worker LIST

Adds a Worker to the list of known workers. If the first argument is a D::P::Worker, use this as the new worker. Otherwise, create a new instance of class worker_class(), passing LIST as arguments to the constructor.

In any case, the new worker will be passed the parameters defined by worker_args().

Returns the new worker object.

workers

Returns the list of known P::D::Worker objects. In scalar context, returns their number.

has_enough_workers

Returns true when the number of connected workers is enough (i.e., greater than or equal to n_workers()).

reset_result

Broadcast a message to all workers to flush their results list.

synchro TOKEN

This method is invoked when a worker receives a /synchro command from its connected client. It increments the counter associated with the TOKEN, and when this counter reaches the number of connected client (which means that all the clients have reached the synchronisation point), the master lets the workers send another /synchro message in reply to their clients, which can go on with the rest of their task.

delay TOKEN

This works much the same way as synchro(). This method is invoked when a worker receives a /delay command from its connected client. It increments the counter associated with the TOKEN, and when this counter reaches the number of connected client (which means that all the clients have reached the synchronisation point), the master lets the workers send another /delay message in reply to their clients. However, instead of sending these messages all at once, the master waits for some time to elapse between each client call. This time is configurable with the /freq command.

result

Returns the list of result() from the D::P::MasterWorker. Subclasses can overload this method to filter the results before they are sent to the user.

run_done

This method is called when a worker receives the /run_done command from its connected client. It increments a counter, and when all clients have sent this command, run_done() calls the result() method to gather the results from all the clients and send them to the out_handle().

run

Broadcast a message to the workers to let them send a /run command to their connected client.

available_for_reading

This method is called by the wait_for_pattern() method in Distributed::Process::Interface to check whether it should return or go on waiting for lines to read on the in_handle(). available_for_reading() returns 1 when something is available on in_handle() (i.e., the user has typed a command on the terminal), or 0 if a worker is sending a message. It blocks until one of the two happens.

wait_for_pattern(), in turn will read the in_handle() if available_for_reading() yielded 1, or return undef if it yielded 0.

listen

This method is called by the Distributed::Process::Server when enough clients are connected. It listens for commands typed by the user on the terminal and, at the same time, to messages sent by the workers, and take appropriate actions based on the command received.

worker_class NAME

worker_class

Returns or sets the class to use when instanciating P::D::Worker objects to handle incoming connections.

When setting the worker_class(), this method will call the go_remote() method on it to alter its inheritance, and make it a subclass of Distributed::Process::RemoteWorker.

worker_args LIST

worker_args ARRAYREF

worker_args

The list of arguments to pass to the worker_class() constructor. If the first argument is an array ref, it will be dereferenced.

Returns the former list of arguments or the current list when invoked without arguments.

Attributes

The following list describes the attributes of this class. They must only be accessed through their accessors. When called with an argument, the accessor methods set their attribute's value to that argument and return its former value. When called without arguments, they return the current value.

n_workers

The number of P::D::Worker that are expected to connect on the server. When enough connections are established, the Master will print a "ready to run" message to warn the user.

frequency

The frequency at which a method run by postpone() should be invoked, in Hz.

Suppose you want all the workers to run their __method() 0.25 seconds after one another. You'd write your Worker run() method like this:

    sub run {
        my $self = shift;
        $self->postpone(__method => 'arguments to __method);
    }

You'd then set the Master's frequency() to 4, to have it launch 4 calls per second, or 1 call every 0.25 second.

See Distributed::Process::Worker for details.

id

The unique ID for the Master, as a D::P::Interface is "master".

timeout

How often available_for_reading() will check for messages from the workers. The rest of the time, it will wait for messages on in_handle(). The default is 0.1 seconds, meaning that available_for_reading() will check for messages from the workers ten times per second.

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.

ACKNOWLEDGEMENTS

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.