SPAWN(3PVM) PVM Version 3.4 SPAWN(3PVM)NAME
pvm_spawn - Starts new PVM processes.
SYNOPSIS
C int numt = pvm_spawn( char *task, char **argv, int flag,
char *where, int ntask, int *tids )
Fortran call pvmfspawn( task, flag, where, ntask, tids, numt )
PARAMETERS
task Character string which is the executable file name of the PVM
process to be started. The executable must already reside on
the host on which it is to be started. The name may be a file
in the PVM search path or an absolute path. The default PVM
search path is $HOME/pvm3/bin/$PVM_ARCH/ .
argv Pointer to an array of arguments to the executable (if sup‐
ported on the target machine), not including the executable
name, with the end of the array specified by NULL. argv[0] of
the spawned task is set to the executable path relative to the
PVM working directory (or absolute if an absolute filename was
specified). If the executable needs no arguments, then the
second argument to pvm_spawn is NULL.
flag Integer specifying spawn options.
In C, flag should be the sum of:
Option value MEANING
PvmTaskDefault 0 PVM can choose any machine to start task
PvmTaskHost 1 where specifies a particular host
PvmTaskArch 2 where specifies a type of architecture
PvmTaskDebug 4 Start up processes under debugger
PvmTaskTrace 8 Processes will generate PVM trace data. *
PvmMppFront 16 Start process on MPP front-end.
PvmHostCompl 32 Use complement host set
In Fortran, flag should be the sum of:
Option value MEANING
PVMDEFAULT 0 PVM can choose any machine to start task
PVMHOST 1 where specifies a particular host
PVMARCH 2 where specifies a type of architecture
PVMDEBUG 4 Start up processes under debugger
PVMTRACE 8 Processes will generate PVM trace data. *
* future extension
where Character string specifying where to start the PVM process.
Depending on the value of flag, where can be a host name such
as "ibm1.epm.ornl.gov" or a PVM architecture class such as
"SUN4". Also, the host name "." is taken as the localhost. If
flag is 0, then where is ignored when determining the target
host or architecture, and PVM will select the most appropriate
host.
The where argument can also be used to specify a custom working
directory for each given spawn command. This is done by
appending a ':' and the desired working directory path to the
where string, i.e.:
"ibm1.epm.ornl.gov:/home/user/project/foo"
PVM will temporarily change the working directory to spawn the
given task(s), and will then reset to the default working
directory after the spawn is executed. This option need not be
used in conjunction with either the PvmTaskHost or PvmTaskArch
flags, as the working directory path is stripped off prior to
parsing any host or architecture name. A valid specification
for where is therefore:
":/home/user/project/foo"
The working directory can be either an absolute path name or
can be relative to the current default working directory.
ntask Integer specifying the number of copies of the executable to
start.
tids Integer array of length ntask returning the tids of the PVM
processes started by this pvm_spawn call.
numt Integer returning the actual number of tasks started. Values
less than zero indicate a system error. A positive value less
than ntask indicates a partial failure. In this case the user
should check the tids array for the error code(s).
DESCRIPTION
The routine pvm_spawn starts ntask copies of the executable named task.
On systems that support environment, spawn passes selected variables
from parent environment to children tasks. If set, the envar
PVM_EXPORT is passed. If PVM_EXPORT contains other names (separated by
':') they will be passed too. This is useful for e.g.:
setenv DISPLAY myworkstation:0.0
setenv MYSTERYVAR 13
setenv PVM_EXPORT DISPLAY:MYSTERYVAR
The hosts on which the PVM processes are started are determined by the
flag and where arguments. On return the array tids contains the PVM
task identifiers for each process started.
If pvm_spawn starts one or more tasks, numt will be the actual number
of tasks started. If a system error occurs then numt will be < 0. If
numt is less than ntask then some executables have failed to start and
the user should check the last ntask - numt locations in the tids array
which will contain error codes (see below for meaning). The first numt
tids in the array are always valid.
When flag is set to 0 and where is set to NULL (or "*" in Fortran) a
heuristic (round-robin assignment) is used to distribute the ntask pro‐
cesses across the virtual machine.
If the PvmHostCompl flag is set, the resulting host set gets comple‐
mented. Given that the TaskHost host name "." is taken as localhost,
these can be used together, for example, to request n - 1 tasks on host
"." but with flags TaskHost|HostCompl to spawn n - 1 tasks on hosts
other than the localhost.
In the special case where a multiprocessor is specified by where,
pvm_spawn will start all ntask copies on this single machine using the
vendor's underlying routines.
The spawned task will have argv[0] set to the the executable path rela‐
tive to its inherited working directory (or possibly an absolute path),
so the base filename can be got by using:
char *p;
p = (p = rindex(argv[0], '/')) ? p + 1 : argv[0];
If PvmTaskDebug is set, then the pvmd will start the task(s) under
debugger(s). In this case, instead of executing pvm3/bin/ARCH/task args
it executes pvm3/lib/debugger pvm3/bin/ARCH/task args. debugger is a
shell script that the users can modify to their individual tastes.
Presently the script starts an xterm with dbx or comparable debugger in
it.
EXAMPLES
C:
numt = pvm_spawn( "host", 0, PvmTaskHost, "sparky", 1, &tid[0] );
numt = pvm_spawn( "host", 0, (PvmTaskHost+PvmTaskDebug),
"sparky", 1, &tid[0] );
numt = pvm_spawn( "node", 0, PvmTaskArch, "RIOS", 1, &tid[i] );
char *args[] = { "12", "60" , (char*)0 };
numt = pvm_spawn( "FEM1", args, 0, 0, 16, tids );
numt = pvm_spawn( "pde", 0, PvmTaskHost, "paragon.ornl", 512, tids );
Fortran:
FLAG = PVMARCH + PVMDEBUG
CALL PVMFSPAWN( 'node', FLAG, 'SUN4', 1, TID(3), NUMT )
CALL PVMFSPAWN( 'FEM1', PVMDEFAULT, '*', 16, TIDS, NUMT )
CALL PVMFSPAWN( 'TBMD', PVMHOST, 'cm5.utk.edu', 32, TIDS, NUMT )
ERRORS
These error conditions can be returned by pvm_spawn either in numt or
in the tids array.
PvmBadParam
giving an invalid argument value.
PvmNoHost
Specified host is not in the virtual machine.
PvmNoFile
Specified executable cannot be found. The default location PVM
looks in is ~/pvm3/bin/ARCH, where ARCH is a PVM architecture
name.
PvmNoMem
Malloc failed. Not enough memory on host.
PvmSysErr
pvmd not responding.
PvmOutOfRes
out of resources.
SEE ALSOpvm_export(3PVM)
30 August, 1993 SPAWN(3PVM)
