Next: 5 The Satin Divide-and-Conquer Up: Ibis Programmer's Manual Previous: 3 An Ibis Application
Subsections

- 4.1 The Ibis Nameserver
- 4.2 Running an Ibis Application
- 4.3 Running the example

#
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 .
  `-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.

Next: 5 The Satin Divide-and-Conquer Up: Ibis Programmer's Manual Previous: 3 An Ibis Application