1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
.\" $Id: pvm_spawn.3,v 1.1 1996/09/23 22:20:59 pvmsrc Exp $
.TH SPAWN 3PVM "30 August, 1993" "" "PVM Version 3.4"
.SH NAME
pvm_spawn \- Starts new PVM processes.
.SH SYNOPSIS
.nf
.ft B
C int numt = pvm_spawn( char *task, char **argv, int flag,
char *where, int ntask, int *tids )
.br
Fortran call pvmfspawn( task, flag, where, ntask, tids, numt )
.fi
.SH PARAMETERS
.IP task 0.8i
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/ .
.br
.IP 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.
.br
.IP flag
Integer specifying spawn options.
.ta 0.5i 2.0i 2.5i
.nf
In C, \fIflag\fR should be the \fIsum\fR of:
Option value MEANING
PvmTaskDefault 0 PVM can choose any machine to start task
PvmTaskHost 1 \fIwhere\fR specifies a particular host
PvmTaskArch 2 \fIwhere\fR 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, \fIflag\fR should be the \fIsum\fR of:
Option value MEANING
PVMDEFAULT 0 PVM can choose any machine to start task
PVMHOST 1 \fIwhere\fR specifies a particular host
PVMARCH 2 \fIwhere\fR specifies a type of architecture
PVMDEBUG 4 Start up processes under debugger
PVMTRACE 8 Processes will generate PVM trace data. *
* future extension
.fi
.IP where
Character string specifying where to start the PVM process.
Depending on the value of
.I flag,
.I where
can be a host name such as ``ibm1.epm.ornl.gov'' or a PVM
architecture class such as ``SUN4''.
If
.I flag
is 0, then
.I where
is ignored and PVM will select the most appropriate host.
.br
.IP ntask
Integer specifying the number of copies of the executable to start.
.br
.IP tids
Integer array of length
.I ntask
returning
the tids of the PVM processes started by this pvm_spawn call.
.br
.IP numt
Integer returning the actual number of tasks started.
Values less than zero indicate a system error.
A positive value less than
.I ntask
indicates a partial failure.
In this case the user should check the
.I tids
array for the error code(s).
.SH DESCRIPTION
The routine
.I pvm_spawn
starts
.I ntask
copies of the executable named
.I task.
On systems that support environment,
spawn passes selected variables from parent environment to children tasks.
If set, the envar \fIPVM_EXPORT\fR is passed.
If PVM_EXPORT contains other names (separated by ':') they will
be passed too. This is useful for e.g.:
.nf
setenv DISPLAY myworkstation:0.0
setenv MYSTERYVAR 13
setenv PVM_EXPORT DISPLAY:MYSTERYVAR
.fi
.PP
The hosts on which
the PVM processes are started are determined by the
.I flag
and
.I where
arguments. On return the array
.I tids
contains the PVM task identifiers for each process started.
.PP
If pvm_spawn starts one or more tasks,
.I numt
will be the actual number of tasks started.
If a system error occurs then
.I numt
will be < 0.
If
.I numt
is less than
.I ntask
then some executables
have failed to start and the user should check the last
.I ntask -
.I numt
locations in the
.I tids
array which will contain error codes
(see below for meaning).
The first
.I numt
tids in the array are always valid.
.PP
When
.I flag
is set to 0 and
.I where
is set to NULL (or ``*'' in Fortran)
a heuristic (round-robin assignment) is used to distribute the
.I ntask
processes across the virtual machine.
.PP
If the PvmHostCompl flag is set, the resulting host set gets complemented.
Also, the TaskHost hostname "." is taken as localhost.
These can be used, for example, to spawn
n - 1 tasks on host "." with flags TaskHost|HostCompl
to get all but the localhost.
.PP
In the special case where a multiprocessor is specified by
.I where,
pvm_spawn will start all
.I ntask
copies on this
single machine using the vendor's underlying routines.
.PP
The spawned task will have
.I 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:
.br
char *p;
.br
p = (p = rindex(argv[0], '/')) ? p + 1 : argv[0];
.PP
If PvmTaskDebug is set, then the pvmd will start the task(s)
under debugger(s). In this case, instead of executing
\fIpvm3/bin/ARCH/task args\fR
it executes
\fIpvm3/lib/debugger pvm3/bin/ARCH/task args\fR.
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.
.SH EXAMPLES
.nf
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 );
.sp
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 )
.SH ERRORS
These error conditions can be returned by
.I pvm_spawn
either in
.I numt
or in the
.I tids
array.
.IP PvmBadParam
giving an invalid argument value.
.IP PvmNoHost
Specified host is not in the virtual machine.
.IP PvmNoFile
Specified executable cannot be found. The default
location PVM looks in is ~/pvm3/bin/ARCH,
where ARCH is a PVM architecture name.
.IP PvmNoMem
Malloc failed. Not enough memory on host.
.IP PvmSysErr
pvmd not responding.
.IP PvmOutOfRes
out of resources.
.PP
.SH SEE ALSO
pvm_export(3PVM)
|
