The following function may be used to initialize MPI, and initialize the MPI thread environment, instead of MPI_INIT.
| MPI_INIT_THREAD(required, provided) | |
| IN required | desired level of thread support (integer) |
| OUT provided | provided level of thread support (integer) |
int MPI_Init_thread(int *argc, char *((*argv)[]), int required, int *provided)
MPI_INIT_THREAD(REQUIRED, PROVIDED, IERROR)
INTEGER REQUIRED, PROVIDED, IERROR
{ int MPI::Init_thread(int& argc, char**& argv, int required) (binding deprecated, see Section Deprecated since MPI-2.2
) }
In C and C++, the passing of argc and argv is
optional.
In C, this is accomplished by passing the appropriate null pointer.
In C++, this is accomplished with two separate bindings to
cover these two cases.
This is as with MPI_INIT as discussed in
Section Startup
.
( End of advice to users.)
This call initializes MPI in the same way that a call to MPI_INIT
would. In addition, it
initializes the thread environment. The argument required
is used to specify the desired level of thread support.
The possible values are listed in increasing order of thread support.
Different processes in MPI_COMM_WORLD may require different
levels of thread support.
The call returns in provided information about the actual
level of thread support that will be provided by MPI. It can be one of the
four values listed above.
The level(s) of thread support that can be provided by
MPI_INIT_THREAD will
depend on the implementation, and may depend on information provided
by the user before the program started to execute (e.g., with
arguments to mpiexec). If possible, the call will return
provided = required. Failing this, the call will return the
least supported level such that provided > required (thus providing
a stronger level of support than required by the user). Finally, if the user
requirement cannot be satisfied, then the call will return
in provided the highest supported level.
A thread compliant MPI implementation will be able to return
provided
A call to MPI_INIT has the same effect as a
call to MPI_INIT_THREAD with a required =
MPI_THREAD_SINGLE.
Vendors may provide (implementation
dependent) means to specify the level(s) of thread support available when the MPI
program is started, e.g., with arguments to mpiexec. This
will affect the outcome of calls to MPI_INIT and
MPI_INIT_THREAD. Suppose, for example, that an MPI
program has been started so that only MPI_THREAD_MULTIPLE is
available. Then MPI_INIT_THREAD will return
provided = MPI_THREAD_MULTIPLE, irrespective of the value
of required; a call to MPI_INIT will also
initialize the MPI thread support level to
MPI_THREAD_MULTIPLE. Suppose, on the other hand, that an
MPI program has been started so that all four levels of thread
support are available. Then, a call to MPI_INIT_THREAD
will return provided = required; on the other hand, a call to
MPI_INIT will initialize the MPI thread support level to
MPI_THREAD_SINGLE.
Various optimizations are possible when MPI code is executed
single-threaded, or is executed on multiple threads, but not
concurrently: mutual exclusion code may be omitted. Furthermore, if only one
thread executes, then the MPI library can use library functions that
are not thread safe, without risking conflicts with user threads.
Also, the model
of one communication thread, multiple computation threads fits
many applications well, e.g.,
if the process code is a sequential
Fortran/C/C++ program with MPI calls that has been parallelized by a
compiler for execution on an SMP node, in a cluster of SMPs,
then the process computation is
multi-threaded, but MPI calls will likely execute on a single
thread.
The design accommodates a static specification of the thread support
level, for environments that require static binding of libraries, and
for compatibility for current multi-threaded MPI codes.
( End of rationale.)
If provided is not MPI_THREAD_SINGLE then the MPI
library should not
invoke C/ C++/Fortran library calls that are
not thread safe, e.g., in an environment where malloc is not thread
safe, then malloc should not be used by the MPI library.
Some implementors may want to use different MPI libraries for
different levels of thread support. They can do so using dynamic
linking and selecting which library will be linked when
MPI_INIT_THREAD is invoked.
If this is not possible, then optimizations for lower levels
of thread support will occur only when the level of thread support required
is specified at link time.
( End of advice to implementors.)
int MPI_Query_thread(int *provided)
MPI_QUERY_THREAD(PROVIDED, IERROR)
{ int MPI::Query_thread() (binding deprecated, see Section Deprecated since MPI-2.2
) }
The call returns in provided the current level of thread
support. This will be the value returned in provided by
MPI_INIT_THREAD, if MPI
was initialized by a call to MPI_INIT_THREAD().
int MPI_Is_thread_main(int *flag)
MPI_IS_THREAD_MAIN(FLAG, IERROR)
{ bool MPI::Is_thread_main() (binding deprecated, see Section Deprecated since MPI-2.2
) }
This function can be called by a thread to find out whether it is the
main thread (the thread that called MPI_INIT or
MPI_INIT_THREAD).
All routines listed in this section
must be
supported by all MPI implementations.
MPI libraries are required to provide these calls even if they do
not support threads, so that portable code that contains invocations
to these functions be able to link correctly. MPI_INIT
continues to be
supported so as to provide compatibility with current MPI codes.
( End of rationale.)
It is possible to spawn threads before MPI is initialized, but no
MPI call other than MPI_INITIALIZED should be executed by these
threads, until MPI_INIT_THREAD is invoked by one
thread (which, thereby, becomes the main thread). In particular, it is
possible to enter the MPI execution with a multi-threaded process.
The level of thread support provided is a global property of the MPI
process that can be specified only once, when MPI is initialized on
that process (or before). Portable third party libraries have to be written so as to
accommodate any provided level of thread support.
Otherwise, their usage will be restricted to specific level(s) of thread support.
If such a library can run only with specific level(s) of thread support, e.g.,
only with MPI_THREAD_MULTIPLE, then
MPI_QUERY_THREAD can be used to check whether the
user initialized MPI to the correct level of thread support and,
if not, raise an exception.
( End of advice to users.)
{ int MPI::Init_thread(int required) (binding deprecated, see Section Deprecated since MPI-2.2
) }
Advice to users.
These values are monotonic; i.e.,
MPI_THREAD_SINGLE < MPI_THREAD_FUNNELED
< MPI_THREAD_SERIALIZED < MPI_THREAD_MULTIPLE.
= MPI_THREAD_MULTIPLE.
Such an implementation may always return
provided
= MPI_THREAD_MULTIPLE, irrespective of the value
of required.
At the other extreme, an MPI library that is not thread compliant
may always return provided = MPI_THREAD_SINGLE,
irrespective of the value of required.
Rationale.
Advice
to implementors.
The following function can be used to query the current level of thread
support.
MPI_QUERY_THREAD(provided) OUT provided provided level of thread support (integer)
INTEGER PROVIDED, IERROR
MPI_IS_THREAD_MAIN(flag) OUT flag true if calling thread is main thread, false
otherwise (logical)
LOGICAL FLAG
INTEGER IERROR
Rationale.
Advice to users.
Up: MPI and Threads
Next: I/O
Previous: Clarifications
Return to MPI-2.2 Standard Index
Return to MPI Forum Home Page
(Unofficial) MPI-2.2 of September 4, 2009
HTML Generated on September 10, 2009