This class can be used as an Active Object, serving requests. Its creation involves the following steps:

            public class TinyHello implements java.io.Serializable {
    static Logger logger = ProActiveLogger.getLogger(Loggers.EXAMPLES);
    private final String message = "Hello World!";

    /** ProActive compulsory no-args constructor */
    public TinyHello() {
    }

    /** The Active Object creates and returns information on its location
     * @return a StringWrapper which is a Serialized version, for asynchrony */
    public StringMutableWrapper sayHello() {
        return new StringMutableWrapper(
            this.message + "\n from " + getHostName() + "\n at " +
            new java.text.SimpleDateFormat("dd/MM/yyyy HH:mm:ss").format(new java.util.Date()));
    }

    /** finds the name of the local machine */
    static String getHostName() {
        try {
            return java.net.InetAddress.getLocalHost().toString();
        } catch (UnknownHostException e) {
            return "unknown";
        }
    }

    /** The call that starts the Acive Objects, and displays results.
     * @param args must contain the name of an xml descriptor */
    public static void main(String[] args)
        throws Exception {
        // Creates an active instance of class Tiny on the local node
        TinyHello tiny = (TinyHello) ProActive.newActive(
                TinyHello.class.getName(), // the class to deploy
                null // the arguments to pass to the constructor, here none
            ); // which jvm should be used to hold the Active Object

        // get and display a value 
        StringMutableWrapper received = tiny.sayHello(); // possibly remote call
        logger.info("On " + getHostName() + ", a message was received: " + received); // potential
 wait-by-necessity
        // quitting
        
        ProActive.exitSuccess();
    }
}

          

Implementing any remotely-accessible functionality is simply done through normal Java methods in a normal Java class, in exactly the same manner it would have been done in a non-distributed version of the same class. Here, the only method is sayHello

Now that we know how to write the class that implements the required server-side functionalities, let us see how to create the server object. We want this active object to be created on the current node, which is why we use newActive with only two parameters (done in the main method).

The code snippet which instantiates the TinyHello in the same VM is the following (in the main method):

        TinyHello tiny = (TinyHello) ProActive.newActive(
                TinyHello.class.getName(), // the class to deploy
                null // the arguments to pass to the constructor, here none
            ); // which jvm should be used to hold the Active Object

This is exactly like invoking a method on a local object of the same type. The user does not have to deal with catching exceptions related to the distant deployment.

As already stated, the only modification brought to the code by ProActive is located at the place where active objects are created. All the rest of the code remains the same, which fosters software reuse. So the way to call the sayHello method in this example is the following (in the main method):

        StringMutableWrapper received = tiny.sayHello(); // possibly remote call
        logger.info("On " + getHostName() + ", a message was received: " + received); // potential
 wait-by-necessity

To launch the example, you may type:

linux> java -cp $CLASSPATH -Djava.security.policy=scripts/proactive.java.policy 
            -Dlog4j.configuration=file:scripts/proactive-log4j 
            org.objectweb.proactive.examples.hello.TinyHello

windows> java -cp $CLASSPATH -Djava.security.policy=scripts\proactive.java.policy 
              -Dlog4j.configuration=file:scripts\proactive-log4j 
               org.objectweb.proactive.examples.hello.TinyHello

There are also scripts in the scripts directory:

linux> cd scripts/unix/ 
linux> tinyHello.sh

windows> cd scripts/windows 
windows> tinyHello.bat

[apple unix]tinyhello.sh
--- Hello World tiny example ---------------------------------
> This ClassFileServer is reading resources from classpath
ProActive Security Policy (proactive.runtime.security) not set. Runtime Security disabled
Created a new registry on port 1099
//apple.inria.fr/Node628280013 successfully bound in registry at //apple.inria.fr/Node628280013
Generating class: pa.stub.org.objectweb.proactive.examples.hello.Stub_TinyHello
Generating class: pa.stub.org.objectweb.proactive.core.util.wrapper.Stub_StringMutableWrapper
On apple/138.96.218.62, a message was received: Hello World!
  from apple/138.96.218.62
  at 03/11/2005 14:25:32

Below are described the different steps in more details.

A simple example

This example is the ProActive version of the Readers/Writers canonical problem. To illustrate the ease-of-use of the ProActive model, different synchronization policies can be applied without even stopping the application. This example is based on a easy to use Swing GUI.

This example is one possible implementation of the well-known Dining Philosophers synchronization problem. This example is based on a easy to use Swing GUI.

This example has more fancy GUI stuff. It can be used later on to see how to deploy on several machines, and also for the Fault-tolerant features.

Using the script c3d_no_user, a "Dispatcher" object is launched (ie a centralized server) as well as 4 "Renderer" objects, which are active objects to be used for parallel rendering.

Figure 5.2. the dispatcher GUI is launched

The bottom part of the window allows to choose which renderers should participate in the rendering. You may want to stop using a given machine (because for instance it is overloaded), and thus remove it from the renderers used in the current computation.

Using c3d_add_user,

For example, the user 'alice'

Which configuration is the fastest for the rendering?

Are you on a multi-processor machine?

	Note
	You might not perceive the difference of the performance. The difference is better seen with more distributed nodes and objects (for example on a cluster) .

Using the c3d_add_user script, and specifying the host (set to local host bydefault)

Figure 5.3. Specifying the host

If you use rlogin, make sure the DISPLAY is properly set. You must use the same version of ProActive on both machines!

Notice that a collaborative consensus must be reached before starting some actions (or that a timeout occured).

You will need at first to start IC2D using either ProActive/scripts/unix/ic2d.sh or ProActive/scripts/windows/ic2d.bat depending on your environment.

In order to visualize all Active objects, you need to acquire ('Monitoring/Monitor a new RMI host' menu):

Figure 5.4. The C3D application when a new user joins in, seen with IC2D

From IC2D, you can drag-and-drop active objects from one JVM to another. Click the right button on a C3DRenderingEngine, and drag and drop it in another JVM. Observe the migration taking place.

Add a new sphere, using all rendering engines, and check that the messages are still sent to the active object that was asked to migrate.

As migration and communications are implemented in a fully compatible manner, you can even migrate with IC2D an active object while it is communicating (for instance when a rendering action is in progress). Give it a try!

	Note
	You can also migrate Active Objects which create a GUI. If you do that for the User, you will see the graphical window beiung destroyed, and rebuilt once more.

Manually you can start a new JVM - a 'Node' in the ProActive terminology - that will be used in a running system.

linux> startNode.sh rmi://mymachine/NodeZ &
windows> startNode.bat rmi://mymachine/NodeZ 

The node should appear in IC2D when you request the monitoring of the new machine involved (Monitoring menu, then 'monitor new RMI host'.

	Note
	If you feel uncomfortable with the automatic layout, switch to manual using the 'manual layout' option (right click on the World panel). You can then reorganize the layout of the machines.

Depending on the machines you have, the complexity of the image, look for the most efficient configuration.

You can also write components with the Fractive API, which is an implementation of Fractal in ProActive. You should check the section on components for more information (Part V, “Composing”). There is a long explanation of the C3D component version (Chapter 10, C3D - from Active Objects to Components). The visual aspect is very similar to the standard Active Object C3D version. That's on purpose, to show how easy it is to transform code into components. If you want to run a components version of c3d, try this:

scripts/unix/components$ ./c3d.sh
scripts/windows/components$ c3d.bat

The component binding is done through the Fractal ADL, which is a standard way of writing components through an xml file. You can have a visual representation with IC2D (start IC2D, menu->Components->Start the components GUI). You should specify how to read the file. You have to enter:

Figure 5.5. IC2D component explorer with the C3D example

The main classes of this application are:

In the Dispatcher, look at the method public void rotateScene(int i_user, String i_user_name, Vec angle) that handles election of the next action to undertake.

The readers and the writers want to access the same data. In order to allow concurrency while ensuring the consistency of the readings, accesses to the data have to be synchronized upon a specified policy. Thanks to ProActive, the accesses are guaranteed to be allowed sequentially.

The implementation with ProActive uses 3 active objects: Reader, Writer, and the controller class (ReaderWriter).

5.3.1.1. Start the application

Figure 5.6. Using the readers script

ProActive starts a node (i.e. a JVM) on the current machine, and creates 3 Writer, 3 Reader, a ReaderWriter (the controller of the application) and a ReaderDisplay, that are active objects.

Figure 5.7. A GUI is started that illustrates the activities of the Reader and Writer objects.

public void evenPolicy(org.objectweb.proactive.Service service)

public void readerPolicy(org.objectweb.proactive.Service service)

public void writerPolicy(org.objectweb.proactive.Service service)

The 'dining philosophers' problem is a classic exercise in concurrent programming. The goal is to avoid deadlocks.

We have provided an illustration of the solution using ProActive, where all the philosophers are active objects, as well as the table (controller) and the dinner frame (user interface).

5.3.2.1. Start the philosophers application

Figure 5.8. With philosophers.sh or philosophers.bat

ProActive creates a new node and instantiates the active objects of the application: DinnerLayout, Table, and Philosopher

Figure 5.9. The GUI is started.

5.3.2.5. Start the IC2D application

IC2D is a graphical environment for monitoring and steering of distributed and Grid Computing applications.

• Being in the autopilot mode, start the IC2D visualization application (using ic2d.sh or ic2d.bat)

The ic2d GUI is started. It is composed of 2 panels: the main panel and the request queue panel

• Acquire your current machine

Figure 5.10. Monitoring new RMI host with IC2D

It is possible to visualize the status of each active object (processing, waiting etc...), the communications between active objects, and the topology of the system (here all active objects are in the same node):

Using the migration/penguin script.

Using the ic2d script

Acquire the machines you have started nodes on

An agent is materialized by a picture in a java window.

After selecting them, use the buttons to:

The InitializedHello class extends the Hello class, and implements the interfaces InitActive and EndActive.It acts a a server for the InitializedHelloClient class.

The main method is overriden so that it can instantiate the InitializedHello class

Execution is similar to the previous example; just use the InitializedHelloClient client class and InitializedHello server class.

linux> java -Djava.security.policy=scripts/proactive.java.policy \
            -Dlog4j.configuration=file:scripts/proactive-log4j 
            org.objectweb.proactive.examples.hello.InitializedHello 

windows> java -Djava.security.policy=scripts\proactive.java.policy  \
              -Dlog4j.configuration=file:scripts\proactive-log4j \
              org.objectweb.proactive.examples.hello.InitializedHello &

linux> java -Djava.security.policy=scripts/proactive.java.policy 
            -Dlog4j.configuration=file:scripts/proactive-log4j  \
            org.objectweb.proactive.examples.hello.InitializedHelloClient //localhost/Hello 

windows> java -Djava.security.policy=scripts\proactive.java.policy \
              -Dlog4j.configuration=file:scripts\proactive-log4j 
              org.objectweb.proactive.examples.hello.InitializedHelloClient //localhost/Hello 

The conditions for MigratableHello to be a migratable active object are:

- it must have a constructor without parameters: this is a result of a ProActive restriction : the active object having to implement a no-arg constructor. </ p>

- implement the Serializable interface (as it will be transferred through the network).</>

Hello, the superclass, must be able to be serialized, in order to be transferred remotely. It does not have to implement directly java.io.Serializable, but its attributes should be serializable - or transient. For more information on this topic, check Chapter 16, Active Object Migration .

We want to further enhance InitializedHello it by making migratable: we'd like to be able to move it across virtual machines.

Thus, we create a MigratableHello class, that derives from InitializedHello. This class will implement all the non-functionnal behavior concerning the migration, for which this example is created. The Hello class (and InitializedHello) is left unmodified.

Note that the migration has to be initiated by the active object itself. This explains why we have to write the moveTo method in the code of MigratableHello - i.e. a method that contains an explicit call to the migration primitive. (cf Chapter 16, Active Object Migration for migration documentation )

MigratableHello also implements a factory method for instanciating itself as an active object : static MigratableHello createMigratableHello(String: name)

The class diagram for the application is the following:

- start several nodes using the startnode script.

windows>cd scripts/windows
                                startNode.bat //localhost/n1
                                startNode.bat //localhost/n2
linux>cd scripts/linux
                ./startNode.sh //localhost/n1
                ./startNode.sh //localhost/n2       

- compile and run the program (run MigratableHelloClient), passing in parameter the urls of the nodes you'd like the agent to migrate to.

cd compile
windows>build.bat examples
linux>build examples
cd ..       

linux>java -Djava.security.policy=scripts/proactive.java.policy -Dlog4j.configuration=file:scripts/proactive-log4j org.objectweb.proactive.examples.hello.MigratableHelloClient //localhost/n1 //localhost/n2

windows>java -Djava.security.policy=scripts\proactive.java.policy -Dlog4j.configuration=file:scripts\proactive-log4j org.objectweb.proactive.examples.hello.MigratableHelloClient //localhost/n1 //localhost/n2

- observe the instance of MigratableHello migrating:

During the execution, a default node is first created. It then hosts the created active object. Then the active object is migrated from node to node, each time returning 'hello' and telling the client program where it is located.

We will write a new active object class, that extends MigratableHello. The sayHello method will create a window containing the hello message. This window is defined in the class HelloFrame

MigratableHello migratable_hello = MigratableHello.createMigratableHello("agent1");

with

MigratableHello migratable_hello = HelloFrameController.createHelloFrameController("agent1");

The displayed window: it just contains a text label with the location of the active object.

Download and decompress ProActive from http://

Create the file MyPi.java inside the tutorial directory with initially the following content:

package org.objectweb.proactive.examples.pi;

import org.objectweb.proactive.ProActive;
import org.objectweb.proactive.core.descriptor.data.ProActiveDescriptor;
import org.objectweb.proactive.core.descriptor.data.VirtualNode;
import org.objectweb.proactive.core.group.ProActiveGroup;
import org.objectweb.proactive.core.node.Node;

class MyPi{

// global variables will go here

public static void main(String args[]) throws Exception{
  
  Integer numberOfDecimals =  new Integer(args[0]);
  String descriptorPath = args[1];

  // the main code will go here
} 

Inside the main we add the code for acquiring the resources.

  ProActiveDescriptor descriptor = ProActive.getProactiveDescriptor(descriptorPath); //Parse the xml descriptor
  descriptor.activateMappings(); //Acquire the resources
  VirtualNode virtualNode = descriptor.getVirtualNode("computers-vn"); //Get the virtual node named "computers-vn"
  Node[] nodes = virtualNode.getNodes();

  PiComputer piComputer = (PiComputer) ProActiveGroup.newGroupInParallel(
                          PiComputer.class.getName(),
                          new Object[] { numberOfDecimals }, 
                          nodes);

  int numberOfWorkers = ProActiveGroup.getGroup(piComputer).size();

  Interval intervals = PiUtil.dividePI(numberOfWorkers, numberOfDecimals.intValue());
  ProActiveGroup.setScatterGroup(intervals);

  Result results = piComputer.compute(intervals);

  Result result= PiUtil.conquerPI(results);
  System.out.println("Pi:"+result);

  descriptor.killall(true);
  System.exit(0);

pi$ cd scripts
scripts$ ./build mypi -Ddecimals=100 -Ddescriptor=../descriptors/localhost.xml

In this chapter we are going to see a simple example of an MPI written program ported to ProActive.

First let's introduce what we are going to compute.

This simple program approximates pi by computing :

pi = integral from 0 to 1 of 4/( 1+x*x ) dx

Which is approximated by :

sum from k=1 to N of 4 / ( ( 1 +( k-1/2 ) **2 )

The only input data required is N, the number of iterations.

Involved files :

This section of the guided tour goes through the different steps that you would take in writing an application with ProActive, from a simple design, to a more complicated structure. This is meant to help you get familiar with the Group facilities offered by ProActive. Please take note that this page tries to take you through the progression, step by step. You may find some more information, mainly on the design, on the web page of the applications/examples of ProActive. This is a snapshot of the ProActive nbody example running on 3 hosts with 8 bodies:

Figure 9.1. NBody screenshot, with 3 hosts and 8 bodies

Figure 9.2. NBody screenshot, with the application GUI and Java3D installed

n-body is a classic problem. It consists in working out the position of bodies in space, which depend only on the gravitational forces that apply to them. A good introduction to the problem is given here. You may find a detailled explanation of the underlying mathematics here. Different ways of finding numerical solutions are given here.

In short, one considers several bodies (sometimes called particles) in space, where the only force is due to gravity. When only two bodies are at hand, this is expressed as

Fp->b is the force that p applies on b, G is the gravitational constant, mpmb describe the mass of the bodies, r is the distance between p and b, andu is a unit vector in the direction going from p to b. When we consider all the forces that apply to one given body, we have to sum up the contribution of all the other bodies: This should be read as: the total force on the body b is the sum of all the forces applied to b, generated by all the other bodies in the system. This is the force that has to be computed for every body in the system. With this force, using the usual physics formulae, (Newton's second Law) one may now compute the movement of a particle for a given time step (a the acceleration, v the velocity, x the position, t the time):

With script located in the folder ProActive/script/[unix|windows] do:

$ nbody.[bat|sh] [-nodisplay | -displayft | -3d | -3dft] totalNbBodies maxIter

Right after starting the application, users have to choose one algorithm for computing. The choice is between:

Mouse controls with the 3D GUI:

This guided tour is based on the files you may find in the directory ProActive/src/org/objectweb/proactive/examples/nbody. You'll find the following tree:

Figure 9.3. The nbody directory structure

The common directory contains files reused through the different versions. 'simple' is the simplest example, 'groupcom' is the first example with Group communication, and 'groupdistrib' and 'groupoospmd' are two enhancements based on different synchronization schemes. 'barneshut' is a bit special, in that it contains a different algorithm to solve the nbody problem.

The files contained in 'common' are those that are reused throughout the different versions. Let's see what they do:

The files contained in the other directories, 'simple', 'groupcom', 'groupdistrib' , 'groupoospmd' detail steps of increasing complexity, making the application use different concepts. 'barneshut' contains the final implementation, featuring the Barnes-Hut algorithm. But let's not go too fast. Let's have a look at the insides of the simplest implementation of the n-body problem.

This is the implementation of the simplest example of nbody. We defined the Planet to be a passive object, and it does nothing. It is a container for position, velocity and mass, as we've seen in the description given higher up. The real actors are the Domains, they do all the work. Every Planet in the universe is associated with a Domain, which is an Active Object. This Domain contains the code to manage the communication of the possitions of the Planets during the simulation. They are created in the Start.java file:

         Rectangle universe = new Rectangle (-100,-100,100,100);
         Domain [] domainArray = new Domain [totalNbBodies];
         for (int  i = 0 ; i < totalNbBodies ; i++)  {
             Object [] constructorParams = new Object [] {
                      new Integer(i),
                      new Planet (universe)
                 };
             try {
                 // Create all the Domains used in the simulation
                 domainArray[i] = (Domain) ProActive.newActive(
                         Domain.class.getName(),
                         constructorParams,
                         nodes[(i+1) % nodes.length]
                 );
             }
             catch (ActiveObjectCreationException e) { killsupport.abort(e); }
             catch (NodeException e) {  killsupport.abort(e); }
         }

See how the call to ProActive.newActive creates one new Active Object, a Domain, at each iteration of the loop. The array nodes contains all the nodes on which an Active Object may be deployed; at each iteration, one given node, ie one JVM, is selected. The constructorParams are the parameters that are to be passed to the constructor of Domain, and since it's an Object [] , the parameters may only be Objects (don't try to build constructors using ints in their constructor - this explains the use of the class Integer).

The Domains, once created, are initialized, and then they synchronize themselves by all pinging the maestro, with the notifyFinished call:

         // init workers, from the Start class
         for (int i=0 ; i < totalNbBodies ; i ++)
             domainArray[i].init(domainArray, displayer, maestro);
          // init method, defined within each worker
         

          public void init(Domain [] domainArray, Displayer dp, Maestro master) {
                   this.neighbours = domainArray;
                   .....
                   maestro.notifyFinished();  // say we're ready to start
                   }

         public void notifyFinished() {
             this.nbFinished ++;
             if (this.nbFinished == this.domainArray.length) {
                 this.iter ++; 
                 if (this.iter==this.maxIter)
                      this.killsupport.quit();
                 this.nbFinished = 0 ;
                   for (int i= 0 ; i < domainArray.length ; i++)
                       this.domainArray[i].sendValueToNeighbours();
           }
           }

Notice how domainArray is passed to all the Domains, when calling init. This is the value assigned to the local field neighbours, which later on serves to communicate with all the other Domains of the simulation.

The synchronization is done by the Maestro, which counts the number of Domains that have finished, and then asks them to go on to the next iteration. While in their execution, the Domains gather information concerning the position of all the other bodies, which need to be known to move the local Planet, at every time step. This is done using a push scheme. Instead of explicitly asking for information, this information is automatically issued:

       public void sendValueToNeighbours() {
            for (int i = 0 ; i < this.neighbours.length ; i ++)
               if (i != this.identification) // don't notify self!
                   this.neighbours[i].setValue(this.info, this.identification);
             .....  
            }
       
        public void setValue(Planet inf, int id) {
           this.values [id] = inf;
           this.nbReceived ++ ;
           if (this.nbReceived > this.nbvalues)  // This is a bad sign!
               System.err.println('Domain ' + identification + ' received too many answers');
           if (this.nbReceived == this.nbvalues) {
               this.maestro.notifyFinished();
               moveBody();
           }
           }  

This means that each Domain sends its information to all the other Domains, and then waits until it has received all the positions it is waiting for. The other Domains are stored as an array, which is called neighbours. You may find another view of this example on this web page.

This is a simple improvement, which results in faster communication. You may have noticed the Group capabilities of ProActive. They give us the ability to call an operation on an object which is a Group, and have it sent to all the members of the Group. We can use them in this framework: first, create a Group (instead of having independant Active Objects) :

           // in the Start class
            Object [][] params = ...
            Domain  domainGroup = null;
            try {
                // Create all the Domains as part of a Group
                domainGroup = (Domain) ProActiveGroup.newGroup ( Domain.class.getName(), params,
 nodes);
            }
            catch ....>

The double array params stores the parameters passed to the constructors of the Domains we're creating. Domain 0 will have params[0][] passed as arguments, Domain 1 params[1][], and so on. The nodes are the Nodes on which to create these Active Objects. Do notice the try... catch construction which is needed around any creation of Active Objects because it may raise exceptions. In this previous bit of code, a Group containing new Active Objects has been created and all these Objects belong to the group . You may have noticed that the type of the Group is Domain. It's a bit strange at first, and you may think this reference points to only one Active Object at once, but that's not true. We're accesssing all the objects in the group, and to be able to continue using the methods of the Domain class, the group is typed as Domain, and that's the reason why it's called a typed Group.

Then this group is passed as a parameter to all the members of the Group in just one call:

         // Still in the Start class
            domainGroup.init(domainGroup, displayer, maestro);
           

This method sets the local field as a copy of the passed parameter, and as such is unique. We can play around with it without affecting the others. So let's remove the local Domain from the Group, to avoid having calls on self:

               public void init(Domain domainGroup, Displayer dp, Maestro master) {
                 this.neighbours = domainGroup;
                 Group g = ProActiveGroup.getGroup(neighbours);
                 g.remove(ProActive.getStubOnThis()); // no need to send information to self
               .....
              

Remember that in the previous example, the neighbours where stored in an array, and each was accessed in turn:

         for (int i = 0 ; i < this.neighbours.length ; i ++)
               if (i != this.identification) // don't notify self!
               this.neighbours[i].setValue(this.info, this.identification);

Well, that's BAAAAD, or at least inefficient! Replace this by the following code, because it works faster:

this.neighbours.setValue(this.info, this.identification);

This has the following meaning: call the method setValue, with the given parameters, on all the members of the Group neighbours. In one line of code, the method setValue is called on all the Active Objects in the group.

You may find another view of this example on this web page.

Now, do we like the idea that the synchronization is centralized on one entity, the Maestro? I don't and it's the bottleneck of the application anyway: once a Domain has finished, it sends the notifyFinshed, and then sits idle. A way of making this better is to remove this bottleneck completely! This is done by using an odd-even scheme: if a Domain receives information from a distant Domain too early (ie in the wrong iteration), this information is stored, and will get used at the next iteration. In the meantime, the local Domain does not change its iteration, because it is still waiting for more results, in the current iteration.

         public void setValue(Planet inf, int receivedIter) {
           if (this.iter == receivedIter) {
             this.currentForce.add(info, inf);
             this.nbReceived ++ ;
             if (this.nbReceived == this.nbvalues)
                 moveBody();
         }
         else {
             this.prematureValues.add(new Carrier (inf, receivedIter));
         }
         }

Also notice how the computation is done incrementally when the result is received (this.currentForce.add(info, inf);), instead of when all the results have arrived. This allows for less time spent idle. Indeed, waiting for all the results before computing might leave idle time between setValue requests. And then, just before computing the new position of the body, the sum of all the forces has to be computed. It's better to have this sum ready when needed.

The prematureValues Vector is the place where we put the values that arrive out of sync. When a value is early, it is queued there, and dequeued as soon as this Domain changes iteration.

         public void sendValueToNeighbours()  {
                   reset();                  
                   this.iter++;
                   if (this.iter < this.maxIter) {                           
                       neighbours.setValue(this.info, this.iter);                      
                       ... // display related code
                       treatPremature();                  
                       }                  
                    ... // JVM destruction related code             
             }   
            

The treatPremature() method simply treats the values that were early as if they had just arrived, by calling the setValue method with the parameters stored.

You may find another view of this example on this web page.

This is another way to improve the groupcom example. It also removes the master, but this time by inserting oospmd barriers, that can be thought as behaving like the maestro class, but faster. To create functional OOspmd Groups, there is a special instruction, which takes the same parameters as a newGroup instruction:

         Object [][] params =  ...
         Domain domainGroup = null;
         try {
              domainGroup = (Domain) ProSPMD.newSPMDGroup( Domain.class.getName(), params, nodes);
             }
             catch ...

Now, to use this OOspmd group properly, we want to use the barrier() methods. We put these in the Domains code, to do the synchronization. What happens is that each Domain hits the barrier call, and then waits for all the others to have reached it, before reading its request queue again.

 public void sendValueToNeighbours() {
    this.neighbours.setValue(this.info, this.identification);       
    ProSPMD.barrier('barrier' + this.iter);
    this.iter++;
    this.asyncRefToSelf.moveBody();    
  ....
 

Beware, the stop-and-wait is not just after the barrier call, but instead blocks the request queue. So if there is code after that barrier, it will get executed. In fact, the barrier should be seen as a prioritary request on the queue. This explains why we had to put the code after the barrier as a method placed on an asynchronous refernce to self. If we hadn't done it that way, but just appended the code of that method just after the barrier, the call to moveBody() would be executed before the barrier execution, which is exactly what we don't want!

You may find another view of this example on this web page.

This way to construct the nbody simulation is based on a very different algorithm. This is inserted to show how one can express this algorithm in ProActive, but breaks off from the previous track, having such a different approach to solving the problem. Here's how it works:

To avoid broadcasting to every active object the new position of every particle, a tree implementation can simplify the problem by agglomerating sets of particles as a single particle, with a mass equal to the sum of masses of the all the particles:. This is the core of the Barnes-Hut algorithm. References on this can be found for example here, and here. This method allows us to have a complexity brought down to O(N log N).

In our parallel implementation, we have defined an Active Object called Domain, which represents a volume in space, and which contains Planets. It is either subdivided into smaller Domains, or is a leaf of the total tree, and then only contains Planets. A Planet is still an Object with mass, velocity and position, but is no longer on a one-to-one connection with a Domain. We have cut down communications to the biggest Domains possible : when a Planet is distant enough, its interactions are not computed, but it is grouped with its local neighbours to a bigger particle. Here is an example of the Domains which would be known by the Domain drawn in red:

The Domain in the lower left hand-corner, drawn in blue, is also divided into sub-Domains, but this needs not be known by the Domain in red: it assumes all the particles in the blue Domain are only one big one, centered at the center of mass of all the particles within the blue.

In this version, the Domains communicate with a reduced set of other Domains, spanning on volumes of different sizes. Synchronization is achieved by sending explicitely iteration numbers, and returning when needed older positions. You may notice that some Domains seem desynchronized with other ones, having several iterations inbetween. That is no problem because if they then need to be synchronized and send each other information, a mechanism saving the older positions permits to send them when needed.

You may find another view of this example on this web page.

In this guided tour, we tried to show different facilities provided by ProActive, based on a real problem (nbody). We first saw how to deploy the application, then tuned it by adding Group communication, then removed a bottleneck ( due to the hard synchronization ) . Finally, given is the code associated to a different algorithm, which cumbersomely shows how to get Active Objects deployed along a tree structure to communicate. Remember that there is another explanation of all this on the web.

What we need to do is to extract the interfaces of the Objects, ie find which methods are going to be called on the components. This means find out what methods are called from outside the Active Object. You can do that by searching in the classes where the calls are made on active objects. For this, you have to know in detail which classes are going to be turned into component. If you have a code base which closely follows Object Oriented Programming rules, the interfaces are already there. Indeed, when a class is written, it should always go with one or more interfaces, which present to the world what the class abilities are. In C3D (Active Object version), these interfaces already exist: they are called User, Engine and Dispatcher.

Note

Tricky part: whatever way you look at components, you'll have to modify the initial code if these interfaces were not created at first go. You have to replace all the class references by their interface, when you use them in other files. For example, if we had not already used interfaces in the C3D Object code, we would have had to replace all occurrences of C3DDispatcher by occurrences of Dispatcher.

Why do we have to do that, replacing classes by interfaces? That's due to the way components work. When the components are going to be bound, you're not binding the classes themselves (ie the container which performs operations), but [proxies to] the interfaces presenting the behaviour available. And these proxies implement the interfaces, and do not extend the classes. What is highlighted here is that components enforce good code design by separating behaviours.

You now have to create a class that englobes the previous Active Objects, and which is a component representing the same functionality. How do you do that? Pretty simple. All you need to do is extend the Active Object class, and add to it the non-functional interfaces which go with the component. You have the binding interfaces to create, which basically say how to put together two Components, tell who is already attached, and how to separate them. These are the lookupFc, listFc, bindFc and unbindFc methods.

This has been done in the *Impl files. Let's consider, for example, the UserImpl class (it is shown below).What you have here are those component methods. Be even more careful with this bindFc method. In fact, it really binds the protected Dispatcher variable c3ddispatcher. This way, the C3DUser code can now use this variable as if it was addressing the real Active Object. Just to be precise, we have to point out that you're going through proxies before reaching the Component, then the Active Object. This is hidden by the ProActive layer, all you should know is you're addressing a Dispatcher, and you're fine! The findDispatcher method has been overridden because component lookup doesn't work like standard Active Object lookup.

       public class UserImpl extends C3DUser implements BindingController, User {
    /** Mandatory ProActive empty no-arg constructor */
    public UserImpl() {
    }

    /** Tells what are the operations to perform before starting the activity of the AO.
     * Registering the component and some empty fields filling in is done here.
     * We also state that if migration asked, procedure  is : saveData, migrate, rebuild */
    public void initActivity(Body body) {
        // Maybe 'binding to dispatcher' has been done before
        if (this.c3ddispatcher == null) {
            logger.error(
                "User component could not find a dispatcher. Performing lookup");

            // ask user through Dialog for userName & host
            NameAndHostDialog userAndHostNameDialog = new NameAndHostDialogForComponent();
            this.c3ddispatcher = userAndHostNameDialog.getValidatedDispatcher();
            setUserName(userAndHostNameDialog.getValidatedUserName());

            if (this.c3ddispatcher == null) {
                logger.error("Could not find a dispatcher. Closing.");
                System.exit(-1);
            }
        }

        if (getUserName() == null) { // just in case it was not yet set.
            setUserName("Bob");
        }

        // Register the User in the Registry. 
        try {
            Fractive.register(Fractive.getComponentRepresentativeOnThis(),
                UrlBuilder.buildUrlFromProperties("localhost", "User"));
        } catch (IOException e) {
            logger.error("Registering 'User' for future lookup failed");
            e.printStackTrace();
        }

        super.initActivity(body);
    }

    /** returns all the possible bindings, here just user2dispatcher .
     * @return the only posible binding "user2dispatcher" */
    public String[] listFc() {
        return new String[] { "user2dispatcher" };
    }

    /** Returns the dispatcher currently bound to the client interface of this component
     * @return null if no component bound, otherwise returns the bound component */
    public Object lookupFc(final String interfaceName) {
        if (interfaceName.equals("user2dispatcher")) {
            return c3ddispatcher;
        }

        return null;
    }

    /** Binds to this UserImpl component the dispatcher which should be used. */
    public void bindFc(final String interfaceName, final Object serverInterface) {
        if (interfaceName.equals("user2dispatcher")) {
            c3ddispatcher = (org.objectweb.proactive.examples.c3d.Dispatcher) serverInterface;

            // Registering back to the dispatcher is done in the go() method 
        }
    }

    /** Detaches the user from its dispatcher.
     * Notice how it has not been called in terminate() ?
     * This is due to the fact that unbinding only sets a reference to null,
     * and does no cleaning up. */
    public void unbindFc(final String interfaceName) {
        if (interfaceName.equals("user2dispatcher")) {
            c3ddispatcher = null;
        }
    }
}

      

If you're out of luck, the code contains instructions to retain references to objects that call methods on the current Object. These methods have a signature ressembling method(..., ActiveObject ao, ...). This is called, in ProActive, with a ProActive.getStubOnThis() (if you don't, and instead use 'this', the code won't work correctly on remote hosts!). If the local object uses this ProActive.getStubOnThis(), you're going to have trouble with components. The problem is that this design does not fit the component paradigm: you should be using declared interfaces bound with the bind methods, not be passing along references to self. So you have to remove these from the code, and make it component-oriented. But remember, you should be using bind methods to attach other components.

	Note
	If you really have to keep these ProActive.getStubOnThis() references, you may, because components, (or at least their internals) really are Active Objects. But you should be extra careful. This "Active Object reference passing" should not happen between components, as they are meant to interact through their component interfaces only.

One feature given by the component architecture is the possiblity to rename Virtual Nodes. Let's see how this can be used:

Suppose you are only dealing with packaged software. That means you may not modify the source code of some part of your application, for instance because it is kindly given to you by some other company, which wants to keep parts of its codebase secret. Let's say that the deployment descriptor you're using does not reference the proper VirtualNodes. How can you still deploy your application in this case? Well, you have to rename those Nodes into the names that are fitting to your application. You should do that after the definition of the interfaces that are defined inside the component. Here's an example of how to do that, renaming the externally provided name 'UserVirtualNode' to the name internally used by UserImpl 'User':

In the main ADL file (userAndComposite.fractal)

  <component ... />
       
    <!-- mapping the node names in the descriptor file to others referenced in the component's
 adl files. -->
    <exportedVirtualNodes>
      <exportedVirtualNode name="UserVirtualNode">
        <composedFrom>
           <composingVirtualNode component="user" name="User"/>
        </composedFrom>
      </exportedVirtualNode>
    </exportedVirtualNodes>
       
    <!-- Creating one user component -->

In the User ADL file (UserImpl.fractal)

<content class="org.objectweb.proactive.examples.components.c3d.UserImpl"/>
       
    <!-- Recalling a renamed Virtual Node -->
    <exportedVirtualNodes>
      <exportedVirtualNode name="User">
        <composedFrom>
          <composingVirtualNode component="this" name="User"/>
        </composedFrom>
      </exportedVirtualNode>
    </exportedVirtualNodes>
       
    <controller desc="primitive"/>

If you add this code into the adl, you are saying that the VirtualNode called UserVirtualNode (found in the deployment descriptor file the application is using) should be recognized by the application as if it was called User.

	Note
	Above has been described the way to rename a VirtualNode; this can be used on packaged software, when the VirtualNodes provided do not fit the VirtualNodes needed by your application.

When running the User Component alone, you are prompted for an address on which to lookup a Dispatcher Component. Then the two components are bound through a lookup mechanism. This is very simple to use. Here's the code to do that:

Fractive.register(Fractive.getComponentRepresentativeOnThis(),
      UrlBuilder.buildUrlFromProperties("localhost", "Dispatcher"));

ProActiveComponentRepresentative a = Fractive.lookup(
      UrlBuilder.buildUrl(this.hostName, "Dispatcher", protocol, this.portNumber));
      this.c3dDispatcher = (Dispatcher) a.getFcInterface("user2dispatcher");

For the registeration, you only need a reference on the component you want to register, and build a url containing the name of the host, containing an alias for the Component.

The Fractive.lookup method uses a Url to find the host which holds the component. This Url contains the machine name of the host, communication protocl and portNumber, but also the lookup name under which the desired Component has been registered under , here "Dispatcher". The last operation consists only in retreiving the correct interface to which to connect to. If the interface is not known at compile-time, it can be discovered at run-time with the getFcInterfaces() method, which lists all the interfaces available.

The first parameter of newActive is a string containing the fully-qualified name of the class we want to make active. Parameters to the constructor have to be passed as an array of Object. Then, according to the type of the elements of this array, the ProActive runtime determines which constructor of class A to call. Nevertheless, there is still room for some ambiguity in resolving the constructor because:

    public A (int i) {
        //
    }
    public A (Integer i) {
        //
    }
    public A (int i, String s) {
        //
    }
    public A (int i, Vector v) {
        //
    }

It is possible to pass a third parameter to the call to newActive in order to create the new active object on a specific JVM, possibly remote. The JVM is identified using a Node object that offers the minimum services ProActive needs on a given JVM to communicate with this JVM. If that parameter is not given, the active object is created in the current JVM and is attached to a default Node.

A node is identified by a node URL which is formed using the protocol, the hostname hosting the JVM where is the node located and the name of the node. The NodeFactory allows to create or lookup nodes. The method newActive can take in parameter a nodeURL as a String or a Node object that points to an existing node. Here an example:

      a = (A) ProActive.newActive("example.A", params, "rmi://pluto.inria.fr/aNode");
  or
      Node node = NodeFactory.getNode("rmi://pluto.inria.fr/aNode");
      a = (A) ProActive.newActive("example.A", params, node);

The algorithms that decide for each phase what to do are the following (activity is the eventual object passed as a parameter to newActive or turnActive):

InitActive

if activity is non null and implements InitActive
  we invoke the method initActivity defined in the object activity
else if the class of the reified object implements InitActive
  we invoke the method initActivity of the reified object
else
  we don't do any initialization

RunActive

if activity is non null and implements RunActive
  we invoke the method runActivity defined in the object activity
else if the class of the reified object implements RunActive
  we invoke the method runActivity of the reified object
else
  we run the standard FIFO activity

EndActive

if activity is non null and implements EndActive
  we invoke the method endActivity defined in the object activity
else if the class of the reified object implements EndActive
  we invoke the method endActivity of the reified object
else
  we don't do any cleanup

Implementing the interfaces directly in the class used to create the active object is the easiest solution when you control the class that you make active. Depending on which phase in the life of the active object you want to customize, you implement the corresponding interface (one or more) amongst InitActive, RunActive and EndActive. Here is an example that has a custom initialization and activity.

  import org.objectweb.proactive.*;
  public class A implements InitActive, RunActive {
        private String myName;
         public String getName() {
         return myName;
        }
        // -- implements InitActive
        public void initActivity(Body body) {
        myName = body.getName();
        }
        // -- implements RunActive for serving request in a LIFO fashion
         public void runActivity(Body body) {
        Service service = new Service(Body);
        while (body.isActive()) {
         service.blockingServeYoungest();
        }
        }
        public static void main(String[] args) throws Exception {
        A a = (A) ProActive.newActive("A",null);
        System.out.println("Name = "+a.getName());
        }
  }

import org.objectweb.proactive.*;
public class Simulation implements RunActive {
      private boolean stoppedSimulation=false;
        private boolean startedSimulation=false
        private boolean suspendedSimulation=false;
        private boolean notStarted = true;
        public void startSimulation(){
        //Simulation starts
        notStarted = false;
        startedSimulation=true;
        }
        public void restartSimulation(){
        //Simulation is restarted
        startedSimulation=true;
        suspendedSimulation=false;
        }
        public void suspendSimulation(){
        //Simulation is suspended
        suspendedSimulation=true;
        startedSimulation = false;
        }
        public void stoppedSimulation(){
        //Simulation is stopped
        stoppedSimulation=true;
        }
        public void runActivity(Body body) {
         Service service = new Service(Body);
        while (body.isActive()) {
        //If the simulation is not yet started wait until startSimulation method
        if(notStarted) service.blockingServeOldest(startSimulation());
       // If the simulation is started serve request with FIFO
        if(startedSimulation) service.blockingServeOldest();
        // If simulation is suspended wait until restartSimulation method
        if(suspendedSimulation) service.blockingServeOldest(restartSimulation());
        // If simulation is stopped, exit
        if(stoppedSimulation) exit();
        }
}

public class BusyButReactive implements RunActive {
public void  runActivity(Body body) {
Service service = new Service(body);
while ( ! hasToTerminate ) {
        ...    // Do some activity on its own
        ...
        ...    // Non blocking service
        ...
        service.serveOldest("changeParameters", "terminate");   ... 
      }
    }
public void changeParameters () {...   // change computation parameters}
public void terminate (){ hasToTerminate=true;}
}

It also allows one to specify explicit termination of AOs (there is currently no Distributed Garbage Collector). Of course, the reactivity is up to the length of going around the loop.

Passing an object implementing the interfaces when creating the active object is the solution to use when you do not control the class that you make active or when you want to write generic activities policy and reused them with several active objects. Depending on which phase in the life of the active object you want to customize, you implement the corresponding interface (one or more) amongst InitActive, RunActive and EndActive. Following is an example that has a custom activity.

Comparing to the solution above where interfaces are directly implemented in the reified class, there is one restriction here: you cannot access the internal state of the reified object. Using an external object should therefore be used when the implementation of the activity is generic enough not to have to access the member variables of the reified object.

  import org.objectweb.proactive.*;
  public class LIFOActivity implements RunActive {
    // -- implements RunActive for serving request in a LIFO fashion
    public void runActivity(Body body) {
      Service service = new Service(Body);
      while (body.isActive()) {
        service.blockingServeYoungest();
      }
    }
  }
  import org.objectweb.proactive.*;
  public class A implements InitActive {
    private String myName;
    public String getName() {
      return myName;
    }
    // -- implements InitActive
    public void initActivity(Body body) {
      myName = body.getName();
    }
    public static void main(String[] args) throws Exception {
      // newActive(classname, constructor parameter (null = none), 
      //           node (null = local), active, MetaObjectFactory (null = default)
      A a = (A) ProActive.newActive("A", null, null, new LIFOActivity(), null);
      System.out.println("Name = "+a.getName());
    }
  }