2.1.3 Assembling and Running an Application Using the GUI

For the purposes of this exercise, we will assume that you are working in and environment in which GUI host and Ccaffeine host are separate machines. If they are the same, you can use $TUTORIAL_SRC/utils/run-gui.sh as described in Section 2.1.1 instead of the first two steps, below.

1. Run  $TUTORIAL_SRC/utils/bocca-gui-backend.sh --port port_num on the Ccaffeine host using the appropriate port.

   In the Ccaffeine host terminal window, you will see something like:

   my rank: -1, my pid: 9625
   Type: Server
   

2. Run  simple-gui.sh --port port_num --host backend_host (on Windows,  simple-gui.bat) on the GUI host .

   Once the GUI connects to Ccaffeine , Ccaffeine begins running the rc file it was invoked with. In the GUI host terminal window, you first see some startup messages from the GUI itself, followed by a series of messages as Ccaffeine processes the rc file and the GUI displays the results. These are debugging messages and can largely be ignored.

   In the Ccaffeine host terminal, you should see some additional messages as Ccaffeine processes the rc file, like:

   CCAFFEINE configured with spec (0.8.2) and babel (1.0.4).
   
   CCAFFEINE configured with classic (0.5.7).
   
   CCAFFEINE configured without neo and neo components.
   CmdLineClient parsing ...
   
   CmdContextCCA::initRC: Found components/tests/test_gui_rc.
   # There are allegedly 11 classes in the component path
   

   Finally, in the GUI host window, you should see some output associated with the GUI's initialization process, and the GUI itself should have appeared on your display, looking something Figure 2.1.

   Figure 2.1: GUI with components in palette and empty arena (Step 2).

   

   Tip The default layout has the palette area fairly narrow. You can click-and-drag on the bar separating the palette and the arena to adjust the width.

   Note You may see additional components in your palette , as we try to expand the variety of examples we provide in the tutorial-src .

   As mentioned above, the test_gui_rc sets up the path and loads the framework's palette with a set of available components. rc files are explained in detail in Section 2.2.

3. We will begin by instantiating a drivers.CXXDriver component. Click-and-drag the component you want from the palette to the arena . When you release the mouse button in the arena , a dialog box will pop up prompting you to name this instance of the component. The default will be the last part of the component's class name (i.e. CXXDriver for drivers.CXXDriver ) with a numerical suffix to insure the name is unique. The suffix starts at 0 and simply counts up according to the number of instances of that component you've created in that session. You can, of course, enter any instance name you like, as long as it is unique across all components in the arena , but for simplicity, we will always accept the default value in this Guide.

4. For the first application, follow the same procedure to instantiate:
   • drivers.CXXDriver ,
   • functions.PiFunction ,
   • integrators.MonteCarlo ,
   • randomgens.RandNumGenerator ,
   (you may notice some debugging messages in the GUI host terminal window as you do this), and your GUI should look something like Figure 2.2.

   Figure 2.2: GUI with several components instantiated in arena (Step 4).

   

   Tip You can drag components around the arena to arrange them as suits you - just click on the black area of the component and drag it to the new location. The positions have no bearing on the operation of the GUI or your application.

5. The next step is to begin making connections between the ports of your components. Click-and-release CXXDriver0 's integrate uses port, then click-and-release MonteCarlo0 's integrate provides port and a red line should be drawn between the two (Figure 2.3).

   Figure 2.3: Driver's integrator port connected to integrator's integrator port (Step 5).

   

   Tip If you hover the cursor over a particular port on a component, a ``tool tip'' box will pop up with the port's name and type based on the arguments to the addProvidesPort or registerUsesPort calls in the component's setServices method. This can be useful for double checking to make sure you're connecting matching ports. Also notice that when you hover over a particular port (either uses or provides ), matching ports of the opposite type (either provides or uses ) will be highlighted.

   Note You can move components around even after their ports are connected - the connections will automatically rearrange. There is no harm in connections crossing each other, nor in connections passing behind other components (though of course they may make it harder to interpret the ``wiring diagram'' correctly).

6. Complete the first application by making the following connections:
   • CXXDriver0 's integrate to MonteCarlo0 's integrate

   • MonteCarlo0 's function to PiFunction0 's function

   • MonteCarlo0 's RandomGeneratorPort to RandNumGenerator0 's
     RandomGeneratorPort .

   At this point, your GUI should look something like Figure 2.4.

   Figure 2.4: Fully connected application (Step 6).

   

7. The application is now fully assembled and is ready to run. If you click-and-release the go button on the CXXDriver0 component, you should see the result appear in the Ccaffeine host terminal, ``Value = 3.139160''^2.2 and the message

   ``IN: ##specific go command successful'' in the GUI host terminal.

   Tip Remember that your application is running within the framework. Unless the application itself does something special, the output from the application will appear in the window in which the framework is running.

8. Next, we're going to use some of the other components to assemble a different application using the
   • integrators.Simpson and
   • functions.CubeFunction
   components. Since they're already in the palette , you can instantiate them in the same way as Step 3. Your GUI should look like Figure 2.5.

   Figure 2.5: Additional components instantiated (Step 8).

   

   Tip As we've mentioned, wiring diagrams can become hard to interpret when they become cluttered, as is the case with the screen shot above. To help interpret the diagram, remember the following: ``Wires'' only connect to the sides of ports - on the left side of provides ports (on the left side of the component), or on the right side of uses ports. Connections are never made to the top or bottom of a component. The GUI's wire-drawing algorithm is aware only of the two components that are being connected. It will make no attempt to avoid other components or other wires. So wires can pass behind components without connecting to any of their ports, and wires may overlap. If you're still uncertain how to interpret the connections try rearranging the components slightly. Connections attached to the component will follow as you drag it around, but others not associated with that component will remain unchanged.

9. Next, we break the port connections we don't need so we can reconnect to the new components. Right-click on the integrate (either the user or the provider ) and a dialog box will pop up asking you to confirm that you want to break the connection.^2.3 You will need to break the following connections:
   • CXXDriver0 's integrate to MonteCarlo0 's integrate

   • MonteCarlo0 's function to PiFunction0 's function

   There is no need to remove unused components from the arena - as long as they are not connected to active components, they will not interfere.^2.4 In fact in this case, neither MonteCarlo0 nor RandNumGenerator0 are used, so it is safe to leave them connected to each other.

   Note Steps 8 and 9 could have been done in either order.

10. Assemble the new application (Figure 2.6) by making the following connections:
    • CXXDriver0 's integrate to Simpson0 's integrate

    • Simpson0 's function to PiFunction0 's function

    Figure 2.6: Another application, with additional unused components still in arena (Step 10).

    

    Click-and-release the go button on the CXXDriver0 component, you should see the result appear in the Ccaffeine host terminal, ``Value = 3.141593'' and the message ``IN: ##specific go command successful'' in the GUI host terminal.

11. Finally, create a third application by replacing PiFunction0 with CubeFunction0 (Figure 2.7). When you click on the go you should get ``Value = 0.250000''^2.5 in the Ccaffeine host terminal.

    Figure 2.7: A third application, with extraneous components still in arena (Step 11).

    

12. At this point, you should understand how to instantiate components, how to connect and disconnect their ports, and how to execute the application with the go port. Feel free to use any and all of the components available in the palette to experiment with other integration applications.

    Note Observe that as a user of CCA components, you have no idea what language each component is implemented in. (Admittedly, the names of the drivers are suggestive of the implementation language, but those names were chosen at the convenience of the component developer, and they provide no guarantees regarding the components' implementations.) The language interoperability features of Babel allow components to be hooked together regardless of implementation language with complete transparency.

13. To politely exit the GUI, select File $\Rightarrow$ Quit. This will terminate both the GUI and the backend ccafe-client sessions.

    Tip If you've used the GUI to setup and start a long-running simulation, and you don't want to leave the GUI running continuously, you can use the File $\Rightarrow$ Detach option to close the GUI but leave the backend running. However it is currently impossible to reattach to a running session.

    Tip If the backend crashes while the GUI is running, exit the GUI by using Detach. Trying to Quit without a running backend will cause the GUI to hang.