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 supported 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 processes across the virtual machine.
If the PvmHostCompl flag is set, the resulting host set gets complemented. 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
relative 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 ALSO¶
pvm_export(3PVM)