The deployment of the Master/Slave framework relies on the ProActive deployment mechanism . In order to deploy a set of worker, the master needs either:

For a better explanation of the ProActive deployment mechanism and of ProActive deployment descriptors, see Chapter 22, XML Deployment Descriptors .

Figure 17.1.  Deployment of the master/slave framework

In order to submit tasks to the Master, the Task interface from the Master/Slave API needs to be implemented. In this interface, the unique method run will correspond to the code being executed remotely. After tasks have been submitted to him, the master will dispatch tasks automatically to the slaves.

Warning ! : when a Java object implementing the Task interface (i.e. a user task) is submitted to the master, the object will be deep-copied to the master. In consequence, every referenced objects will also be copied. When tasks are submitted to the remote slaves, the user task objects will be serialized and sent though the network. As a consequence, information which means something only locally will be lost (database connections, reference to a thread, etc...)

Figure 17.2. Tasks definition and submission

Results will be collected by the master when the calculations are complete. Users can either wait that one or every results are available. Users have also the option to ask the master for result availability and continue their own work until results are finally available.

Figure 17.3. Results gathering

Two results can be received in two modes specified in the ResultReceptionMode :

The figures below explain the two different modes :

Figure 17.4. Completion order

Figure 17.5. Submission order

The Master/Slave API entry point and main class is the following:

org.objectweb.proactive.examples.masterslave.ProActiveMaster

The methods of this class are described in the interface:

org.objectweb.proactive.examples.masterslave.interfaces.Master

The user has the possibility to create either a local master or a remote master.

    /**
     * Creates a local master (you can add resources afterwards)
     */
    public ProActiveMaster();

    /**
     * Creates an empty remote master that will be created on top of the given Node <br>
     * Resources can be added to the master afterwards
     * @param remoteNodeToUse this Node will be used to create the remote master
     */
    public ProActiveMaster(Node remoteNodeToUse);

    /**
     * Creates a remote master with the URL of a descriptor and the name of a virtual node
     * The master will be created on top of a single resource deployed by this virtual node
     * @param descriptorURL url of the ProActive descriptor
     * @param masterVNName name of the virtual node to deploy inside the ProActive descriptor
     */
     
    public ProActiveMaster(URL descriptorURL, String masterVNName);

    /**
     * Adds the given Collection of nodes to the master <br/>
     * @param nodes a collection of nodes
     */
    void addResources(Collection<Node> nodes);
    
    /**
     * Adds every resource inside the given virtual node to the master <br/>
     * @param virtualnode a virtual node object
     */
    void addResources(VirtualNode virtualnode);

    /**
     * Adds the given descriptor to the master<br>
     * Every virtual nodes inside the given descriptor will be activated<br/>
     * @param descriptorURL URL of a deployment descriptor
     */
    void addResources(URL descriptorURL);

    /**
    * Adds the given descriptor to the master<br>
    * Only the specified virtual node inside the given descriptor will be activated <br/>
    * @param descriptorURL URL of a deployment descriptor
    * @param virtualNodeName name of the virtual node to activate
    */
    void addResources(URL descriptorURL, String virtualNodeName);

The task interface is defined at:

org.objectweb.proactive.examples.masterslave.interfaces.Task

public interface Task<R extends Serializable> extends Serializable {
    /**
     * A task to be executed
     * @param memory access to the slave memory
     * @return the result
     * @throws Exception
     */
    public R run(SlaveMemory memory) throws Exception;
};

Users need to implement the Task interface to define their tasks. The SlaveMemory parameter is explained in the Advanced Usage chapter.

    /**
     * Adds a list of tasks to be solved by the master <br/>
     * @param tasks list of tasks
     * @throws TaskAlreadySubmittedException if a task is submitted twice
     */
    void solve(List<T> tasks) throws TaskAlreadySubmittedException;

Warning ! : the master keeps a track of task objects that have been submitted to it and which are currently computing. Submitting two times the same task object without waiting for the result of the first computation is not allowed.

    /**
     * Wait for all results, will block until all results are computed <br>
     * The ordering of the results depends on the result reception mode in use <br>
     * @return a collection of objects containing the result
     * @throws TaskException if a task threw an Exception
     */
    List<R> waitAllResults() throws TaskException;

    /**
     * Wait for the first result available <br>
     * Will block until at least one Result is available. <br>
     * Note that in SubmittedOrder mode, the method will block until the next result in submission
 order is available<br>
     * @return an object containing the result
     * @throws TaskException if the task threw an Exception
     */
    R waitOneResult() throws TaskException;

    /**
     * Wait for a number of results<br>
     * Will block until at least k results are available. <br>
     * The ordering of the results depends on the result reception mode in use <br>
     * @param k the number of results to wait for
     * @return a collection of objects containing the results
     * @throws TaskException if the task threw an Exception
     */
    List<R> waitKResults(int k) throws TaskException;

    /**
     * Tells if the master is completely empty (i.e. has no result to provide and no tasks
 submitted)
     * @return the answer
     */
    boolean isEmpty();

    /**
     * Returns the number of available results <br/>
     * @return the answer
     */
    int countAvailableResults();

Five methods can be used in order to collect results:

    /**
     * Terminates the master (and eventually free every resources)
     * @param freeNodeResources tells if the master should as well free the node resources
     * @return success
     */
    public void terminate(boolean freeResources);

One single method is used to terminate the master. A boolean parameter tells the master to free resources or not (i.e. terminate remote JVMs).