|
« Return to documentation listing
Table of Contents
MPI_Comm_spawn_multiple - Spawns multiple binaries, or the same
binary with multiple sets of arguments.
#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[])
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, *)
USE mpi_f08
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, INTENT(IN) :: count, array_of_maxprocs(*), root
CHARACTER(LEN=*), INTENT(IN) :: array_of_commands(*)
CHARACTER(LEN=*), INTENT(IN) :: array_of_argv(count, *)
TYPE(MPI_Info), INTENT(IN) :: array_of_info(*)
TYPE(MPI_Comm), INTENT(IN) :: comm
TYPE(MPI_Comm), INTENT(OUT) :: intercomm
INTEGER :: array_of_errcodes(*)
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
- 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).
- 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).
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).
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.
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.
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.
MPI_Comm_spawn(3)
MPI_Comm_get_parent(3)
mpirun(1)
« Return to documentation listing
|
