Minor
[charm.git] / doc / charm++ / mpi-interop.tex
index 5476280e654b91fc753fcbd3f69d18043041d139..b34442b33b9f6ff15c0a49c09599afb9f4467aca 100644 (file)
@@ -1,44 +1,44 @@
-Libraries written in Charm++ can also be used with pure MPI programs. Currently this
-functionality is supported only if Charm is built using MPI as the network layer
+Libraries written in \charmpp{} can also be used with pure MPI programs. Currently this
+functionality is supported only if \charmpp{} is built using MPI as the network layer
 (e.g. mpi-linux-x86\_64 build). An example program to demonstrate the
 interoperation is available in examples/charm++/mpi-coexist. We will be
 referring to this example program for ease of understanding.
 
 \section{Control Flow and Memory Structure}
-The control flow and memory structure of a Charm-MPI interoperable program  is
+The control flow and memory structure of a \charmpp{}-MPI interoperable program  is
 similar to that of a pure MPI program that uses external MPI libraries. The
 execution of program begins with pure MPI code's {\em main}. At some point after 
 MPI\_Init() has been invoked, the following function call should be made to initialize
-Charm: \\
+\charmpp{}: \\
 
 {\bf void CharmLibInit(MPI\_Comm newComm, int argc, char **argv)}\\
 
-\noindent Here, {\em newComm} is the MPI communicator that Charm will use for
+\noindent Here, {\em newComm} is the MPI communicator that \charmpp{} will use for
 the setup and communication. All the MPI ranks that belong to {\em newComm} should 
 make this call. A collection of MPI ranks that make the CharmLibInit call defines a 
-new Charm instance. Different MPI ranks that belong to different communicators can 
-make this call independently, and separate Charm instances (that are not aware of each other) 
-will be created. As of now, a particular MPI rank can only be part of one unique Charm 
-instance. Arguments {\em argc and argv} should contain the information required by Charm 
+new \charmpp{} instance. Different MPI ranks that belong to different communicators can 
+make this call independently, and separate \charmpp{} instances (that are not aware of each other) 
+will be created. As of now, a particular MPI rank can only be part of one unique \charmpp{} 
+instance. Arguments {\em argc and argv} should contain the information required by \charmpp{} 
 such as the load balancing strategy etc.
 
-During the initialization the control is transferred from MPI to Charm
-RTS on the MPI ranks that made the call. Along with basic setup, Charm RTS also invokes
+During the initialization the control is transferred from MPI to \charmpp{}
+RTS on the MPI ranks that made the call. Along with basic setup, \charmpp{} RTS also invokes
 the constructors of all mainchares during initialization. Once the intial set up
 is done, control is transferred back to MPI as if returning from a function call. 
-Since Charm initialization is made via a function call from the pure MPI
-program, Charm resides in the same memory space as the pure MPI program. This
-makes transfer of data from MPI to Charm convenient (using pointers).
+Since \charmpp{} initialization is made via a function call from the pure MPI
+program, \charmpp{} resides in the same memory space as the pure MPI program. This
+makes transfer of data from MPI to \charmpp{} convenient (using pointers).
 
-\section{Writing Interoperable Charm Libraries}
-Minor modifications are required to make a Charm program interoperable with a pure
+\section{Writing Interoperable \charmpp{} Libraries}
+Minor modifications are required to make a \charmpp{} program interoperable with a pure
 MPI program:
 \begin{itemize}
-\item An interoperable Charm library should not contain a main module.
-\item {\em CkExit} should be used as one uses {\em return} statement for returning
+\item An interoperable \charmpp{} library should not contain a main module.
+\item {\em CkExit} should be used the same way {\em return} statement is used for returning
 back from a function call. It is advisable to make sure that only one chare
 invokes {\em CkExit}.
-\item Include {\em mpi-interoperate.h} - if not included, invoking CkExit will result 
+\item Include {\em mpi-interoperate.h} - if not included, invoking {\em CkExit} will result 
 in random output.
 \item Since the CharmLibInit call invokes the constructors of mainchares, the
 constructors of mainchares should only perform basic set up such as creation of chare
@@ -49,26 +49,42 @@ initializations in an interface function as demonstrated in the interoperable
 library examples/charm++/mpi-coexist/libs/hello.
 \item Interface functions - Every library needs to define interface function(s) 
 that can be invoked from pure MPI programs, and transfers the control to the 
-Charm RTS. Examples of such interface functions in can be found in hi
-(HiStart), hello (HelloStart) and kNeighbor (kNeighbor) directories in 
+\charmpp{} RTS. The interface functions are simple functions whose task is to
+start work for the \charmpp{} libraries. Here is an example interface function for the
+{\em hello} library. 
+\begin{alltt}
+void HelloStart(int elems)
+\{
+  if(CkMyPe() == 0) \{
+  CkPrintf("HelloStart - Starting lib by calling constructor of MainHello\\n");
+  CProxy\_MainHello mainhello = CProxy\_MainHello::ckNew(elems);
+  \}
+  CsdScheduler(-1);
+\}
+\end{alltt}
+
+This function creates a new chare (mainHello) defined in the {\em hello} library which
+subsequently results in work being done in {\em hello} library.
+More examples of such interface functions can 
+be found in hi (HiStart) and kNeighbor (kNeighbor) directories in 
 examples/charm++/mpi-coexist/libs. Note that a scheduler call {\em
 CsdScheduler(-1)} should be made from the interface functions to start the
-message reception by Charm RTS.
+message reception by \charmpp{} RTS.
 \end{itemize}
 
 \section{Writing Interoperable MPI Programs}
-An MPI program that invokes Charm libraries should include {\em mpi-interoperate.h}. 
+An MPI program that invokes \charmpp{} libraries should include {\em mpi-interoperate.h}. 
 As mentioned earlier, an initialization call, {\em CharmLibInit} is 
-required after invoking MPI\_Init to perform the initial set up of Charm
-It is advisable to call an MPI\_Barrier after a control transfer between Charm 
-and MPI to avoid any side effects. Thereafter, a Charm library can be invoked at
+required after invoking MPI\_Init to perform the initial set up of \charmpp{}
+It is advisable to call an MPI\_Barrier after a control transfer between \charmpp{} 
+and MPI to avoid any side effects. Thereafter, a \charmpp{} library can be invoked at
 any point using the interface functions. One may look at
 examples/charm++/mpi-coexist/multirun.cpp for a working example. Based on the
 way interfaces are defined, a library can be invoked multiple times. In the end,
-one should call {\em CharmLibExit} to free resources reserved by Charm.
+one should call {\em CharmLibExit} to free resources reserved by \charmpp{}.
 
 \section{Compilation}
-An interoperable Charm library can be compiled as usual using {\em charmc}.
+An interoperable \charmpp{} library can be compiled as usual using {\em charmc}.
 Instead of producing an executable in the end, one should create a library (*.a)
 as shown in examples/charm++/mpi-coexist/libs/hi/Makefile. The compilation
 process of the MPI program, however, needs modification. One has to include the