ProActive Example Applications

The C3D application uses three scripts that can be found under examples/c3d:

To use the application first start the dispatcher using either c3d_one_user.sh/bat or c3d_no_user.sh/bat and then add users with c3d_add_user.sh/bat

To start the application use examples/readers.

ProActive starts a node (i.e. a JVM) on the current machine, and creates 3 Writers, 3 Readers, a ReaderWrite (the controller of the application), and a ReaderDisplay, all of which are active objects.

The examples has three synchronization modes "Priority to Writers", "Priority to Readers", and "Even Policy". The application is able to assign different priority to readers or writers without blocking on reading or writing.

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

To start the application use examples/philosophers/philosophers.sh or examples\philosophers\philosophers.bat depending on your operating system.

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

Figure 5.3. The Dining Philosophers Example

The pictures represent the state of the philosophers. They can be:

The forks can have two states:

You can either run the application in autopilot mode running it by itself without encountering a deadlock or in manual mode where you click on the philosophers' heads to switch their modes. You can starve one of the philosophers. (i.e. the others alternate eating and thinking while one never eats!)

Use the examples/penguin/penguin.sh script to start the penguin controller. The controller allows you to add a new agent (penguin), and control its itinerary.

The active object is moving between the machines (specified in the deployment descriptor) , and that the penguin window disappears and reappears on the screen associated with the new JVM.

After selecting them, use the buttons to:

To start a chat client run chat.sh or chat.bat from the examples/chat/folder. The syntax is chat.sh|bat user_name host_to_connect_to user_to_connect_to .

When you start the first client the last argument can have any value. However if you want to connect to another chat you have to supply a valid user name and host. The communication is not dependent on any particular user. The first user that created the chat can leave and the other users can still communicate.

Start the first user by running chat.sh|bat toto localhost no_user . The following window appears.

To connect the user tutu run chat.sh|bat tutu localhost toto .

You can further connect other users in the same manner. Run chat.sh|bat tata localhost tutu . You can connect to any user in the chat and you will have access to all the users.

The chat application can be migrated to another computer. All we have to do to fully migrate one chat is start a node on the remote computer using startNode.sh or startNode.bat from the scripts folder. We have to use a parameter in the form of rmi://hostname/node_name to start the node. After starting the node we can migrate the chat application by putting the URL //hostname/node_name in the migrate to textbox and clicking on the Migrate button. The application will be recreated on the remote computer with its state intact and ready to communicate to the other users.

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 :

In examples/integralPi run integralpi.sh or .bat, you can specify the number of workers from the command line. Feel free to edit scripts to specify another deployment descriptor.

bash-3.00$ ./integralpi.sh

--- IntegralPi --------------------------------------------------
The number of workers is 4
 --> This ClassFileServer is reading resources from classpath 2011
Created a new registry on port 1099
ProActive Security Policy (proactive.runtime.security) not set. Runtime Security disabled
************* Reading deployment descriptor: file:./../../descriptors/Matrix.xml ********************
created VirtualNode name=matrixNode
**** Starting jvm on amda.inria.fr
**** Starting jvm on amda.inria.fr
**** Starting jvm on amda.inria.fr
ProActive Security Policy (proactive.runtime.security) not set. Runtime Security disabled
 --> This ClassFileServer is reading resources from classpath 2012
ProActive Security Policy (proactive.runtime.security) not set. Runtime Security disabled
ProActive Security Policy (proactive.runtime.security) not set. Runtime Security disabled
 --> This ClassFileServer is reading resources from classpath 2013
 --> This ClassFileServer is reading resources from classpath 2014
**** Starting jvm on amda.inria.fr
Detected an existing RMI Registry on port 1099
Detected an existing RMI Registry on port 1099
Detected an existing RMI Registry on port 1099
ProActive Security Policy (proactive.runtime.security) not set. Runtime Security disabled
 --> This ClassFileServer is reading resources from classpath 2015
//amda.inria.fr/matrixNode2048238867 successfully bound in registry at //amda.inria.fr/matrixNode2048238867
**** Mapping VirtualNode matrixNode with Node: //amda.inria.fr/matrixNode2048238867 done
//amda.inria.fr/matrixNode690267632 successfully bound in registry at //amda.inria.fr/matrixNode690267632
**** Mapping VirtualNode matrixNode with Node: //amda.inria.fr/matrixNode690267632 done
//amda.inria.fr/matrixNode1157915128 successfully bound in registry at //amda.inria.fr/matrixNode1157915128
**** Mapping VirtualNode matrixNode with Node: //amda.inria.fr/matrixNode1157915128 done
Detected an existing RMI Registry on port 1099
//amda.inria.fr/matrixNode-814241328 successfully bound in registry at //amda.inria.fr/matrixNode-814241328
**** Mapping VirtualNode matrixNode with Node: //amda.inria.fr/matrixNode-814241328 done
4 nodes found
Generating class : pa.stub.org.objectweb.proactive.examples.integralpi.Stub_Worker

Enter the number of iterations (0 to exit) : 100000
Generating class : pa.stub.org.objectweb.proactive.examples.integralpi.Stub_Worker
Generating class : pa.stub.org.objectweb.proactive.examples.integralpi.Stub_Worker
Generating class : pa.stub.org.objectweb.proactive.examples.integralpi.Stub_Worker
Generating class : pa.stub.org.objectweb.proactive.examples.integralpi.Stub_Worker

         Worker 2 Calculated x = 0.7853956634245252 in 43 ms


         Worker 3 Calculated x = 0.7853906633745299 in 30 ms


         Worker 1 Calculated x = 0.7854006634245316 in 99 ms


         Worker 0 Calculated x = 3.141592653598117 in 12 ms


Calculated PI is 3.141592653598117 error is 8.324008149429574E-12

Enter the number of iterations (0 to exit) :  

With the 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 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. 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.

This is a snapshot of the ProActive n-body example running on 3 hosts with 8 bodies:

n-body screenshot, with the application GUI and Java3D installed:

Add wrappers around the original object classes (C3D*) and instead of linking the classes together by setting fields through the initial methods, do that in the binding methods. In other words, we have to spot exactly where C3DRenderingEngine, C3DUser and C3DDispatcher are used by a class other than itself, and turn these references into component bindings. Of course, we also have to expose the interfaces that we are going to use, hence the Dispatcher, Engine and User interface that have to be implemented.

Figure 5.4.  Informal description of the C3D Components hierarchy

First of all, have a look at the doc on C3D to remember how this application is written, in Section 5.1, “C3D: A distributed 3D renderer” . Most important is the class diagram, showing C3DUser, C3DDispatcher and C3DRederingEngine. We decided that the only objects worth wrapping in components were those three. The rest is too small to be worth the hassle.

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.

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:

The component Registration

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

The Component lookup

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.

There is only one access point for this example in the scripts directory:

examples/c3d$ ./c3d_component.sh
--- Fractal C3D example ---------------------------------------------
Parameters : descriptor_file [fractal_ADL_file]
        The first file describes your deployment of computing nodes.
                You may want to try ../../../descriptors/components/C3D_all.xml
        The second file describes your components layout.
                Default is org.objectweb.proactive.examples.components.c3d.adl.userAndComposite
---------------------------------------------------------

There are two ways to start the components C3D. If you only want to start the Composite (Dispatcher + Renderer):

examples/c3d$ ./c3d_component.sh \
../../../descriptors/components/C3D_all.xml \
org.objectweb.proactive.examples.components.c3d.adl.compositeOfDispRend

If you want to start only a User, you will be asked for the address of a Dispatcher to which to connect to:

examples/c3d$ ./c3d_component.sh \
../../../descriptors/components/C3D_all.xml \
org.objectweb.proactive.examples.components.c3d.adl.UserImpl

These are a few of the examples present in the ProActive distribution. To see a full list of the examples go to the application web page.