Adding a section on interoperability
authorNikhil Jain <nikhil@illinois.edu>
Sun, 19 Aug 2012 20:29:19 +0000 (15:29 -0500)
committerNikhil Jain <nikhil@illinois.edu>
Sun, 19 Aug 2012 20:29:19 +0000 (15:29 -0500)
doc/charm++/intro.tex
doc/charm++/manual.tex
doc/charm++/mpi-interop.tex [new file with mode: 0644]

index c53e42d38a9e67f1b1138ab5d4352dae757ad3d8..2653b711d4ca2a7c8eabd50c1afced3a88a17ac8 100644 (file)
@@ -22,9 +22,11 @@ BlueGene/Q, Cray XT, XE and XK series (including XK6 and XE6),
 a single workstation or a network of workstations (including x86
 (running Linux, Windows, MacOS)), etc.  The communication protocols
 and infrastructures supported by
-\charmpp\ are UDP, TCP, Myrinet, Infiniband, uGNI, and PAMI. 
+\charmpp\ are UDP, TCP, Myrinet, Infiniband, MPI, uGNI, and PAMI. 
 \charmpp\ programs can run without changing the source
-on all these platforms.  Please see the \charmpp{}/\converse{}
+on all these platforms. If built on MPI, \charmpp{} programs can 
+also interoperate with pure MPI programs (\S\ref{sec:interop}).
+  Please see the \charmpp{}/\converse{}
 Installation and Usage
 \htmladdnormallink{Manual}{http://charm.cs.illinois.edu/manuals/html/install/manual.html}
 for details about installing, compiling and running
index 51459c0eb440f244d2ce6012d7a600572103ca9f..36fea1b9aea7366be833fbf26194c572d8b74792 100644 (file)
   \input{ckloop}
 }
 
+\chapter{Charm-MPI Interoperation}
+\index{MPI Interoperation}
+\label{sec:interop}
+  \input{mpi-interop}
+
 \part{Appendix}
 \appendix
 
diff --git a/doc/charm++/mpi-interop.tex b/doc/charm++/mpi-interop.tex
new file mode 100644 (file)
index 0000000..5476280
--- /dev/null
@@ -0,0 +1,84 @@
+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
+(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
+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: \\
+
+{\bf void CharmLibInit(MPI\_Comm newComm, int argc, char **argv)}\\
+
+\noindent Here, {\em newComm} is the MPI communicator that Charm 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 
+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
+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).
+
+\section{Writing Interoperable Charm Libraries}
+Minor modifications are required to make a Charm 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
+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 
+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
+arrays etc. The set up should not result in invocation of actual work, which
+should be done using interface functions (when desired from the pure MPI
+program). One may avoid use of mainchares, and perform the necessary
+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 
+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.
+\end{itemize}
+
+\section{Writing Interoperable MPI Programs}
+An MPI program that invokes Charm 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
+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.
+
+\section{Compilation}
+An interoperable Charm 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
+charm directory (-I\$(CHARMDIR)/include) to help the compiler find the location of
+included {\em mpi-interoperate.h}. The linking step to create the executable
+should be done using {\em charmc}, which in turn uses the compiler used to build
+charm. In the linking step, it is required to pass {\em -mpi} as an argument
+because of which {\em charmc} performs the linking for interoperation. The charm
+libraries, which one wants to be linked, should be passed using {\em -module}
+option. Refer to examples/charm++/mpi-coexist/Makefile to view a working
+example.
+
+