MPI_INIT_THREAD(3)				     Open MPI					MPI_INIT_THREAD(3)

MPI_Init_thread — Initializes the MPI world model

SYNTAX
   C Syntax
	  #include <mpi.h>

	  int MPI_Init_thread(int *argc, char ***argv,
	       int required, int *provided)

   Fortran Syntax
	  USE MPI
	  ! or the older form: INCLUDE 'mpif.h'
	  MPI_INIT_THREAD(REQUIRED, PROVIDED, IERROR)
	       INTEGER REQUIRED, PROVIDED, IERROR

   Fortran 2008 Syntax
	  USE mpi_f08
	  MPI_Init_thread(required, provided, ierror)
	       INTEGER, INTENT(IN) :: required
	       INTEGER, INTENT(OUT) :: provided
	       INTEGER, OPTIONAL, INTENT(OUT) :: ierror

INPUT PARAMETERS
       • argc: C only: Pointer to the number of arguments.

       • argv: C only: Argument vector.

       • required: Desired level of thread support (integer).

OUTPUT PARAMETERS
       • provided: Available level of thread support (integer).

       • ierror: Fortran only: Error status (integer).

DESCRIPTION
       This  routine,  or MPI_Init <#mpi-init>, initializes the MPI world model.  Either of these routines must be
       called before MPI communication routines are called within the MPI world model.	The MPI world model can be
       initialized at most exactly once in the lifetime of an MPI process.  This is different than the MPI session
       model, which can be initialized and finalized multiple times in an MPI process.	 See  MPI_Session_init	<#
       mpi-session-init> and MPI_Session_finalize <#mpi-session-finalize>.

       See  MPI-5.0:11.4.1  <https://www.mpi-forum.org/>  for a list of MPI functionality that is available (e.g.,
       even when the MPI world model has not yet initialized or has already been finalized).

       The MPI world model can	be  initialized	 at  most  once;  subsequent  calls  to	 MPI_Init  <#mpi-init>	or
       MPI_Init_thread are erroneous.

       Alternatively,  instead	of  the	 MPI  world  model,  MPI  applications	can  use  the  sessions model; see
       MPI_Session_init <#mpi-session-init>.

       Upon return, the level of thread support available to the program is set in  provided.  In  Open	 MPI,  the
       value  is  dependent  on	 how  the  library  was configured and built. Note that there is no guarantee that
       provided will be greater than or equal to required.

       Open MPI accepts the C argc and argv arguments to main, but neither modifies, interprets,  nor  distributes
       them:

	  #include <mpi.h>

	  int main(int argv, char *argv[]) {
	      int provided;
	      MPI_Init_thread(&argc, &argv, MPI_THREAD_MULTIPLE, &provided);
	      /* ...body of main MPI pogram... */
	      MPI_Finalize();
	      return 0;
	  }

       MPI_Init_thread	has both a direct and an indirect mechanism to request a specific level of thread support.
       MPI_Init <#mpi-init> only has an indirect mechanism to request a specific level of thread support.

   Direct request of thread level
       MPI_Init_thread has the required parameter, which can be set to any one of the  following  constants  (from
       mpi.h):

       • MPI_THREAD_SINGLE: Indicating that only one thread will execute.

       • MPI_THREAD_FUNNELED:  Indicating  that	 if  the  process  is  multithreaded,  only the thread that called
	 MPI_Init_thread will make MPI calls.

       • MPI_THREAD_SERIALIZED: Indicating that if the process is multithreaded, only one  thread  will	 make  MPI
	 library calls at one time.

       • MPI_THREAD_MULTIPLE:  Indicating  that	 if the process is multithreaded, multiple threads may call MPI at
	 once with no restrictions.

       The values of these constants adhere to the following relationships:

						    \begin{eqnarray}
	   MPI\_THREAD\_SINGLE	   & < & MPI\_THREAD\_FUNNELED \\
	   MPI\_THREAD\_FUNNELED   & < & MPI\_THREAD\_SERIALIZED \\
	   MPI\_THREAD\_SERIALIZED & < & MPI\_THREAD\_MULTIPLE \\ \end{eqnarray}

   Indirect request of thread level
       Both MPI_Init_thread and MPI_Init <#mpi-init> support an indirect method of indicating the required  thread
       level: setting the OMPI_MPI_THREAD_LEVEL environment variable:

       • If  the OMPI_MPI_THREAD_LEVEL environment variable is set at the time MPI_Init <#mpi-init> is invoked, it
	 behaves as if MPI_Init_thread was invoked with the corresponding MPI_THREAD_* constant value  passed  via
	 the required parameter.

       • If  the  OMPI_MPI_THREAD_LEVEL	 environment  variable	is set at the time MPI_Init_thread is invoked, the
	 MPI_THREAD_* constant value corresponding to the environment variable value overrides	the  value  passed
	 via the required parameter.

       The OMPI_MPI_THREAD_LEVEL environment variable can be set to any of the values listed below.
			  ┌──────────────────────────┬──────────────────────────────────────┐
			  │ Value that Open MPI uses │ Allowable values (case-insensitive)  │
			  ├──────────────────────────┼──────────────────────────────────────┤
			  │ MPI_THREAD_SINGLE	     │ MPI_THREAD_SINGLE, SINGLE, 0	    │
			  ├──────────────────────────┼──────────────────────────────────────┤
			  │ MPI_THREAD_FUNNELED	     │ MPI_THREAD_FUNNELED, FUNNELED, 1	    │
			  ├──────────────────────────┼──────────────────────────────────────┤
			  │ MPI_THREAD_SERIALIZED    │ MPI_THREAD_SERIALIZED, SERIALIZED, 2 │
			  ├──────────────────────────┼──────────────────────────────────────┤
			  │ MPI_THREAD_MULTIPLE	     │ MPI_THREAD_MULTIPLE, MULTIPLE, 3	    │
			  └──────────────────────────┴──────────────────────────────────────┘

       Note:
	  In  Open  MPI	 v5.0.8	 and  prior,  only  the	 integer values 0 through 3 were acceptable values for the
	  OMPI_MPI_THREAD_LEVEL environment variable.

	  Starting with Open MPI v5.0.9, the Open MPI community recomends using one of the string name variants.

NOTES
       The Fortran version does not have provisions for argc and argv  and  takes  only	 REQUIRED,  PROVIDED,  and
       IERROR.

       It is the caller’s responsibility to check the value of provided, as it may be less than what was requested
       in required.

       The  MPI Standard does not specify what a program using the MPI world model can do before invoking MPI_Init
       <#mpi-init>  or	MPI_Init_thread	 or  after  invoking  MPI_Finalize  <#mpi-finalize>.  In  the	Open   MPI
       implementation, it should do as little as possible. In particular, avoid anything that changes the external
       state of the program, such as opening files, reading standard input, or writing to standard output.

   MPI_THREAD_MULTIPLE Support
       MPI_THREAD_MULTIPLE  support is included if the environment in which Open MPI was built supports threading.
       You can check the output of ompi_info(1) <#man1-ompi-info> to  see  if  Open  MPI  has  MPI_THREAD_MULTIPLE
       support:

	  shell$ ompi_info | grep "Thread support"
		    Thread support: posix (MPI_THREAD_MULTIPLE: yes, OPAL support: yes, OMPI progress: no, Event lib: yes)
	  shell$

       The  MPI_THREAD_MULTIPLE:  yes  portion	of  the	 above	output	indicates  that Open MPI was compiled with
       MPI_THREAD_MULTIPLE support.

       Note that there is a small performance penalty for using MPI_THREAD_MULTIPLE support; latencies	for  short
       messages will be higher as compared to when using MPI_THREAD_SINGLE, for example.

ERRORS
       Almost  all MPI routines return an error value; C routines as the return result of the function and Fortran
       routines in the last argument.

       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 MPI_Init <#mpi-init>/MPI_Init_thread, after MPI_Finalize <#
       mpi-finalize>, or when using the Sessions Model exclusively) the error raises the  initial  error  handler.
       The  initial  error handler can be changed by calling MPI_Comm_set_errhandler <#mpi-comm-set-errhandler> on
       MPI_COMM_SELF when using the World model, or the mpi_initial_errhandler CLI argument to mpiexec or info key
       to  MPI_Comm_spawn  <#mpi-comm-spawn>/MPI_Comm_spawn_multiple  <#mpi-comm-spawn-multiple>.   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.

       Open MPI includes three predefined error handlers that can be used:

       • MPI_ERRORS_ARE_FATAL Causes the program to abort all connected MPI processes.

       • MPI_ERRORS_ABORT An error handler that can be invoked on a communicator, window, file, or  session.  When
	 called on a communicator, it acts as if MPI_Abort <#mpi-abort> was called on that communicator. If called
	 on  a window or file, acts as if MPI_Abort <#mpi-abort> 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.

       • MPI_ERRORS_RETURN Returns an error code to the application.

       MPI applications can also implement their own error handlers by calling:

       • MPI_Comm_create_errhandler	<#mpi-comm-create-errhandler>	  then	   MPI_Comm_set_errhandler	<#
	 mpi-comm-set-errhandler>

       • MPI_File_create_errhandler	 <#mpi-file-create-errhandler>	   then	    MPI_File_set_errhandler	<#
	 mpi-file-set-errhandler>

       • MPI_Session_create_errhandler	 <#mpi-session-create-errhandler>   then   MPI_Session_set_errhandler	<#
	 mpi-session-set-errhandler> or at MPI_Session_init <#mpi-session-init>

       • MPI_Win_create_errhandler	<#mpi-win-create-errhandler>	  then	    MPI_Win_set_errhandler	<#
	 mpi-win-set-errhandler>

       Note that MPI does not guarantee that an MPI program can continue past an error.

       See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors>.

       See the Error Handling section of the MPI-3.1 standard for more information.

       See also:

	  • MPI_Init <#mpi-init>

	  • MPI_Initialized <#mpi-initialized>

	  • MPI_Finalize <#mpi-finalize>

	  • MPI_Finalized <#mpi-finalized>

	  • MPI_Session_finalize <#mpi-session-finalize>

	  • MPI_Session_init <#mpi-session-init>

Copyright
       2003-2026, The Open MPI Community

						   Mar 05, 2026					MPI_INIT_THREAD(3)
