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

FreeBSD Manual Pages

  
 
  

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

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 exe-
	     cutable 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.  De-
	     pending 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 architec-
	     ture, and PVM will select the most appropriate host.

	     The where argument can also be used to specify a custom working di-
	     rectory  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  con-
	     junction  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 par-
     ent 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 identi-
     fiers 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  lo-
     calhost.

     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 un-
     derlying 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  debug-
     ger(s).  In this case, instead of executing pvm3/bin/ARCH/task args it exe-
     cutes 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)

				 30 August, 1993		     SPAWN(3PVM)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pvm_spawn&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help