SPAWN(3PVM)

💖 SPAWN(3PVM) 💖

okay bestie, welcome to pvm_spawn — the PVM routine that literally starts new PVM processes for you. she's from PVM Version 3.4 and she's been doing this since 1993 and she has NEVER missed. let's get into it 🫶

---

🌸 NAME 🌸

pvm_spawn — Starts new PVM processes. periodt.

---

✨ SYNOPSIS ✨

C, the classic:

int numt = pvm_spawn( char *task, char **argv, int flag,
char *where, int ntask, int *tids )

Fortran, the vintage:

call pvmfspawn( task, flag, where, ntask, tids, numt )

---

🎀 PARAMETERS 🎀

• task — a character string, and it's the executable file name of the PVM process you're starting. no cap: the executable has to already be sitting on the host where it's gonna start. the name can 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 for the executable (if that's even supported on the target machine). note that the executable name is NOT included in this array, and the end of the array is marked by NULL. argv[0] of the spawned task gets set to the executable path relative to the PVM working directory (or absolute if you gave an absolute filename). and if your executable needs no arguments? then the second argument to pvm_spawn is NULL. easy.
• flag — integer, and it's the one specifying your spawn options. 🦋

In C, flag should be the sum of:

• 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:

• 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 — she's not here yet, she's coming tho 💅

• where — character string specifying where to start the PVM process. depending on what flag is, where can be a host name like "ibm1.epm.ornl.gov" or a PVM architecture class like "SUN4". also, the host name "." is taken as the localhost. if flag is 0, then where gets ignored when determining the target host or architecture, and PVM will pick the most appropriate host for you (she's got taste).

the where argument can ALSO be used to specify a custom working directory for each given spawn command. how? by appending a ':' and the desired working directory path to the where string, like:

"ibm1.epm.ornl.gov:/home/user/project/foo"

PVM will temporarily change the working directory to spawn the given task(s), and then reset back to the default working directory after the spawn is executed. and lowkey, you don't even need to pair this with the PvmTaskHost or PvmTaskArch flags, because the working directory path gets stripped off before any host or architecture name is parsed. so a valid specification for where is:

":/home/user/project/foo"

the working directory can be either an absolute path name, or relative to the current default working directory. either way, she eats. 🍓

• 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 mean a system error. a positive value less than ntask means a partial failure — in that case you 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 the parent environment to the children tasks. if set, the envar PVM_EXPORT is passed. and if PVM_EXPORT contains other names (separated by ':') they'll get passed too. this is useful for, like, 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 failed to start, and you should check the last ntask - numt locations in the tids array — those 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. she's just rotating, it's her thing.

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. iconic behaviour honestly.

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. no extra steps, she just does it.

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 users can modify to their individual tastes. presently the script starts an xterm with dbx or a 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. not me being the bearer of bad news but you need to know:

• 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)

---

and that's the whole page bestie, you ate that 💅 PVM Version 3.4, dated 30 August, 1993 — yeah she's vintage, she's archival, she's a whole era, and she still runs. mwah. 🎀💖✨