% -*- latex -*-


\setDate{August  9, 2010}
% The following must all be on one line for latex2man to work.
\begin{Name}{3}{icetCreateMPICommunicator}{Kenneth Moreland}{\IceT Reference}{\CFunc{icetCreateMPICommunicator} -- Converts an MPI communicator to an \IceT communicator.}

  \mansection{Synopsis}

  \textC{\#include <IceTMPI.h>}

  \begin{Table}{3}
    \CType{IceTCommunicator}\textC{ }\CFunc{icetCreateMPICommunicator}\textC{(} \\
    \qquad\qquad\qquad\qquad\qquad\qquad\qquad\qquad\qquad\qquad\qquad
    \CTypeExternal{MPI\_Comm}\quad\CArg{mpi\_comm}\quad\textC{);}
  \end{Table}


  \mansection{Description}

  \IceT requires a communicator in order to perform correctly.  An
  application is free to build its own communicator, but many will simply
  prefer to use MPI, which is a well established parallel communication
  tool.  Thus, \IceT comes with an implementation of
  \CType{IceTCommunicator} that uses the MPI communication layer
  underneath.

  \CFunc{icetCreateMPICommunicator} is used to create an
  \CType{IceTCommunicator} that uses the \CArg{mpi\_comm} MPI communication
  object.  The resulting \CType{IceTCommunicator} shares the same process
  group and process rank as the original \CTypeExternal{MPI\_Comm}
  communicator.

  \CArg{mpi\_comm} is duplicated, which has two consiquences.  First, all
  process in \CArg{mpi\_comm}'s group may need to call
  \CFunc{icetCreateMPICommunicator} in order for any of them to proceed
  (depending on the MPI implementation).  Second, \CArg{mpi\_comm} and the
  resulting \CType{IceTCommunicator} are decoupled from each other.
  Communications in one cannot affect another.  Also, one communicator may
  be destroyed without affecting the other.


  \mansection{Return Value}

  An \CType{IceTCommunicator} with the same process group and rank as
  \CArg{mpi\_comm}.  The communicator may be destroyed with a call to
  \CFunc{icetDestroyMPICommunicator}.


  \mansection{Errors}

  None.


  \mansection{Warnings}

  None.


  \mansection{Bugs}

  All MPI errors are ignored.


  \mansection{Copyright}
  Copyright \copyright 2003 Sandia Corporation

  @copyright@

  \mansection{See Also}

  \CFuncSeeAlso{icetDestroyMPICommunicator},
  \CFuncSeeAlso{icetCreateContext}

\end{Name}


% These are emacs settings that go at the end of the file.
% Local Variables:
% writestamp-format: "%B %e, %Y"
% writestamp-prefix: "^\\\\setDate{"
% writestamp-suffix: "}$"
% End:
