Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SPAWN(3PVM)			PVM Version 3.4			   SPAWN(3PVM)

       pvm_spawn - Starts new PVM processes.

       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 )

       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  ""	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

	       The where argument can also be used to specify a	custom working
	       directory for each given	spawn command.	This is	 done  by  ap-
	       pending	a  ':'	and  the desired working directory path	to the
	       where string, i.e.:


	       PVM will	temporarily change the working directory to spawn  the
	       given  task(s),	and will then reset to the default working di-
	       rectory 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:


	       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

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

       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_EX-
       PORT  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

       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 de-
       bugger(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

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

	    CALL PVMFSPAWN( 'node', FLAG, 'SUN4', 1, TID(3), NUMT )

       These error conditions can be returned by pvm_spawn either in  numt  or
       in the tids array.

	      giving an	invalid	argument value.

	      Specified	host is	not in the virtual machine.

	      Specified	 executable  cannot be found. The default location PVM
	      looks in is ~/pvm3/bin/ARCH, where ARCH is  a  PVM  architecture

	      Malloc failed. Not enough	memory on host.

	      pvmd not responding.

	      out of resources.


				30 August, 1993			   SPAWN(3PVM)


Want to link to this manual page? Use this URL:

home | help