NAME

MPI_Comm_spawn_multiple - Spawns multiple binaries, or the same binary with multiple sets of arguments.

SYNTAX

C Syntax

#include <mpi.h>
int MPI_Comm_spawn_multiple(int count, char *array_of_commands[],
	char **array_of_argv[], const int array_of_maxprocs[], const MPI_Info
	array_of_info[], int root, MPI_Comm comm, MPI_Comm *intercomm,
	int array_of_errcodes[])

Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_COMM_SPAWN_MULTIPLE(COUNT, ARRAY_OF_COMMANDS, ARRAY_OF_ARGV,
	ARRAY_OF_MAXPROCS, ARRAY_OF_INFO, ROOT, COMM, INTERCOMM,
	ARRAY_OF_ERRCODES, IERROR)
	INTEGER	COUNT, ARRAY_OF_INFO(*), ARRAY_OF_MAXPROCS(*), ROOT,
		COMM, INTERCOMM, ARRAY_OF_ERRCODES(*), IERROR
	CHARACTER*(*) ARRAY_OF_COMMANDS(*), ARRAY_OF_ARGV(COUNT, *)

C++ Syntax

#include <mpi.h>
MPI::Intercomm MPI::Intracomm::Spawn_multiple(int count,
	const char* array_of_commands[], const char** array_of_argv[],
	const int array_of_maxprocs[], const MPI::Info array_of_info[],
	int root, int array_of_errcodes[])
MPI::Intercomm MPI::Intracomm::Spawn_multiple(int count,
	const char* array_of_commands[], const char** array_of_argv[],
	const int array_of_maxprocs[], const MPI::Info array_of_info[],
	int root)

INPUT PARAMETERS

count: Number of commands (positive integer, significant to MPI only at root -- see NOTES).
array_of_commands: Programs to be executed (array of strings, significant only at root).
array_of_argv: Arguments for commands (array of array of strings, significant only at root).
array_of_maxprocs: Maximum number of processes to start for each command (array of integers, significant only at root).
array_of_info: Info objects telling the runtime system where and how to start processes (array of handles, significant only at root).
root: Rank of process in which previous arguments are examined (integer).
comm: Intracommunicator containing group of spawning processes (handle).

OUTPUT PARAMETERS

intercomm: Intercommunicator between original group and the newly spawned group (handle).
array_of_errcodes: One code per process (array of integers).
IERROR: Fortran only: Error status (integer).

DESCRIPTION

MPI_Comm_spawn_multiple is identical to MPI_Comm_spawn(3) except that it can specify multiple executables. The first argument, count, indicates the number of executables. The next three arguments are arrays of the corresponding arguments in MPI_Comm_spawn(3). The next argument, array_of_info, is an array of info arguments, one for each executable. See the INFO ARGUMENTS section for more information.

For the Fortran version of array_of_argv, the element array_of_argv(i,j) is the jth argument to command number i.

In any language, an application may use the constant MPI_ARGVS_NULL (which is likely to be (char ***)0 in C) to specify that no arguments should be passed to any commands. The effect of setting individual elements of array_of_argv to MPI_ARGV_NULL is not defined. To specify arguments for some commands but not others, the commands without arguments should have a corresponding argv whose first element is null ((char *)0 in C and empty string in Fortran).

All of the spawned processes have the same MPI_COMM_WORLD. Their ranks in MPI_COMM_WORLD correspond directly to the order in which the commands are specified in MPI_Comm_spawn_multiple. Assume that m1 processes are generated by the first command, m2 by the second, etc. The processes corresponding to the first command have ranks 0, 1,..., m1-1. The processes in the second command have ranks m1, m1+1, ..., m1+m2-1. The processes in the third have ranks m1+m2, m1+m2+1, ..., m1+m2+m3-1, etc.

The array_of_errcodes argument is 1-dimensional array of size

	 _ count
	\       n ,
	/_ i=1   i

where i is the ith element of array_of_maxprocs. Command number i corresponds to the i contiguous slots in this array from element



                      _              _
	 _ i-1          |   _ i          |
	\       n ,  to |  \      n      | -1
	/_ j=1   i      |  /_ j=1  j     |


                     |_              _|

Error codes are treated as for MPI_Comm_spawn(3).

INFO ARGUMENTS

The following keys for info are recognized in "Open MPI". (The reserved values mentioned in Section 5.3.4 of the MPI-2 standard are not implemented.)

Key                    Type     Description
---                    ----     -----------
host                   char *   Comma-separated list of hosts on which


                                the processes should be spawned.  See


                                the orte_host man page for an


                                explanation of how this will be used.
hostfile               char *   Hostfile containing the hosts on which


                                the processes are to be spawned. See


                                the orte_hostfile man page for


                                an explanation of how this will be


                                used.
add-host               char *   Add the specified hosts to the list of


                                hosts known to this job and use it for


                                the associated processes. This will be


                                used similarly to the -host option.
add-hostfile           char *   Hostfile containing hosts to be added


                                to the list of hosts known to this job


                                and use it for the associated


                                process. This will be used similarly


                                to the -hostfile option.
wdir                   char *   Directory where the executable is


                                located. If files are to be


                                pre-positioned, then this location is


                                the desired working directory at time


                                of execution - if not specified, then


                                it will automatically be set to


                                ompi_preload_files_dest_dir.
ompi_prefix            char *   Same as the --prefix command line


                                argument to mpirun.
ompi_preload_binary    bool     If set to true, pre-position the


                                specified executable onto the remote


                                host. A destination directory must


                                also be provided.
ompi_preload_files     char *   A comma-separated list of files that


                                are to be pre-positioned in addition


                                to the executable.  Note that this


                                option does not depend upon


                                ompi_preload_binary - files can


                                be moved to the target even if an


                                executable is not moved.
ompi_stdin_target      char *   Comma-delimited list of ranks to


                                receive stdin when forwarded.
ompi_non_mpi           bool     If set to true, launching a non-MPI


                                application; the returned communicator


                                will be MPI_COMM_NULL. Failure to set


                                this flag when launching a non-MPI


                                application will cause both the child


                                and parent jobs to "hang".
ompi_param             char *   Pass an OMPI MCA parameter to the


                                child job.  If that parameter already


                                exists in the environment, the value


                                will be overwritten by the provided


                                value.
mapper                 char *   Mapper to be used for this job
map_by                 char *   Mapping directive indicating how


                                processes are to be mapped (slot,


                                node, socket, etc.).
rank_by                char *   Ranking directive indicating how


                                processes are to be ranked (slot,


                                node, socket, etc.).
bind_to                char *   Binding directive indicating how


                                processes are to be bound (core, slot,


                                node, socket, etc.).
path                   char *   List of directories to search for


                                the executable
npernode               char *   Number of processes to spawn on


                                each node of the allocation
pernode                bool     Equivalent to npernode of 1
ppr                    char *   Spawn specified number of processes


                                on each of the identified object type
env                    char *   Newline-delimited list of envars to


                                be passed to the spawned procs

bool info keys are actually strings but are evaluated as follows: if the string value is a number, it is converted to an integer and cast to a boolean (meaning that zero integers are false and non-zero values are true). If the string value is (case-insensitive) "yes" or "true", the boolean is true. If the string value is (case-insensitive) "no" or "false", the boolean is false. All other string values are unrecognized, and therefore false.

Note that if any of the info handles have ompi_non_mpi set to true, then all info handles must have it set to true. If some are set to true, but others are set to false (or are unset), MPI_ERR_INFO will be returned.

Note that in "Open MPI", the first array location in array_of_info is applied to all the commands in array_of_commands.

NOTES

The argument count is interpreted by MPI only at the root, as is array_of_argv. Since the leading dimension of array_of_argv is count, a nonpositive value of count at a nonroot node could theoretically cause a runtime bounds check error, even though array_of_argv should be ignored by the subroutine. If this happens, you should explicitly supply a reasonable value of count on the nonroot nodes.

Similar to MPI_Comm_spawn(3), it is the application's responsibility to terminate each individual set of argv in the array_of_argv argument. In C, each argv array is terminated by a NULL pointer. In Fortran, each argv array is terminated by an empty string (note that compilers will not automatically insert this blank string; the application must ensure to have enough space for an empty string entry as the last element of the array).

Other restrictions apply to the array_of_argv parameter; see MPI_Comm_spawn(3)'s description of the argv parameter for more details.

MPI-3.1 implies (but does not directly state) that the argument array_of_commands must be an array of strings of length count. Unlike the array_of_argv parameter, array_of_commands does not need to be terminated with a NULL pointer in C or a blank string in Fortran. Older versions of Open MPI required that array_of_commands be terminated with a blank string in Fortran; that is no longer required in this version of Open MPI.

Calling MPI_Comm_spawn(3) many times would create many sets of children with different MPI_COMM_WORLDs, whereas MPI_Comm_spawn_multiple creates children with a single MPI_COMM_WORLD, so the two methods are not completely equivalent. Also if you need to spawn multiple executables, you may get better performance by using MPI_Comm_spawn_multiple instead of calling MPI_Comm_spawn(3) several times.

ERRORS

Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI::Exception object.

Before the error value is returned, the current MPI error handler is called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned. Note that MPI does not guarantee that an MPI program can continue past an error.