Compiling and Invoking TOP-C Applications

A `TOP-C' application can be compiled once, and then linked to your choice of a run-time library for either a sequential, distributed memory or shared memory architecture. The two shell scripts `bin/topcc' and `bin/topc++' are used instead of `gcc' and `g++' (or other C/C++ compilers).

Compiling TOP-C Applications

The TOP-C application file must contain

    #include <topc.h>

It must make calls to

    TOPC_init(...);
    TOPC_master_slave(...);
    TOPC_finalize();

as describe in the section, section Structure of a TOP-C Program. The application file is compiled by one of:

    topcc -seq myfile.c
    topcc -mpi myfile.c
    topcc -pthread myfile.c

according to whether the target computer architecture will be sequential (`-seq': single processor), distributed memory (`-mpi': networked CPU's), or shared memory (`-pthread': SMP or other shared memory architecture with a POSIX threads interface). topcc is a substitute for cc or gcc, and creates an `a.out' file. (Similarly, topc++ exists as a substitute for c++ or g++.) There is a man file,

    `doc/topcc.1'

with further information on topcc and topc++.

The same object file may be relinked to use different `TOP-C' memory models without recompiling the object file.

    topcc -c myapp.c
    topcc -seq -o myapp-seq myapp.o
    topcc -mpi -o myapp-mpi myapp.o

For the rest of this chapter, we standardize our description for topcc. However, topc++ is equally valid wherever topcc is mentioned.

Invoking a TOP-C Application in Sequential Memory

For example,

    topcc -seq -g myfile.c

compiles a sequential version for debugging using gdb (see section `Summary' in The GNU debugger), for example. This is usually a first step in debugging a TOP-C application, since sequential debugging is easier than parallel debugging.

Invoking a TOP-C Application in Distributed Memory

Linking using the `-mpi' option (default) allows an application to execute using a distributed memory model of networked processors. The `TOP-C' distribution includes a subset MPI implementation `mpinu'(1)}, sufficient to run `TOP-C' applications.

  topcc -mpi myapp.c
  # procgroup file exists in current directory
  ./a.out

When the binary is executed, it looks at the current directory for a file,

    `procgroup'

The procgroup file determines the number and location of the slave processes. If one prefers, one can specify an alternate procgroup file via the syntax as in the following example:

    ./a.out -p4pg ../myprocgroup.big

The `TOP-C' distribution includes a file `bin/procgroup' as an example of the procgroup format. The file must contain a line:

    local 0

for the master process. It must also contain a line for each slave process of the form:

    hostname 1 full_pathname

where hostname is the remote host. The value localhost is recommended for debugging. The full_pathname is the pathname of a binary on the remote host. In a shared file system, this will typically be the same as the pathname of the local binary, but it can be a different binary, allowing for heterogeneous computing. The environment variable,

    RSH

(default rsh) is used to invoke the remote host. It is sometimes useful to modify this environment variable to get around firewalls.

If the slave processes fail to start up or fail to respond to the master, one other debugging resource is available. If an application fails to start up, then `TOP-C' leaves the `/tmp' directory a file

    `/tmp/mpinu-rsh.$$'

where $$ is the process id. The file shows the commands that `TOP-C/mpinu' tried to use to start up the slave process. By examing and even manually executing those commands from the terminal, one can often deduce the difficulty in creating the slave processes.

Invoking a TOP-C Application in Shared Memory

Linking using the `-pthread' option (POSIX threads) allows an application to execute using a distributed memory model of networked processors. The `TOP-C' distribution includes a subset MPI implementation `mpinu'(2)}, sufficient to run `TOP-C' applications.

  topcc -pthread myapp.c
  ./a.out

Note that the `TOP-C' memory model for shared memory has some small variations from the distributed memory model. See section Modifying TOP-C Code for the Shared Memory Model, for details. Check your source code to see if this affects you.

While a `TOP-C' application object file can usually be linked using an arbitrary `TOP-C' memory model without recompiling, there are some circumstances where you may first need to recompile the application source using topcc -pthread.

Go to the first, previous, next, last section, table of contents.