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).
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 files,
`doc/topcc.1'
with further information on topcc
and topc++
.
If installed, man topcc
and man topc++
exist.
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 large applications, it may be preferable to directly invoke
the `TOP-C' libraries and include files. For such
situations, topc-config
exists. The following
is exactly equivalent to topcc --mpi myfile.c
(assuming you configured `TOP-C' using `gcc'..
gcc `topc-config --cflags` --mpi myfile.c `topc-config --libs`
Type topc-config
with no arguments for a full set of
command line options.
For the rest of this chapter, we standardize our description for
topcc
. However, topc++
is equally valid wherever
topcc
is mentioned.
For a brief synopsis of application command line parameters, type:
topcc myapp.c ./a.out --TOPC_help
Currently, this will display the following.
Usage: ./a.out [TOPC_OPTION ...] [OTHER_OPTIONS ...] where TOPC_OPTION is one of: --TOPC_help display this message [default: false] --TOPC_verbose=<int>] [0..2]: verbose mode [default: false] --TOPC_num_slaves=<int> number of slaves (sys-defined default) [default: -1] --TOPC_slave_wait=<int> secs before slave starts (use w/ gdb attach) [default: 0] --TOPC_slave_timeout=<int> dist mem: secs to die if no msgs, 0=never [default: 3600] --TOPC_trace=<int> trace (0: notrace, 1: trace, 2: user trace fncs.) [default: 2] --TOPC_procgroup=<string> procgroup file (--mpi) [default: "./procgroup"] --TOPC_topc_log=<string> NOT IMPL: log file for TOPC output ("-" = stdout) [default: "-"] --TOPC_safety=<int> [0..20]: higher turns off optimizations, see --TOPC_verbose [default: 0]
For each parameter, --TOPC_PARAM
, there is a corresponding
C/C++ variable, TOPC_OPT_PARAM
. This variable is of type
int
or char *
. If the application program sets the value
before a call to TOPC_init()
, these variables will act as
defaults. For example, to turn off tracing by default, write:
int main( int argc, char *argv[] ) { TOPC_OPT_trace = 0; TOPC_init( &argc, &argv ); ... }
For the usage of --TOPC_procgroup
,
see section Invoking a TOP-C Application in Distributed Memory.
That section also explains on what hosts the slaves run
when --TOPC_num_slaves
indicates a different number of
slaves than the `procgroup' file.
For the usage of --TOPC_slave_wait
, see
section Stepping Through a Slave Process with `gdb'.
For the usage of --TOPC_safety
, see
`TOP-C' recognizes --
as terminating all option processing,
according to standard UNIX conventions.
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.
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(1)} implementation `mpinu', sufficient to run `TOP-C' applications.
topcc --mpi myapp.c # procgroup file exists in current directory ./a.out
The application must then create the remote slave processes at runtime. Assuming you used the default configuration, `mpinu' is built into the `TOP-C' library and uses the `procgroup' mechanism to specify slave processes. (If you prefer to use a different `MPI' dialect, `TOP-C' will work, but `src/Makefile.in' must be modified, and that `MPI' dialect may use a different mechanism for introducing slave processes.
When the application binary is executed under the default, 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 --TOPC_procgroup=../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 pathname -
means to use the same pathname for the slave
on the remote host as for the master on the current host.
A relative pathname, such as ./a.out
or ../new_arch/a.out
,
specifies a pathname relative to the pathname of the binary of
the master on the current host. (This code assumes that your
application does not change the working directory before
calling TOPC_init()
.)
Note that if you execute
an application, /project/sparc/app
, `TOP-C' will by
default use the procgroup file in the current directory, ./
,
but will construct relative pathnames in the procgroup file
relative to the directory, /project
. This is useful
for maintaining binaries, /project/linux/app
,
/project/alpha/app
, etc., and referring to them
in the procgroup as ../linux/app
, etc.
You can also choose an explicit procgroup file via
a call, such as
/project/sparc/app --TOPC_procgroup=/project/myprocgroup
.
See section Command Line Parameters in TOP-C Applications.
If the command-line-parameter --TOPC_num_slaves=int
is given, and if int is less than the number of
slaves in the procgroup
file, then `TOP-C' will
use the first int slaves from the file. If int
is more than the number of slaves in the procgroup
file,
then `TOP-C' will use all of the given slaves, and then
create additional processes on the remote hosts, by
returning to the beginning of the procgroup
file and
re-reading the list of slave host/binaries until int
slaves have been created in all.
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
examining and even manually executing those commands from the terminal,
one can often deduce the difficulty in creating the slave processes.
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(2)} implementation `mpinu', 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 Optimizing 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.