383 lines
16 KiB
Groff
383 lines
16 KiB
Groff
.\" Man page generated from reStructuredText.
|
||
.
|
||
.TH "MPI_COMM_SPAWN" "3" "Feb 14, 2025" "" "Open MPI"
|
||
.
|
||
.nr rst2man-indent-level 0
|
||
.
|
||
.de1 rstReportMargin
|
||
\\$1 \\n[an-margin]
|
||
level \\n[rst2man-indent-level]
|
||
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||
-
|
||
\\n[rst2man-indent0]
|
||
\\n[rst2man-indent1]
|
||
\\n[rst2man-indent2]
|
||
..
|
||
.de1 INDENT
|
||
.\" .rstReportMargin pre:
|
||
. RS \\$1
|
||
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
||
. nr rst2man-indent-level +1
|
||
.\" .rstReportMargin post:
|
||
..
|
||
.de UNINDENT
|
||
. RE
|
||
.\" indent \\n[an-margin]
|
||
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||
.nr rst2man-indent-level -1
|
||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||
..
|
||
.sp
|
||
\fI\%MPI_Comm_spawn\fP — Spawns a number of identical binaries.
|
||
.SH SYNTAX
|
||
.SS C Syntax
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
#include <mpi.h>
|
||
|
||
int MPI_Comm_spawn(const char *command, char *argv[], int maxprocs,
|
||
MPI_Info info, int root, MPI_Comm comm,
|
||
MPI_Comm *intercomm, int array_of_errcodes[])
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Fortran Syntax
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
USE MPI
|
||
! or the older form: INCLUDE \(aqmpif.h\(aq
|
||
MPI_COMM_SPAWN(COMMAND, ARGV, MAXPROCS, INFO, ROOT, COMM,
|
||
INTERCOMM, ARRAY_OF_ERRCODES, IERROR)
|
||
|
||
CHARACTER*(*) COMMAND, ARGV(*)
|
||
INTEGER INFO, MAXPROCS, ROOT, COMM, INTERCOMM,
|
||
ARRAY_OF_ERRCODES(*), IERROR
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Fortran 2008 Syntax
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
USE mpi_f08
|
||
MPI_Comm_spawn(command, argv, maxprocs, info, root, comm, intercomm,
|
||
array_of_errcodes, ierror)
|
||
CHARACTER(LEN=*), INTENT(IN) :: command, argv(*)
|
||
INTEGER, INTENT(IN) :: maxprocs, root
|
||
TYPE(MPI_Info), INTENT(IN) :: info
|
||
TYPE(MPI_Comm), INTENT(IN) :: comm
|
||
TYPE(MPI_Comm), INTENT(OUT) :: intercomm
|
||
INTEGER :: array_of_errcodes(*)
|
||
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SH INPUT PARAMETERS
|
||
.INDENT 0.0
|
||
.IP \(bu 2
|
||
\fBcommand\fP: Name of program to be spawned (string, significant only at \fIroot\fP).
|
||
.IP \(bu 2
|
||
\fBargv\fP: Arguments to \fIcommand\fP (array of strings, significant only at \fIroot\fP).
|
||
.IP \(bu 2
|
||
\fBmaxprocs\fP: Maximum number of processes to start (integer, significant only at \fIroot\fP).
|
||
.IP \(bu 2
|
||
\fBinfo\fP: A set of key\-value pairs telling the runtime system where and how to start the processes (handle, significant only at \fIroot\fP).
|
||
.IP \(bu 2
|
||
\fBroot\fP: Rank of process in which previous arguments are examined (integer).
|
||
.IP \(bu 2
|
||
\fBcomm\fP: Intracommunicator containing group of spawning processes (handle).
|
||
.UNINDENT
|
||
.SH OUTPUT PARAMETER
|
||
.INDENT 0.0
|
||
.IP \(bu 2
|
||
\fBintercomm\fP: Intercommunicator between original group and the newly spawned group (handle).
|
||
.IP \(bu 2
|
||
\fBarray_of_errcodes\fP: One code per process (array of integers).
|
||
.IP \(bu 2
|
||
\fBierror\fP: Fortran only: Error status (integer).
|
||
.UNINDENT
|
||
.SH DESCRIPTION
|
||
.sp
|
||
\fI\%MPI_Comm_spawn\fP tries to start \fImaxprocs\fP identical copies of the MPI
|
||
program specified by \fIcommand\fP, establishing communication with them and
|
||
returning an intercommunicator. The spawned processes are referred to as
|
||
children. The children have their own MPI_COMM_WORLD, which is separate
|
||
from that of the parents. \fI\%MPI_Comm_spawn\fP is collective over \fIcomm\fP, and
|
||
also may not return until \fI\%MPI_Init\fP has been called in the children.
|
||
Similarly, \fI\%MPI_Init\fP in the children may not return until all parents
|
||
have called \fI\%MPI_Comm_spawn\fP\&. In this sense, \fI\%MPI_Comm_spawn\fP in the parents
|
||
and \fI\%MPI_Init\fP in the children form a collective operation over the union
|
||
of parent and child processes. The intercommunicator returned by
|
||
\fI\%MPI_Comm_spawn\fP contains the parent processes in the local group and the
|
||
child processes in the remote group. The ordering of processes in the
|
||
local and remote groups is the same as the as the ordering of the group
|
||
of the \fIcomm\fP in the parents and of MPI_COMM_WORLD of the children,
|
||
respectively. This intercommunicator can be obtained in the children
|
||
through the function \fI\%MPI_Comm_get_parent\fP\&.
|
||
.sp
|
||
The MPI standard allows an implementation to use the MPI_UNIVERSE_SIZE
|
||
attribute of MPI_COMM_WORLD to specify the number of processes that will
|
||
be active in a program. Although this implementation of the MPI standard
|
||
defines MPI_UNIVERSE_SIZE, it does not allow the user to set its value.
|
||
If you try to set the value of MPI_UNIVERSE_SIZE, you will get an error
|
||
message.
|
||
.sp
|
||
The \fIcommand\fP Argument
|
||
.sp
|
||
The \fIcommand\fP argument is a string containing the name of a program to
|
||
be spawned. The string is null\-terminated in C. In Fortran, leading and
|
||
trailing spaces are stripped. MPI looks for the file first in the
|
||
working directory of the spawning process.
|
||
.sp
|
||
The \fIargv\fP Argument
|
||
.sp
|
||
\fIargv\fP is an array of strings containing arguments that are passed to
|
||
the program. The first element of \fIargv\fP is the first argument passed to
|
||
\fIcommand\fP, not, as is conventional in some contexts, the command itself.
|
||
The argument list is terminated by NULL in C and an empty string in
|
||
Fortran (note that it is the MPI application’s responsibility to ensure
|
||
that the last entry of the \fIargv\fP array is an empty string; the compiler
|
||
will not automatically insert it). In Fortran, leading and trailing
|
||
spaces are always stripped, so that a string consisting of all spaces is
|
||
considered an empty string. The constant MPI_ARGV_NULL may be used in C
|
||
and Fortran to indicate an empty argument list. In C, this constant is
|
||
the same as NULL.
|
||
.sp
|
||
In C, the \fI\%MPI_Comm_spawn\fP argument \fIargv\fP differs from the \fIargv\fP
|
||
argument of \fImain\fP in two respects. First, it is shifted by one element.
|
||
Specifically, \fIargv\fP[0] of \fImain\fP contains the name of the program
|
||
(given by \fIcommand\fP). \fIargv\fP[1] of \fImain\fP corresponds to \fIargv\fP[0]
|
||
in \fI\%MPI_Comm_spawn\fP, \fIargv\fP[2] of \fImain\fP to \fIargv\fP[1] of
|
||
\fI\%MPI_Comm_spawn\fP, and so on. Second, \fIargv\fP of \fI\%MPI_Comm_spawn\fP must be
|
||
null\-terminated, so that its length can be determined. Passing an \fIargv\fP
|
||
of MPI_ARGV_NULL to \fI\%MPI_Comm_spawn\fP results in \fImain\fP receiving \fIargc\fP of
|
||
1 and an \fIargv\fP whose element 0 is the name of the program.
|
||
.sp
|
||
The \fImaxprocs\fP Argument
|
||
.sp
|
||
Open MPI tries to spawn \fImaxprocs\fP processes. If it is unable to spawn
|
||
\fImaxprocs\fP processes, it raises an error of class MPI_ERR_SPAWN. If MPI
|
||
is able to spawn the specified number of processes, \fI\%MPI_Comm_spawn\fP
|
||
returns successfully and the number of spawned processes, \fIm\fP, is given
|
||
by the size of the remote group of \fIintercomm\fP\&.
|
||
.sp
|
||
A spawn call with the default behavior is called hard. A spawn call for
|
||
which fewer than \fImaxprocs\fP processes may be returned is called soft.
|
||
.sp
|
||
The \fIinfo\fP Argument
|
||
.sp
|
||
The \fIinfo\fP argument is an opaque handle of type MPI_Info in C and
|
||
INTEGER in Fortran. It is a container for a number of user\-specified
|
||
(\fIkey,value\fP) pairs. \fIkey\fP and \fIvalue\fP are strings (null\-terminated
|
||
\fBchar *\fP in C, \fBcharacter*(*)\fP in Fortran). Routines to create and
|
||
manipulate the \fIinfo\fP argument are described in Section 4.10 of the
|
||
MPI\-2 standard.
|
||
.sp
|
||
For the SPAWN calls, \fIinfo\fP provides additional,
|
||
implementation\-dependent instructions to MPI and the runtime system on
|
||
how to start processes. An application may pass MPI_INFO_NULL in C or
|
||
Fortran. Portable programs not requiring detailed control over process
|
||
locations should use MPI_INFO_NULL.
|
||
.sp
|
||
The following keys for \fIinfo\fP are recognized in Open MPI. (The reserved
|
||
values mentioned in Section 5.3.4 of the MPI\-2 standard are not
|
||
implemented.)
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
Key Type Description
|
||
\-\-\- \-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
|
||
|
||
host char * Host on which the process 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 host to the list of
|
||
hosts known to this job and use it for
|
||
the associated process. 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
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.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
|
||
The \fIroot\fP Argument
|
||
.sp
|
||
All arguments before the \fIroot\fP argument are examined only on the
|
||
process whose rank in \fIcomm\fP is equal to \fIroot\fP\&. The value of these
|
||
arguments on other processes is ignored.
|
||
.sp
|
||
The \fIarray_of_errcodes\fP Argument
|
||
.sp
|
||
The \fIarray_of_errcodes\fP is an array of length \fImaxprocs\fP in which MPI
|
||
reports the status of the processes that MPI was requested to start. If
|
||
all \fImaxprocs\fP processes were spawned, \fIarray_of_errcodes\fP is filled in
|
||
with the value MPI_SUCCESS. If anyof the processes are \fInot\fP spawned,
|
||
\fIarray_of_errcodes\fP is filled in with the value MPI_ERR_SPAWN. In C or
|
||
Fortran, an application may pass MPI_ERRCODES_IGNORE if it is not
|
||
interested in the error codes.
|
||
.SH NOTES
|
||
.sp
|
||
Completion of \fI\%MPI_Comm_spawn\fP in the parent does not necessarily mean
|
||
that \fI\%MPI_Init\fP has been called in the children (although the returned
|
||
intercommunicator can be used immediately).
|
||
.SH ERRORS
|
||
.sp
|
||
Almost all MPI routines return an error value; C routines as the return result
|
||
of the function and Fortran routines in the last argument.
|
||
.sp
|
||
Before the error value is returned, the current MPI error handler associated
|
||
with the communication object (e.g., communicator, window, file) is called.
|
||
If no communication object is associated with the MPI call, then the call is
|
||
considered attached to MPI_COMM_SELF and will call the associated MPI error
|
||
handler. When MPI_COMM_SELF is not initialized (i.e., before
|
||
\fI\%MPI_Init\fP/\fI\%MPI_Init_thread\fP, after \fI\%MPI_Finalize\fP, or when using the Sessions
|
||
Model exclusively) the error raises the initial error handler. The initial
|
||
error handler can be changed by calling \fI\%MPI_Comm_set_errhandler\fP on
|
||
MPI_COMM_SELF when using the World model, or the mpi_initial_errhandler CLI
|
||
argument to mpiexec or info key to \fI\%MPI_Comm_spawn\fP/\fI\%MPI_Comm_spawn_multiple\fP\&.
|
||
If no other appropriate error handler has been set, then the MPI_ERRORS_RETURN
|
||
error handler is called for MPI I/O functions and the MPI_ERRORS_ABORT error
|
||
handler is called for all other MPI functions.
|
||
.sp
|
||
Open MPI includes three predefined error handlers that can be used:
|
||
.INDENT 0.0
|
||
.IP \(bu 2
|
||
\fBMPI_ERRORS_ARE_FATAL\fP
|
||
Causes the program to abort all connected MPI processes.
|
||
.IP \(bu 2
|
||
\fBMPI_ERRORS_ABORT\fP
|
||
An error handler that can be invoked on a communicator,
|
||
window, file, or session. When called on a communicator, it
|
||
acts as if \fI\%MPI_Abort\fP was called on that communicator. If
|
||
called on a window or file, acts as if \fI\%MPI_Abort\fP was called
|
||
on a communicator containing the group of processes in the
|
||
corresponding window or file. If called on a session,
|
||
aborts only the local process.
|
||
.IP \(bu 2
|
||
\fBMPI_ERRORS_RETURN\fP
|
||
Returns an error code to the application.
|
||
.UNINDENT
|
||
.sp
|
||
MPI applications can also implement their own error handlers by calling:
|
||
.INDENT 0.0
|
||
.IP \(bu 2
|
||
\fI\%MPI_Comm_create_errhandler\fP then \fI\%MPI_Comm_set_errhandler\fP
|
||
.IP \(bu 2
|
||
\fI\%MPI_File_create_errhandler\fP then \fI\%MPI_File_set_errhandler\fP
|
||
.IP \(bu 2
|
||
\fI\%MPI_Session_create_errhandler\fP then \fI\%MPI_Session_set_errhandler\fP or at \fI\%MPI_Session_init\fP
|
||
.IP \(bu 2
|
||
\fI\%MPI_Win_create_errhandler\fP then \fI\%MPI_Win_set_errhandler\fP
|
||
.UNINDENT
|
||
.sp
|
||
Note that MPI does not guarantee that an MPI program can continue past
|
||
an error.
|
||
.sp
|
||
See the \fI\%MPI man page\fP for a full list of \fI\%MPI error codes\fP\&.
|
||
.sp
|
||
See the Error Handling section of the MPI\-3.1 standard for
|
||
more information.
|
||
.sp
|
||
\fBSEE ALSO:\fP
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.INDENT 0.0
|
||
.IP \(bu 2
|
||
\fI\%MPI_Comm_spawn_multiple\fP
|
||
.IP \(bu 2
|
||
\fI\%MPI_Comm_get_parent\fP
|
||
.IP \(bu 2
|
||
\fI\%mpirun(1)\fP
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SH COPYRIGHT
|
||
2003-2025, The Open MPI Community
|
||
.\" Generated by docutils manpage writer.
|
||
.
|