208. Startup

Up: Contents Next: Allowing User Functions at Process Termination Previous: Timers and Synchronization

One goal of MPI is to achieve source code portability. By this we mean that a program written using MPI and complying with the relevant language standards is portable as written, and must not require any source code changes when moved from one system to another. This explicitly does not say anything about how an MPI program is started or launched from the command line, nor what the user must do to set up the environment in which an MPI program will run. However, an implementation may require some setup to be performed before other MPI routines may be called. To provide for this, MPI includes an initialization routine MPI_INIT.

Image file

int MPI_Init(int *argc, char ***argv)


All MPI programs must contain exactly one call to an MPI initialization routine: MPI_INIT or MPI_INIT_THREAD. Subsequent calls to any initialization routines are erroneous. The only MPI functions that may be invoked before the MPI initialization routines are called are MPI_GET_VERSION, MPI_GET_LIBRARY_VERSION, MPI_INITIALIZED, MPI_FINALIZED, and any function with the prefix MPI_T_ (within the constraints for functions with this prefix listed in Section Initialization and Finalization ). The version for ISO C accepts the argc and argv that are provided by the arguments to main or NULL:

int main(int argc, char *argv[]) 
    MPI_Init(&argc, &argv); 
    /* parse arguments */ 
    /* main program    */ 
    MPI_Finalize();     /* see below */ 
    return 0;  
The Fortran version takes only IERROR.

Conforming implementations of MPI are required to allow applications to pass NULL for both the argc and argv arguments of main in C.

After MPI is initialized, the application can access information about the execution environment by querying the predefined info object MPI_INFO_ENV. The following keys are predefined for this object, corresponding to the arguments of MPI_COMM_SPAWN or of mpiexec:

Name of program executed.
Space separated arguments to command.
Maximum number of MPI processes to start.
Allowed values for number of processors.

Architecture name.
Working directory of the MPI process.
Value is the name of a file in which additional information is specified.
Requested level of thread support, if requested before the program started execution.

Note that all values are strings. Thus, the maximum number of processes is represented by a string such as ``1024'' and the requested level is represented by a string such as ``MPI_THREAD_SINGLE''.

The info object MPI_INFO_ENV need not contain a (key,value) pair for each of these predefined keys; the set of (key,value) pairs provided is implementation-dependent. Implementations may provide additional, implementation specific, (key,value) pairs.

In case where the MPI processes were started with MPI_COMM_SPAWN_MULTIPLE or, equivalently, with a startup mechanism that supports multiple process specifications, then the values stored in the info object MPI_INFO_ENV at a process are those values that affect the local MPI process.

Example If MPI is started with a call to

    mpiexec -n 5 -arch sun ocean : -n 10 -arch rs6000 atmos 
Then the first 5 processes will have have in their MPI_INFO_ENV object the pairs (command, ocean), (maxprocs, 5), and (arch, sun). The next 10 processes will have in MPI_INFO_ENV (command, atmos), (maxprocs, 10), and (arch, rs6000)

Advice to users.

The values passed in MPI_INFO_ENV are the values of the arguments passed to the mechanism that started the MPI execution --- not the actual value provided. Thus, the value associated with maxprocs is the number of MPI processes requested; it can be larger than the actual number of processes obtained, if the soft option was used. ( End of advice to users.)

Advice to implementors.

High-quality implementations will provide a (key,value) pair for each parameter that can be passed to the command that starts an MPI program. ( End of advice to implementors.)

Image file

int MPI_Finalize(void)


This routine cleans up all MPI state. If an MPI program terminates normally (i.e., not due to a call to MPI_ABORT or an unrecoverable error) then each process must call MPI_FINALIZE before it exits.

Before an MPI process invokes MPI_FINALIZE, the process must perform all MPI calls needed to complete its involvement in MPI communications: It must locally complete all MPI operations that it initiated and must execute matching calls needed to complete MPI communications initiated by other processes. For example, if the process executed a nonblocking send, it must eventually call MPI_WAIT, MPI_TEST, MPI_REQUEST_FREE, or any derived function; if the process is the target of a send, then it must post the matching receive; if it is part of a group executing a collective operation, then it must have completed its participation in the operation.

The call to MPI_FINALIZE does not free objects created by MPI calls; these objects are freed using MPI_ XXX_FREE calls.

MPI_FINALIZE is collective over all connected processes. If no processes were spawned, accepted or connected then this means over MPI_COMM_WORLD; otherwise it is collective over the union of all processes that have been and continue to be connected, as explained in Section Releasing Connections .

The following examples illustrates these rules

Example The following code is correct

        Process 0                Process 1 
        ---------                --------- 
        MPI_Init();              MPI_Init(); 
        MPI_Send(dest=1);        MPI_Recv(src=0); 
        MPI_Finalize();          MPI_Finalize(); 

Example Without a matching receive, the program is erroneous

        Process 0                Process 1 
        -----------              ----------- 
        MPI_Init();              MPI_Init(); 
        MPI_Send (dest=1); 
        MPI_Finalize();          MPI_Finalize(); 

Example This program is correct: Process 0 calls MPI_Finalize after it has executed the MPI calls that complete the send operation. Likewise, process 1 executes the MPI call that completes the matching receive operation before it calls MPI_Finalize.

  Process 0                     Proces 1 
  --------                      -------- 
  MPI_Init();                   MPI_Init();  
  MPI_Isend(dest=1);            MPI_Recv(src=0); 
  MPI_Request_free();           MPI_Finalize(); 
  MPI_Finalize();               exit(); 

Example This program is correct. The attached buffer is a resource allocated by the user, not by MPI; it is available to the user after MPI is finalized.

   Process 0                     Process 1 
   ---------                     --------- 
   MPI_Init();                  MPI_Init(); 
   buffer = malloc(1000000);    MPI_Recv(src=0); 
   MPI_Buffer_attach();         MPI_Finalize(); 
   MPI_Send(dest=1));           exit(); 

Example This program is correct. The cancel operation must succeed, since the send cannot complete normally. The wait operation, after the call to MPI_Cancel, is local --- no matching MPI call is required on process 1.

   Process 0                    Process 1 
   ---------                    --------- 
   MPI_Issend(dest=1);          MPI_Finalize(); 

Advice to implementors.

Even though a process has executed all MPI calls needed to complete the communications it is involved with, such communication may not yet be completed from the viewpoint of the underlying MPI system. For example, a blocking send may have returned, even though the data is still buffered at the sender in an MPI buffer; an MPI process may receive a cancel request for a message it has completed receiving. The MPI implementation must ensure that a process has completed any involvement in MPI communication before MPI_FINALIZE returns. Thus, if a process exits after the call to MPI_FINALIZE, this will not cause an ongoing communication to fail. The MPI implementation should also complete freeing all objects marked for deletion by MPI calls that freed them. ( End of advice to implementors.)
Once MPI_FINALIZE returns, no MPI routine (not even MPI_INIT) may be called, except for MPI_GET_VERSION, MPI_GET_LIBRARY_VERSION, MPI_INITIALIZED, MPI_FINALIZED, and any function with the prefix MPI_T_ (within the constraints for functions with this prefix listed in Section Initialization and Finalization ).

Although it is not required that all processes return from MPI_FINALIZE, it is required that at least process 0 in MPI_COMM_WORLD return, so that users can know that the MPI portion of the computation is over. In addition, in a POSIX environment, users may desire to supply an exit code for each process that returns from MPI_FINALIZE.

Example The following illustrates the use of requiring that at least one process return and that it be known that process 0 is one of the processes that return. One wants code like the following to work no matter how many processes return.

    MPI_Comm_rank(MPI_COMM_WORLD, &myrank); 
    if (myrank == 0) { 
        resultfile = fopen("outfile","w"); 

lag is true if MPI_INIT has been called and false otherwise.
OUT flagF

int MPI_Initialized(int *flag)

MPI_Initialized(flag, ierror)

This routine may be used to determine whether MPI_INIT has been called. MPI_INITIALIZED returns true if the calling process has called MPI_INIT. Whether MPI_FINALIZE has been called does not affect the behavior of MPI_INITIALIZED. It is one of the few routines that may be called before MPI_INIT is called. This function must always be thread-safe, as defined in Section MPI and Threads .

MPI_ABORT(comm, errorcode)
IN commcommunicator of tasks to abort
IN errorcodeerror code to return to invoking environment

int MPI_Abort(MPI_Comm comm, int errorcode)

MPI_Abort(comm, errorcode, ierror)
TYPE(MPI_Comm), INTENT(IN) :: comm
INTEGER, INTENT(IN) :: errorcode

This routine makes a ``best attempt'' to abort all tasks in the group of comm. This function does not require that the invoking environment take any action with the error code. However, a Unix or POSIX environment should handle this as a return errorcode from the main program.

It may not be possible for an MPI implementation to abort only the processes represented by comm if this is a subset of the processes. In this case, the MPI implementation should attempt to abort all the connected processes but should not abort any unconnected processes. If no processes were spawned, accepted, or connected then this has the effect of aborting all the processes associated with MPI_COMM_WORLD.


The communicator argument is provided to allow for future extensions of MPI to environments with, for example, dynamic process management. In particular, it allows but does not require an MPI implementation to abort a subset of MPI_COMM_WORLD. ( End of rationale.)

Advice to users.

Whether the errorcode is returned from the executable or from the MPI process startup mechanism (e.g., mpiexec), is an aspect of quality of the MPI library but not mandatory. ( End of advice to users.)

Advice to implementors.

Where possible, a high-quality implementation will try to return the errorcode from the MPI process startup mechanism (e.g. mpiexec or singleton init). ( End of advice to implementors.)

Up: Contents Next: Allowing User Functions at Process Termination Previous: Timers and Synchronization

Return to MPI-3.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-3.1 of June 4, 2015
HTML Generated on June 4, 2015