1SPAWN(3PVM) PVM Version 3.4 SPAWN(3PVM)
2
6 pvm_spawn - Starts new PVM processes.
7
10 C int numt = pvm_spawn( char *task, char **argv, int flag,
11 char *where, int ntask, int *tids )
12 Fortran call pvmfspawn( task, flag, where, ntask, tids, numt )
14
17 task Character string which is the executable file name of the PVM
18 process to be started. The executable must already reside on
19 the host on which it is to be started. The name may be a file
20 in the PVM search path or an absolute path. The default PVM
21 search path is $HOME/pvm3/bin/$PVM_ARCH/ .
22 argv Pointer to an array of arguments to the executable (if sup‐
24 ported on the target machine), not including the executable
25 name, with the end of the array specified by NULL. argv[0] of
26 the spawned task is set to the executable path relative to the
27 PVM working directory (or absolute if an absolute filename was
28 specified). If the executable needs no arguments, then the
29 second argument to pvm_spawn is NULL.
30 flag Integer specifying spawn options.
32 In C, flag should be the sum of:
34 Option value MEANING
35 PvmTaskDefault 0 PVM can choose any machine to start task
36 PvmTaskHost 1 where specifies a particular host
37 PvmTaskArch 2 where specifies a type of architecture
38 PvmTaskDebug 4 Start up processes under debugger
39 PvmTaskTrace 8 Processes will generate PVM trace data. *
40 PvmMppFront 16 Start process on MPP front-end.
41 PvmHostCompl 32 Use complement host set
42 In Fortran, flag should be the sum of:
44 Option value MEANING
45 PVMDEFAULT 0 PVM can choose any machine to start task
46 PVMHOST 1 where specifies a particular host
47 PVMARCH 2 where specifies a type of architecture
48 PVMDEBUG 4 Start up processes under debugger
49 PVMTRACE 8 Processes will generate PVM trace data. *
50 * future extension
52 where Character string specifying where to start the PVM process.
55 Depending on the value of flag, where can be a host name such
56 as "ibm1.epm.ornl.gov" or a PVM architecture class such as
57 "SUN4". Also, the host name "." is taken as the localhost. If
58 flag is 0, then where is ignored when determining the target
59 host or architecture, and PVM will select the most appropriate
60 host.
61 The where argument can also be used to specify a custom working
63 directory for each given spawn command. This is done by
64 appending a ':' and the desired working directory path to the
65 where string, i.e.:
66 "ibm1.epm.ornl.gov:/home/user/project/foo"
68 PVM will temporarily change the working directory to spawn the
70 given task(s), and will then reset to the default working
71 directory after the spawn is executed. This option need not be
72 used in conjunction with either the PvmTaskHost or PvmTaskArch
73 flags, as the working directory path is stripped off prior to
74 parsing any host or architecture name. A valid specification
75 for where is therefore:
76 ":/home/user/project/foo"
78 The working directory can be either an absolute path name or
80 can be relative to the current default working directory.
81 ntask Integer specifying the number of copies of the executable to
83 start.
84 tids Integer array of length ntask returning the tids of the PVM
86 processes started by this pvm_spawn call.
87 numt Integer returning the actual number of tasks started. Values
89 less than zero indicate a system error. A positive value less
90 than ntask indicates a partial failure. In this case the user
91 should check the tids array for the error code(s).
92
95 The routine pvm_spawn starts ntask copies of the executable named task.
96 On systems that support environment, spawn passes selected variables
97 from parent environment to children tasks. If set, the envar
98 PVM_EXPORT is passed. If PVM_EXPORT contains other names (separated by
99 ':') they will be passed too. This is useful for e.g.:
100 setenv DISPLAY myworkstation:0.0
102 setenv MYSTERYVAR 13
103 setenv PVM_EXPORT DISPLAY:MYSTERYVAR
104 The hosts on which the PVM processes are started are determined by the
106 flag and where arguments. On return the array tids contains the PVM
107 task identifiers for each process started.
108 If pvm_spawn starts one or more tasks, numt will be the actual number
110 of tasks started. If a system error occurs then numt will be < 0. If
111 numt is less than ntask then some executables have failed to start and
112 the user should check the last ntask - numt locations in the tids array
113 which will contain error codes (see below for meaning). The first numt
114 tids in the array are always valid.
115 When flag is set to 0 and where is set to NULL (or "*" in Fortran) a
117 heuristic (round-robin assignment) is used to distribute the ntask pro‐
118 cesses across the virtual machine.
119 If the PvmHostCompl flag is set, the resulting host set gets comple‐
121 mented. Given that the TaskHost host name "." is taken as localhost,
122 these can be used together, for example, to request n - 1 tasks on host
123 "." but with flags TaskHost|HostCompl to spawn n - 1 tasks on hosts
124 other than the localhost.
125 In the special case where a multiprocessor is specified by where,
127 pvm_spawn will start all ntask copies on this single machine using the
128 vendor's underlying routines.
129 The spawned task will have argv[0] set to the the executable path rela‐
131 tive to its inherited working directory (or possibly an absolute path),
132 so the base filename can be got by using:
133 char *p;
134 p = (p = rindex(argv[0], '/')) ? p + 1 : argv[0];
135 If PvmTaskDebug is set, then the pvmd will start the task(s) under
137 debugger(s). In this case, instead of executing pvm3/bin/ARCH/task args
138 it executes pvm3/lib/debugger pvm3/bin/ARCH/task args. debugger is a
139 shell script that the users can modify to their individual tastes.
140 Presently the script starts an xterm with dbx or comparable debugger in
141 it.
142
145 C:
146 numt = pvm_spawn( "host", 0, PvmTaskHost, "sparky", 1, &tid[0] );
147 numt = pvm_spawn( "host", 0, (PvmTaskHost+PvmTaskDebug),
148 "sparky", 1, &tid[0] );
149 numt = pvm_spawn( "node", 0, PvmTaskArch, "RIOS", 1, &tid[i] );
150 char *args[] = { "12", "60" , (char*)0 };
152 numt = pvm_spawn( "FEM1", args, 0, 0, 16, tids );
153 numt = pvm_spawn( "pde", 0, PvmTaskHost, "paragon.ornl", 512, tids );
155 Fortran:
158 FLAG = PVMARCH + PVMDEBUG
159 CALL PVMFSPAWN( 'node', FLAG, 'SUN4', 1, TID(3), NUMT )
160 CALL PVMFSPAWN( 'FEM1', PVMDEFAULT, '*', 16, TIDS, NUMT )
161 CALL PVMFSPAWN( 'TBMD', PVMHOST, 'cm5.utk.edu', 32, TIDS, NUMT )
162
165 These error conditions can be returned by pvm_spawn either in numt or
166 in the tids array.
167 PvmBadParam
169 giving an invalid argument value.
170 PvmNoHost
172 Specified host is not in the virtual machine.
173 PvmNoFile
175 Specified executable cannot be found. The default location PVM
176 looks in is ~/pvm3/bin/ARCH, where ARCH is a PVM architecture
177 name.
178 PvmNoMem
180 Malloc failed. Not enough memory on host.
181 PvmSysErr
183 pvmd not responding.
184 PvmOutOfRes
186 out of resources.
187
189 pvm_export(3PVM)
190 30 August, 1993 SPAWN(3PVM)