4 Compiling and Running an Ibis Application

Before running an Ibis application it must be compiled. Using ant, this is quite easy. Assuming that the environment variable IBIS_ROOT reflects the location of your Ibis installation, here is a build.xml file for our example program:

<project
    name="client-server"
    default="build"
    basedir=".">

    <description>
    Ibis application build.
    </description>

    <property environment="env" />
    <property name="ibis"   value="${env.IBIS_ROOT}" />

    <property name="build"  location="build"/>

    <import file="${ibis}/build-files/apps/build-ibis-app.xml"/>
</project>

Now, invoking ant compiles the application, leaving the class files in a directory called build. Please note that you must use the ant that is distributed with ibis (in the Ibis root directory), because this version provides some tasks to compile Ibis applications.

4.1 The Ibis Nameserver

Most Ibis implementations depend on a nameserver for providing information about a particular run, such as finding Ibis instances participating in the run, finding or registering receive ports, et cetera. The Ibis nameserver collects this information for multiple Ibis runs, even simultaneous ones. It does so by associating a user-supplied identifier with each Ibis run. Each Ibis instance announces its presence to the nameserver, using this identifier, so that the nameserver can determine to which Ibis run this Ibis instance belongs. The nameserver then notifies the other Ibis instances of this run that a new instance has joined the run, including some identification of this instance.

If you tell Ibis that the nameserver location is a machine that also participates in the run itself, Ibis will automatically try to start a nameserver. How you can specify this is explained in the next section. If you want to run the nameserver on a seperate host, one that is not behind a firewall, for instance, you have to start the nameserver by hand.

The Ibis nameserver is started with the ibis-nameserver script which lives in the Ibis bin directory. Before starting an Ibis application, you need to have a nameserver running on a machine that is accessible from all nodes participating in the Ibis run. The nameserver expects the Ibis instances to connect to a socket that it creates when it starts up. The port number of this socket can be specified using a command line option to the ibis-nameserver script. This script recognizes the following options:

-single specifies that the nameserver should only serve a single Ibis run and then exit.

-port portno specifies the port number of the nameserver socket. A port number must be between 0 and 65535, inclusive. Usually, port numbers below 1024 are reserved for other purposes.

-poolport poolportno specifies the port number of the PoolInfoServer mentioned in Section 3.8.1.

4.2 Running an Ibis Application

An Ibis instance is started with the ibis-run script which lives in the Ibis bin directory. This ibis-run script is called as follows:

ibis-run ibis-run-flags java-flags class params

The most important ibis-run-flags are explained below:

-nhosts nhosts specifies the total number of Ibis instances involved in this run.

-hostno hostno specifies the rank number of this Ibis instance within this run, so its range is $0 ... \emph{nhosts}-1$.

-key id specifies the identifier used to identify the run to the nameserver.

-ns nameserverhost specifies the hostname of the machine where the Ibis nameserver runs. If the hostname refers to a machine that also participates in the run, Ibis will start the nameserver itself.

-ns-port port specifies the port number on which the nameserver is listening.

-? gives a description of all options.

javaflags are any flags that need to be passed on to java.

class specifies the application class name.

params specifies the optional application parameters.

The ibis-run script uses these parameters to set the following system properties (see also Section 3.8.1):

ibis.pool.host_number the rank number of this Ibis instance.

ibis.pool.total_hosts the total number of Ibis instances.

ibis.name_server.key identifies the run to the nameserver.

ibis.name_server.port the nameserver port.

ibis.name_server.host the nameserver hostname.

In addition, the following system properties can be specified (as javaflags):

ibis.pool.cluster specifies a cluster name. If not specified, ``unknown'' is used. See Section 5.3 for a possible need for cluster names.

ibis.pool.server.port specifies the port number on which the PoolInfoServer is listening.

The Ibis distribution also provides grun, which is a tool for running Ibis applications on a Globus-based grid. See the grun/doc subdirectory for more information.

4.3 Running the example

In order to run the example, we first have to compile it. Please go to the ibis-example directory and type:

$ ../ant

After a couple of seconds, the example should be compiled. You can run the example both with and without the ibis-run script. Because we run the example on a single machine, we do not need to start a seperate nameserver. To run the application, we first need to start two shells. Then, in both shells type:

$ $IBIS_ROOT/bin/ibis-run \
    -nhosts 2 -ns localhost Example

Now, it should run and print:

Test succeeded!

If you don't use the ibis-run script, you have to set several properties. In both shells, type:

$ java \
    -cp $IBIS_ROOT/build/ibis.jar:$IBIS_ROOT/3rdparty/log4j-1.2.9.jar:build \
    -Dibis.pool.total_hosts=2 -Dibis.name_server.host=localhost \
    -Dibis.name_server.key=bla \
    Example

The ibis.name_server.key value can be any random string. It identifies your run. This is done because one nameserver can serve multiple runs. For this test, we need to provide Ibis with the total number of CPUs in the run, because it is a closed-world test. Ibis waits until both processors have joined the computation. The ibis.name_server.host property should be set to the machine you run the nameserver on. In this case, we use localhost. Because we also run the application on localhost, Ibis will automatically start a nameserver. If you provide a hostname where the Ibis application does not run, you will have to start a nameserver yourself.