.. _mpi_t_init_thread:

MPI_T_init_thread
=================

.. include_body

:ref:`MPI_T_init_thread` |mdash| Initializes the MPI Tool information interface

.. The following file was automatically generated
.. include:: ./bindings/mpi_t_init_thread.rst

INPUT PARAMETERS
----------------

* ``required``: Desired level of thread support (integer).

OUTPUT PARAMETERS
-----------------

* ``provided``: Available level of thread support (integer).

DESCRIPTION
-----------

MPI_T_init_thread() initializes the MPI tool information interface.
Calls to MPI tool functions are allowed at any point in execution
(including before MPI_Init() and after MPI_Finalize()) as long
as MPI_T_init_thread() has been called at least once and the number
of calls to MPI_T_init_thread() is greater than the number of calls
to MPI_T_finalize(). If at any point in execution the number of
calls to MPI_T_finalize() equals the number of calls to
MPI_T_init_thread() the MPI tool interface will no longer be
available until another call to MPI_T_init_thread().

The ``required`` and ``provided`` thread support levels apply to the
MPI tool information interface only; they are distinct from the thread
support level of the World Model (reported by :ref:`MPI_Query_thread`)
and from each session's ``thread_level`` info key.  The level granted
in ``provided`` is fixed for as long as the interface remains
initialized: additional calls to :ref:`MPI_T_init_thread` while the
interface is initialized only increase the reference count and return
the already-established level.  If another MPI scope (the World Model
or a session) is already active at a lower thread level, a request for
``MPI_THREAD_MULTIPLE`` may be granted ``MPI_THREAD_SERIALIZED``
instead, because the running process cannot be safely upgraded; MPI-5.0
explicitly permits one scope's thread level to influence the level
granted to a later initialization.

MPI_T_init_thread(), like MPI_Init_thread(), has a provision to
request a certain level of thread support in ``required``:

* ``MPI_THREAD_SINGLE``: Only one thread will execute.
* ``MPI_THREAD_FUNNELED``: If the process is multithreaded, only the
  thread that called :ref:`MPI_Init_thread` will make MPI calls.
* ``MPI_THREAD_SERIALIZED``: If the process is multithreaded, only one
  thread will make MPI library calls at one time.
* ``MPI_THREAD_MULTIPLE``: If the process is multithreaded, multiple
  threads may call MPI at once with no restrictions.

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``.

NOTES
-----

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

ERRORS
------

:ref:`MPI_T_init_thread` will fail if:

* ``MPI_T_ERR_MEMORY``: Out of memory
* ``MPI_T_ERR_CANNOT_INIT``: Interface not in the state to be
  initialized


.. seealso::
   * :ref:`MPI_T`
   * :ref:`MPI_Init`
   * :ref:`MPI_Init_thread`
