1MPI_Init(3) LAM/MPI MPI_Init(3)
2
6 MPI_Init - Initialize the MPI execution environment
7
9 #include <mpi.h>
10 int MPI_Init(int *pargc, char ***pargv)
11
13 pargc - Pointer to the number of arguments
14 pargv - Pointer to the argument vector
15
18 MPI specifies no command-line arguments but does allow an MPI implemen‐
19 tation to make use of them. LAM/MPI neither uses nor adds any values
20 to the argc and argv parameters. As such, it is legal to pass NULL for
21 both argc and argv in LAM/MPI.
22 Instead, LAM/MPI relies upon the mpirun command to pass meta-informa‐
24 tion between nodes in order to start MPI programs (of course, the LAM
25 daemons must have previously been launched with the lamboot command).
26 As such, every rank in MPI_COMM_WORLD will receive the argc and argv
27 that was specified with the mpirun command (either via the mpirun com‐
28 mand line or an app schema) as soon as main begins. See the mpirun (1)
29 man page for more information.
30 If mpirun is not used to start MPI programs, the resulting process will
32 be rank 0 in MPI_COMM_WORLD , and MPI_COMM_WORLD will have a size of 1.
33 This is known as a "singleton" MPI. It should be noted that LAM dae‐
34 mons are still used for singleton MPI programs - lamboot must still
35 have been successfully executed before running a singleton process.
36 LAM/MPI takes care to ensure that the normal Unix process model of exe‐
38 cution is preserved: no extra threads or processes are forked from the
39 user's process. Instead, the LAM daemons are used for all process man‐
40 agement and meta-environment information. Consequently, LAM/MPI places
41 no restriction on what may be invoked before MPI_INIT* or after
42 MPI_FINALIZE ; this is not a safe assumption for those attempting to
43 write portable MPI programs - see "Portability Concerns", below.
44 MPI mandates that the same thread must call MPI_INIT (or
46 MPI_INIT_THREAD ) and MPI_FINALIZE .
47 Note that the Fortran binding for this routine has only the error
50 return argument ( MPI_INIT(ierror) ).
51 Because the Fortran and C versions of MPI_INIT are different, there is
53 a restriction on who can call MPI_INIT . The version (Fortran or C)
54 must match the main program. That is, if the main program is in C,
55 then the C version of MPI_INIT must be called. If the main program is
56 in Fortran, the Fortran version must be called.
57 LAM/MPI uses the value of argv[0] to identify a process in many of the
59 user-level helper applications (mpitask and mpimsg, for example). For‐
60 tran programs are generally identified as "LAM_MPI_Fortran_program".
61 However, this name can be overridden for Fortran programs by setting
62 the environment variable "LAM_MPI_PROCESS_NAME".
63 On exit from this routine, all processes will have a copy of the argu‐
65 ment list. This is not required by the MPI standard, and truely porta‐
66 ble codes should not rely on it. This is provided as a service by this
67 implementation (an MPI implementation is allowed to distribute the com‐
68 mand line arguments but is not required to).
69
72 Applications using MPI_INIT are effectively invoking MPI_INIT_THREAD
73 with a requested thread support of MPI_THREAD_SINGLE . However, this
74 may be overridden with the LAM_MPI_THREAD_LEVEL environment variable.
75 If set, this variable replaces the default MPI_THREAD_SINGLE value.
76 The following values are allowed
77 0: Corresponds to MPI_THREAD_SINGLE
79 1: Corresponds to MPI_THREAD_FUNNELED
81 2: Corresponds to MPI_THREAD_SERIALIZED
83 3: Corresponds to MPI_THREAD_MULTIPLE
85 See MPI_Init_thread(3) for more information on thread level support in
87 LAM/MPI.
88
91 LAM/MPI defines all required predefined attributes on MPI_COMM_WORLD .
92 Some values are LAM-specific, and require explanation.
93 MPI_UNIVERSE_SIZE
95 This is an MPI-required attribute. It is set to an integer whose value
97 indicates how many CPUs LAM was booted with. See bhost(5) and lam‐
98 boot(1) for more details on how to specify multiple CPUs per node.
99 Note that this may be larger than the number of CPUs in MPI_COMM_WORLD
100 .
101 LAM_UNIVERSE_NCPUS
104 This is a LAM-specific attribute -- it will not be defined in other MPI
106 implementations. It is actually just a synonym for MPI_UNIVERSE_SIZE
107 -- it contains the number of CPUs in the current LAM universe. Note
108 that this may be larger than the number of CPUs in MPI_COMM_WORLD .
109 LAM_UNIVERSE_NNODES
112 This is a LAM-specific attribute -- it will not be defined in other MPI
114 implementations. It indicates the total number of nodes in the current
115 LAM universe (which may be different from the total number of CPUs).
116 Node that this may be larger than the number of nodes in MPI_COMM_WORLD
117 .
118
122 The LAM implementation of MPI uses, by default, SIGUSR2 . This may be
123 changed when LAM is compiled, however, with the --with-signal command
124 line switch to LAM's configure script. Consult your system administra‐
125 tor to see if they specified a different signal when LAM was installed.
126 LAM/MPI does not catch any other signals in user code, by default. If
128 a process terminates due to a signal, the mpirun will be notified of
129 this and will print out an appropriate error message and kill the rest
130 of the user MPI application.
131 This behavior can be overridden (mainly for historical reasons) with
133 the "-sigs" flag to mpirun . When "-sigs" is used, LAM/MPI will effec‐
134 tively transfer the signal-handling code from mpirun to the user pro‐
135 gram. Signal handlers will be installed during MPI_INIT (or
136 MPI_INIT_THREAD ) for the purpose of printing error messages before
137 invoking the next signal handler. That is, LAM "chains" its signal
138 handler to be executed before the signal handler that was already set.
139 Therefore, it is safe for users to set their own signal handlers. If
141 they wish the LAM signal handlers to be executed as well, users should
142 set their handlers before MPI_INIT* is invoked.
143 LAM/MPI catches the following signals
145 SIGSEGV , SIGBUS , SIGFPE , SIGILL
147 All other signals are unused by LAM/MPI, and will be passed to their
149 respective signal handlers.
150
153 Portable MPI programs cannot assume the same process model that LAM
154 uses (i.e., essentially the same as POSIX). MPI does not mandate any‐
155 thing before MPI_INIT (or MPI_INIT_THREAD ), nor anything after
156 MPI_FINALIZE executes. Different MPI implementations make different
157 assumptions; some fork auxillary threads and/or processes to "help"
158 with the MPI run-time environment (this may interfere with the con‐
159 structors and destructors of global C++ objects, particularly in the
160 case where using atexit() or onexit(), for example). As such, if you
161 are writing a portable MPI program, you cannot make the same assump‐
162 tions that LAM/MPI does.
163 In general, it is safest to call MPI_INIT (or MPI_INIT_THREAD ) as soon
165 as possible after main begins, and call MPI_FINALIZE immediately before
166 the program is supposed to end. Consult the documentation for each MPI
167 implementation for their intialize and finalize behavior.
168
171 If an error occurs in an MPI function, the current MPI error handler is
172 called to handle it. By default, this error handler aborts the MPI
173 job. The error handler may be changed with MPI_Errhandler_set ; the
174 predefined error handler MPI_ERRORS_RETURN may be used to cause error
175 values to be returned (in C and Fortran; this error handler is less
176 useful in with the C++ MPI bindings. The predefined error handler
177 MPI::ERRORS_THROW_EXCEPTIONS should be used in C++ if the error value
178 needs to be recovered). Note that MPI does not guarantee that an MPI
179 program can continue past an error.
180 All MPI routines (except MPI_Wtime and MPI_Wtick ) return an error
182 value; C routines as the value of the function and Fortran routines in
183 the last argument. The C++ bindings for MPI do not return error val‐
184 ues; instead, error values are communicated by throwing exceptions of
185 type MPI::Exception (but not by default). Exceptions are only thrown
186 if the error value is not MPI::SUCCESS .
187 Note that if the MPI::ERRORS_RETURN handler is set in C++, while MPI
190 functions will return upon an error, there will be no way to recover
191 what the actual error value was.
192 MPI_SUCCESS
193 - No error; MPI routine completed successfully.
194 MPI_ERR_OTHER
195 - This error class is associated with an error code that indi‐
196 cates that an attempt was made to call MPI_INIT a second time.
197 MPI_INIT may only be called once in a program.
198 MPI_ERR_OTHER
199 - Other error; use MPI_Error_string to get more information
200 about this error code.
201
204 MPI_Init_thread, MPI_Finalize, lamboot, mpirun, lamhalt, lamssi
205
208 For more information, please see the official MPI Forum web site, which
209 contains the text of both the MPI-1 and MPI-2 standards. These docu‐
210 ments contain detailed information about each MPI function (most of
211 which is not duplicated in these man pages).
212 http://www.mpi-forum.org/
214
218 The LAM Team would like the thank the MPICH Team for the handy program
219 to generate man pages ("doctext" from ftp://ftp.mcs.anl.gov/pub/sow‐
220 ing/sowing.tar.gz ), the initial formatting, and some initial text for
221 most of the MPI-1 man pages.
222
224 init.c
225LAM/MPI 7.1.2 2/23/2006 MPI_Init(3)