253 строки
12 KiB
Plaintext
253 строки
12 KiB
Plaintext
.\" Copyright (c) 2010 Cisco Systems, Inc. All rights reserved.
|
|
.\" Copyright 2006-2008 Sun Microsystems, Inc.
|
|
.\" Copyright (c) 1996 Thinking Machines Corporation
|
|
.TH MPI_Comm_spawn_multiple 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
|
|
.SH NAME
|
|
\fBMPI_Comm_spawn_multiple\fP \- Spawns multiple binaries, or the same binary with multiple sets of arguments.
|
|
|
|
.SH SYNTAX
|
|
.ft R
|
|
.SH C Syntax
|
|
.nf
|
|
#include <mpi.h>
|
|
int MPI_Comm_spawn_multiple(int \fIcount\fP, char *\fIarray_of_commands\fP[],
|
|
char **\fIarray_of_argv\fP[], int \fIarray_of_maxprocs\fP[], MPI_Info
|
|
\fIarray_of_info\fP[], int \fIroot\fP, MPI_Comm \fIcomm\fP, MPI_Comm *\fIintercomm\fP,
|
|
int \fIarray_of_errcodes\fP[])
|
|
|
|
.fi
|
|
.SH Fortran Syntax
|
|
.nf
|
|
INCLUDE 'mpif.h'
|
|
MPI_COMM_SPAWN_MULTIPLE(\fICOUNT, ARRAY_OF_COMMANDS, ARRAY_OF_ARGV,
|
|
ARRAY_OF_MAXPROCS, ARRAY_OF_INFO, ROOT, COMM, INTERCOMM,
|
|
ARRAY_OF_ERRCODES, IERROR\fP)
|
|
INTEGER \fICOUNT, ARRAY_OF_INFO(*), ARRAY_OF_MAXPROCS(*), ROOT,
|
|
COMM, INTERCOMM, ARRAY_OF_ERRCODES(*), IERROR\fP
|
|
CHARACTER*(*) \fIARRAY_OF_COMMANDS\fP(*), \fIARRAY_OF_ARGV\fP(\fICOUNT\fP, *)
|
|
|
|
.fi
|
|
.SH C++ Syntax
|
|
.nf
|
|
#include <mpi.h>
|
|
MPI::Intercomm MPI::Intracomm::Spawn_multiple(int \fIcount\fP,
|
|
const char* \fIarray_of_commands\fP[], const char** \fIarray_of_argv\fP[],
|
|
const int \fIarray_of_maxprocs\fP[], const MPI::Info \fIarray_of_info\fP[],
|
|
int \fIroot\fP, int \fIarray_of_errcodes\fP[])
|
|
|
|
MPI::Intercomm MPI::Intracomm::Spawn_multiple(int \fIcount\fP,
|
|
const char* \fIarray_of_commands\fP[], const char** \fIarray_of_argv\fP[],
|
|
const int \fIarray_of_maxprocs\fP[], const MPI::Info \fIarray_of_info\fP[],
|
|
int \fIroot\fP)
|
|
|
|
.fi
|
|
.SH INPUT PARAMETERS
|
|
.ft R
|
|
.TP 1i
|
|
count
|
|
Number of commands (positive integer, significant to MPI only at \fIroot\fP -- see NOTES).
|
|
.TP 1i
|
|
array_of_commands
|
|
Programs to be executed (array of strings, significant only at \fIroot\fP).
|
|
.TP 1i
|
|
array_of_argv
|
|
Arguments for \fIcommands\fP (array of array of strings, significant only at \fIroot\fP).
|
|
.TP 1i
|
|
array_of_maxprocs
|
|
Maximum number of processes to start for each command (array of integers, significant only at \fIroot\fP).
|
|
.TP 1i
|
|
array_of_info
|
|
Info objects telling the runtime system where and how to start processes (array of handles, significant only at \fIroot\fP).
|
|
.TP 1i
|
|
root
|
|
Rank of process in which previous arguments are examined (integer).
|
|
.TP 1i
|
|
comm
|
|
Intracommunicator containing group of spawning processes (handle).
|
|
|
|
.SH OUTPUT PARAMETERS
|
|
.ft R
|
|
.TP 1i
|
|
intercomm
|
|
Intercommunicator between original group and the newly spawned group (handle).
|
|
.TP 1i
|
|
array_of_errcodes
|
|
One code per process (array of integers).
|
|
.TP 1i
|
|
IERROR
|
|
Fortran only: Error status (integer).
|
|
|
|
.SH DESCRIPTION
|
|
.ft R
|
|
MPI_Comm_spawn_multiple is identical to MPI_Comm_spawn(3) except that
|
|
it can specify multiple executables. The first argument, \fIcount\fP,
|
|
indicates the number of executables. The next three arguments are
|
|
arrays of the corresponding arguments in MPI_Comm_spawn(3). The next
|
|
argument, \fIarray_of_info\fP, is an array of \fIinfo\fP arguments, one
|
|
for each executable. See the INFO ARGUMENTS section for more information.
|
|
.sp
|
|
For the Fortran version of \fIarray_of_argv\fP, the element \fIarray_of_argv\fP(i,j) is the jth argument to command number i.
|
|
.sp
|
|
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 \fIarray_of_argv\fP to MPI_ARGV_NULL is not defined. To specify arguments for some commands but not others, the commands without arguments should have a corresponding \fIargv\fP whose first element is null ((char *)0 in C and empty string in Fortran).
|
|
.sp
|
|
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.
|
|
.sp
|
|
The \fIarray_of_errcodes\fP argument is 1-dimensional array of size
|
|
.sp
|
|
.nf
|
|
_ count
|
|
\\ n ,
|
|
/_ i=1 i
|
|
.fi
|
|
.sp
|
|
where i is the ith element of \fIarray_of_maxprocs\fP. Command number \fIi\fP corresponds to the i contiguous slots in this array from element
|
|
.sp
|
|
.nf
|
|
_ _
|
|
_ \fIi\fP-1 | _ \fIi\fP |
|
|
\\ n , to | \\ n | -1
|
|
/_ \fIj\fP=1 i | /_ \fIj\fP=1 j |
|
|
|_ _|
|
|
.fi
|
|
.sp
|
|
Error codes are treated as for MPI_Comm_spawn(3).
|
|
|
|
|
|
.SH INFO ARGUMENTS
|
|
The following keys for \fIinfo\fP are recognized in "#PACKAGE_NAME#". (The reserved values mentioned in Section 5.3.4 of the MPI-2 standard are not implemented.)
|
|
.sp
|
|
.sp
|
|
.nf
|
|
Key Type Description
|
|
--- ---- -----------
|
|
|
|
host char * Comma-separated list of hosts on which
|
|
the processes should be spawned. See
|
|
the \fIorte_host\fP 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 \fIorte_hostfile\fP 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
|
|
\fIompi_preload_files_dest_dir\fP.
|
|
ompi_prefix char * Same as the --prefix command line
|
|
argument to mpirun.
|
|
ompi_local_slave bool If set to true, launch the specified
|
|
process as a local \fIslave\fP to the
|
|
calling process. The new process will
|
|
only be known to the caller, and will
|
|
only be able to communicate with the
|
|
caller.
|
|
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_dest_dir
|
|
char * Target directory where pre-positioned
|
|
files are to be placed.
|
|
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
|
|
\fIompi_preload_binary\fP - files can
|
|
be moved to the target even if an
|
|
executable is not moved.
|
|
ompi_preload_files_src_dir
|
|
char * Source directory where files and
|
|
executables that are to be
|
|
pre-positioned can be found. If not
|
|
specified, the current working
|
|
directory will be used.
|
|
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.
|
|
map_bynode bool If set to true, the processes are
|
|
mapped bynode. If set to false, the
|
|
processes are mapped byslot. By
|
|
default, mapping is determined by the
|
|
default mapping policy set when the
|
|
job was started.
|
|
.fi
|
|
|
|
.sp
|
|
\fIbool\fP 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.
|
|
|
|
.sp
|
|
Note that if any of the info handles have \fIompi_non_mpi\fP 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.
|
|
|
|
.sp
|
|
Note that in "#PACKAGE_NAME#", the first array location in \fIarray_of_info\fP is applied to all the commands in \fIarray_of_commands\fP.
|
|
|
|
.SH NOTES
|
|
The argument \fIcount\fP is interpreted by MPI only at the root, as is \fIarray_of_argv\fP. Since the leading dimension of \fIarray_of_argv\fP is \fIcount\fP, a nonpositive value of \fIcount\fP at a nonroot node could theoretically cause a runtime bounds check error, even though \fIarray_of_argv\fP should be ignored by the subroutine. If this happens, you should explicitly supply a reasonable value of \fIcount\fP on the nonroot nodes.
|
|
.sp
|
|
Similar to MPI_Comm_spawn(3), it is the application's responsibility
|
|
to terminate each individual set of argv in the
|
|
.I 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).
|
|
.sp
|
|
Other restrictions apply to the
|
|
.I array_of_argv
|
|
parameter; see MPI_Comm_spawn(3)'s description of the
|
|
.I argv
|
|
parameter for more details.
|
|
.sp
|
|
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.
|
|
|
|
.SH 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.
|
|
.sp
|
|
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.
|
|
|
|
.SH SEE ALSO
|
|
.ft R
|
|
.sp
|
|
.nf
|
|
MPI_Comm_spawn(3)
|
|
MPI_Comm_get_parent(3)
|
|
mpirun(1)
|