17.2.78. MPI_Comm_spawn_multiple
MPI_Comm_spawn_multiple — 生成多个可执行程序，或使用多组参数生成同一个可执行程序。
17.2.78.1. 语法
17.2.78.1.1. C语法
#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[])
17.2.78.1.2. Fortran语法
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, *)
17.2.78.1.3. Fortran 2008 语法
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
17.2.78.2. 输入参数
count: 命令数量（正整数，仅在root节点对MPI有意义——参见注意事项）。array_of_commands: 要执行的程序（字符串数组，仅在root节点有效）。array_of_argv: 用于commands的参数（字符串数组的数组，仅在root节点有效）。array_of_maxprocs: 每个命令启动的最大进程数（整数数组，仅在根节点有效）。array_of_info: 信息对象数组，告知运行时系统在何处以及如何启动进程（句柄数组，仅在根节点有效）。root: 检查前述参数的进程等级（整数）。comm: 包含派生进程组的内部通信器（句柄）。
17.2.78.3. 输出参数
intercomm: 原始组与新生成组之间的进程间通信器（句柄）。array_of_errcodes: 每个进程对应一个错误码（整数数组）。ierror: 仅限Fortran：错误状态（整数）。
17.2.78.4. 描述
MPI_Comm_spawn_multiple 与 MPI_Comm_spawn 功能相同，区别在于它可以指定多个可执行文件。第一个参数 count 表示可执行文件的数量。接下来的三个参数是对应于 MPI_Comm_spawn 中参数的数组。下一个参数 array_of_info 是一个由 info 参数组成的数组，每个可执行文件对应一个。更多信息请参阅 INFO ARGUMENTS 部分。
对于Fortran版本的array_of_argv，元素array_of_argv(i,j)表示第i个命令的第j个参数。
在任何编程语言中，应用程序都可以使用常量MPI_ARGVS_NULL（在C语言中通常表示为(char **)0）来指定不向任何命令传递参数。将array_of_argv数组中的个别元素设置为MPI_ARGV_NULL的效果是未定义的。若要为某些命令指定参数而其他命令不指定参数，那些不需要参数的命令对应的argv数组的第一个元素应为空值（在C语言中是((char *)0，在Fortran中是空字符串）。
所有生成的进程都拥有相同的MPI_COMM_WORLD。它们在MPI_COMM_WORLD中的排名直接对应于MPI_Comm_spawn_multiple中命令指定的顺序。假设第一个命令生成m1个进程，第二个命令生成m2个进程，依此类推。第一个命令对应的进程排名为0、1、...、m1-1。第二个命令中的进程排名为m1、m1+1、...、m1+m2-1。第三个命令中的进程排名为m1+m2、m1+m2+1、...、m1+m2+m3-1，以此类推。
array_of_errcodes 参数是一个大小为1维的数组
_ count
\ n ,
/_ i=1 i
其中i是array_of_maxprocs的第i个元素。命令编号i对应于该数组中从元素开始的i个连续槽位
_ _
_ i-1 | _ i |
\ n , to | \ n | -1
/_ j=1 i | /_ j=1 j |
|_ _|
错误代码的处理方式与MPI_Comm_spawn相同。
17.2.78.5. 信息参数
在“#PACKAGE_NAME#”中识别以下info键值。（MPI-2标准第5.3.4节中提到的保留值尚未实现。）
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键实际上是字符串，但会按以下规则进行求值：如果字符串值是数字，则转换为整数并强制转为布尔值（即零值为假，非零值为真）。如果字符串值为（不区分大小写）"yes"或"true"，则布尔值为真。如果字符串值为（不区分大小写）"no"或"false"，则布尔值为假。所有其他字符串值均不被识别，因此视为假。
请注意，如果任何信息句柄将ompi_non_mpi设置为true，则所有信息句柄都必须将其设置为true。如果部分设置为true，而其他设置为false（或未设置），则会返回MPI_ERR_INFO。
请注意，在“#PACKAGE_NAME#”中，array_of_info的第一个数组位置将应用于array_of_commands中的所有命令。
17.2.78.6. 注意事项
参数count仅在根节点由MPI解释，array_of_argv同理。由于array_of_argv的首维是count，在非根节点上若count值为非正数，理论上可能导致运行时边界检查错误——尽管该子程序本应忽略array_of_argv。若发生此情况，您应在非根节点显式提供一个合理的count值。
与MPI_Comm_spawn类似，应用程序有责任终止array_of_argv参数中的每个独立argv集合。在C语言中，每个argv数组以NULL指针结尾。在Fortran中，每个argv数组以空字符串结尾（请注意编译器不会自动插入这个空字符串；应用程序必须确保数组最后一个元素预留足够的空间来存放空字符串条目）。
其他限制适用于array_of_argv参数；更多详情请参阅MPI_Comm_spawn对argv参数的描述。
MPI-3.1 暗示（但未直接声明）参数 array_of_commands 必须是一个长度为 count 的字符串数组。 与 array_of_argv 参数不同，array_of_commands 在 C 语言中不需要以 NULL 指针结尾，在 Fortran 中也不需要以空字符串结尾。 旧版 Open MPI 要求 array_of_commands 在 Fortran 中以空字符串结尾；在当前版本的 Open MPI 中已不再需要此要求。
多次调用MPI_Comm_spawn会创建多组具有不同MPI_COMM_WORLD的子进程，而MPI_Comm_spawn_multiple则会创建共享同一个MPI_COMM_WORLD的子进程，因此这两种方法并不完全等同。此外，如果需要生成多个可执行文件，使用MPI_Comm_spawn_multiple而非多次调用MPI_Comm_spawn可能会获得更好的性能。
17.2.78.7. 错误
几乎所有MPI例程都会返回一个错误值；C语言例程通过函数返回值返回，Fortran例程则通过最后一个参数返回。
在返回错误值之前，会调用与通信对象（如通信器、窗口、文件）关联的当前MPI错误处理程序。如果MPI调用未关联任何通信对象，则该调用被视为附加到MPI_COMM_SELF，并将调用关联的MPI错误处理程序。当MPI_COMM_SELF未初始化时（即在MPI_Init/MPI_Init_thread之前、MPI_Finalize之后，或仅使用会话模型时），错误会触发初始错误处理程序。初始错误处理程序可通过在使用世界模型时调用MPI_Comm_set_errhandler来修改MPI_COMM_SELF，或通过mpiexec的mpi_initial_errhandler命令行参数，或MPI_Comm_spawn/MPI_Comm_spawn_multiple的info键来设置。如果未设置其他适当的错误处理程序，则MPI I/O函数将调用MPI_ERRORS_RETURN错误处理程序，而其他所有MPI函数将调用MPI_ERRORS_ABORT错误处理程序。
Open MPI 包含三个可使用的预定义错误处理器：
MPI_ERRORS_ARE_FATAL导致程序中止所有连接的MPI进程。MPI_ERRORS_ABORT一个可在通信器、窗口、文件或会话上调用的错误处理程序。当在通信器上调用时，其行为类似于在该通信器上调用MPI_Abort。如果在窗口或文件上调用，则行为类似于在包含对应窗口或文件中进程组的通信器上调用MPI_Abort。如果在会话上调用，则仅中止本地进程。MPI_ERRORS_RETURN向应用程序返回一个错误代码。
MPI应用程序也可以通过调用以下方式实现自己的错误处理程序：
请注意，MPI不保证MPI程序在出现错误后能够继续运行。
有关更多信息，请参阅MPI-3.1标准中的错误处理部分。