The following routine starts a number of MPI processes and establishes communication with them, returning an intercommunicator.
Advice to users.
It is possible in MPI to start a static SPMD or MPMD application by
starting first one process and having that process start its siblings
with MPI_COMM_SPAWN. This practice is discouraged primarily for
reasons of performance. If possible, it is preferable to start all
processes at once, as a single MPI-1 application.
( End of advice to users.)
| MPI_COMM_SPAWN(command, argv, maxprocs, info, root, comm, intercomm, array_of_errcodes) | |
| IN command | name of program to be spawned (string, significant only at root) |
| IN argv | arguments to command (array of strings, significant only at root) |
| IN maxprocs | maximum number of processes to start (integer, significant only at root) |
| IN info | a set of key-value pairs telling the runtime system where and how to start the processes (handle, significant only at root) |
| IN root | rank of process in which previous arguments are examined (integer) |
| IN comm | intracommunicator containing group of spawning processes (handle) |
| OUT intercomm | intercommunicator between original group and
the newly spawned group (handle) |
| OUT array_of_errcodes | one code per process (array of integer) |
MPI_COMM_SPAWN tries to start maxprocs identical copies of the MPI program specified by command, 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. MPI_COMM_SPAWN is collective over comm, and also may not return until MPI_INIT has been called in the children. Similarly, MPI_INIT in the children may not return until all parents have called MPI_COMM_SPAWN. In this sense, MPI_COMM_SPAWN in the parents and MPI_INIT in the children form a collective operation over the union of parent and child processes. The intercommunicator returned by MPI_COMM_SPAWN 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 comm in the parents and of MPI_COMM_WORLD of the children, respectively. This intercommunicator can be obtained in the children through the function MPI_COMM_GET_PARENT.
Advice to users.
An implementation may automatically establish communication before
MPI_INIT is called by the children. Thus, completion of
MPI_COMM_SPAWN in the parent does not necessarily mean that
MPI_INIT has been called in the children (although the
returned intercommunicator can be used immediately).
( End of advice to users.)
The command argument The command 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 does not specify how to find the executable or how the working directory is determined. These rules are implementation-dependent and should be appropriate for the runtime environment.
Advice
to implementors.
The implementation should use a natural rule for finding
executables and determining working directories. For instance, a
homogeneous system with a global file system might look first in the
working directory of the spawning process, or might search the
directories in a PATH environment variable as do Unix shells. An
implementation on top of PVM would use PVM's rules for finding
executables (usually in
$HOME/pvm3/bin/$PVM_ARCH). An MPI implementation running under POE on an
IBM SP would use POE's method of finding executables. An implementation
should document its rules for finding executables and determining
working directories, and a high-quality implementation should give the
user some control over these rules.
( End of advice to implementors.)
If the program named in command does not call
MPI_INIT, but instead forks a process that calls
MPI_INIT, the results are undefined. Implementations
may allow this case to work but are not required to.
Advice to users.
MPI does not say what happens if the program you start is
a shell script and that shell script starts a program that
calls MPI_INIT. Though some implementations may allow
you to do this, they may also have restrictions, such as requiring
that arguments supplied to the shell script be supplied
to the program, or requiring that certain parts of the environment
not be changed.
( End of advice to users.)
The argv argument argv is an array of strings containing arguments that are passed to the program. The first element of argv is the first argument passed to command, not, as is conventional in some contexts, the command itself. The argument list is terminated by NULL in C and C++ and an empty string in Fortran. 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, C++ and Fortran to indicate an empty argument list. In C and C++, this constant is the same as NULL.
Example Examples of argv in C and Fortran
To run the program ``ocean'' with arguments ``-gridfile'' and
``ocean1.grd'' in C:
char command[] = "ocean";
char *argv[] = {"-gridfile", "ocean1.grd", NULL};
MPI_Comm_spawn(command, argv, ...);
or, if not everything is known at compile time:
char *command;
char **argv;
command = "ocean";
argv=(char **)malloc(3 * sizeof(char *));
argv[0] = "-gridfile";
argv[1] = "ocean1.grd";
argv[2] = NULL;
MPI_Comm_spawn(command, argv, ...);
In Fortran:
CHARACTER*25 command, argv(3)
command = ' ocean '
argv(1) = ' -gridfile '
argv(2) = ' ocean1.grd'
argv(3) = ' '
call MPI_COMM_SPAWN(command, argv, ...)
Arguments are supplied to the program if this is allowed by the operating system. In C, the MPI_COMM_SPAWN argument argv differs from the argv argument of main in two respects. First, it is shifted by one element. Specifically, argv[0] of main is provided by the implementation and conventionally contains the name of the program (given by command). argv[1] of main corresponds to argv[0] in MPI_COMM_SPAWN, argv[2] of main to argv[1] of MPI_COMM_SPAWN, etc. Second, argv of MPI_COMM_SPAWN must be null-terminated, so that its length can be determined. Passing an argv of MPI_ARGV_NULL to MPI_COMM_SPAWN results in main receiving argc of 1 and an argv whose element 0 is (conventionally) the name of the program.
If a Fortran implementation supplies routines that allow a program to obtain its arguments, the arguments may be available through that mechanism. In C, if the operating system does not support arguments appearing in argv of main(), the MPI implementation may add the arguments to the argv that is passed to MPI_INIT.
The maxprocs argument MPI tries to spawn maxprocs processes. If it is unable to spawn maxprocs processes, it raises an error of class MPI_ERR_SPAWN.
An implementation may allow the info argument to change
the default behavior, such that if the implementation is
unable to spawn all maxprocs processes, it may
spawn a smaller number of processes instead of raising
an error. In principle, the info
argument may specify an arbitrary set 
of allowed values for the number of
processes spawned. The set {mi} does not necessarily
include the value maxprocs. If an implementation
is able to spawn one of these allowed numbers of processes,
MPI_COMM_SPAWN returns successfully
and the number of spawned processes, m,
is given by the size of the remote group of intercomm.
If m is less than
maxproc, reasons why the other processes
were not spawned are given in array_of_errcodes
as described below. If it is
not possible to spawn one of the allowed numbers of processes,
MPI_COMM_SPAWN raises an
error of class MPI_ERR_SPAWN.
A spawn call with the default behavior is called hard. A spawn call for which fewer than maxprocs processes may be returned is called soft. See Section Reserved Keys for more information on the soft key for info.
Advice to users.
By default, requests are hard and MPI errors are fatal. This means
that by default there will be a fatal error if MPI cannot
spawn all the requested processes. If you want the behavior
``spawn as many processes as possible, up to N,'' you
should do a soft spawn, where the set of allowed values {mi}
is {0 ... N}. However, this is not completely portable,
as implementations are not required to support soft spawning.
( End of advice to users.)
The info argument The info argument to all of the routines in this chapter is an opaque handle of type MPI_Info in C, MPI::Info in C++ and INTEGER in Fortran. It is a container for a number of user-specified ( key, value) pairs. key and value are strings (null-terminated char* in C, character*(*) in Fortran). Routines to create and manipulate the info argument are described in Section The Info Object .
For the SPAWN calls, info provides additional (and possibly 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.
MPI does not specify the content of the info argument, except to reserve a number of special key values (see Section Reserved Keys ). The info argument is quite flexible and could even be used, for example, to specify the executable and its command-line arguments. In this case the command argument to MPI_COMM_SPAWN could be empty. The ability to do this follows from the fact that MPI does not specify how an executable is found, and the info argument can tell the runtime system where to ``find'' the executable ``'' (empty string). Of course a program that does this will not be portable across MPI implementations.
The root argument All arguments before the root argument are examined only on the process whose rank in comm is equal to root. The value of these arguments on other processes is ignored.
The array_of_errcodes argument The array_of_errcodes is an array of length maxprocs
in which MPI reports the status of each process that
MPI was requested to start. If all maxprocs processes were spawned,
array_of_errcodes is filled in with the value
MPI_SUCCESS. If only m (
)
processes are spawned, m of the entries will contain
MPI_SUCCESS and the rest will contain
an implementation-specific error code indicating the
reason MPI could not start the process. MPI does not
specify which entries correspond to failed processes.
An implementation may, for instance, fill in
error codes in one-to-one correspondence with
a detailed specification in the info
argument. These error codes
all belong to the error class MPI_ERR_SPAWN
if there was no error in the argument list.
In C or Fortran, an application may pass MPI_ERRCODES_IGNORE
if it is not interested in the error codes. In C++ this constant does
not exist, and the array_of_errcodes argument may be
omitted from the argument list.
Advice
to implementors.
MPI_ERRCODES_IGNORE in Fortran is a special type
of constant, like MPI_BOTTOM.
See the discussion in Section Named Constants
.
( End of advice to implementors.)
| MPI_COMM_GET_PARENT(parent) | |
| OUT parent | the parent communicator (handle) |
If a process was started with MPI_COMM_SPAWN or MPI_COMM_SPAWN_MULTIPLE, MPI_COMM_GET_PARENT returns the ``parent'' intercommunicator of the current process. This parent intercommunicator is created implicitly inside of MPI_INIT and is the same intercommunicator returned by SPAWN in the parents.
If the process was not spawned, MPI_COMM_GET_PARENT returns MPI_COMM_NULL.
After the parent communicator is freed or disconnected, MPI_COMM_GET_PARENT returns MPI_COMM_NULL.
Advice to users.
MPI_COMM_GET_PARENT returns a handle to a single intercommunicator.
Calling MPI_COMM_GET_PARENT a second time returns a handle
to the same intercommunicator. Freeing the handle with MPI_COMM_DISCONNECT
or MPI_COMM_FREE will cause other references to
the intercommunicator to become invalid (dangling).
Note that calling MPI_COMM_FREE on the parent
communicator is not useful.
( End of advice to users.)
Rationale.
The desire of the Forum was to create a constant MPI_COMM_PARENT
similar to MPI_COMM_WORLD. Unfortunately such a constant cannot
be used (syntactically) as an argument to MPI_COMM_DISCONNECT,
which is explicitly allowed.
( End of rationale.)