changed the f90charm manual.
authorGengbin Zheng <gzheng@illinois.edu>
Mon, 2 Apr 2001 01:19:16 +0000 (01:19 +0000)
committerGengbin Zheng <gzheng@illinois.edu>
Mon, 2 Apr 2001 01:19:16 +0000 (01:19 +0000)
doc/f90charm/manual.tex

index f71b552601f9404edb943e33dc2529c51217d07a..925db7e8b91e04b3b7557074979fd34bec072d33 100644 (file)
 
 \pagestyle{headings}
 
-\title{Fortran90 Bindings for Charm++\footnote{last modified 3/3/2001 by Gengbin Zheng}}
+\title{Fortran90 Bindings for Charm++\footnote{last modified 4/1/2001 by Gengbin Zheng}}
 
 \begin{document}
 
 \maketitle
 
-To interface Fortran90 to Charm and thus obtain a parallel version of
-your program you need to do the following things:
+Charm++ is a parallel object language based on C++. The f90charm module is to
+provide Fortran90 programs a f90 interface to Charm++. Using F90Charm interface,
+users can write Fortran90 programs in a fashion simliar to Charm++, which allows
+creation of parallel object arrays(Chare Arrays) and sending messages between 
+them.
+
+To interface Fortran90 to Charm++ and thus obtain a parallel version of your 
+program you need to do the following things:
 \begin{enumerate}
 \item Write a Charm Interface file (extension .ci)
-\item Write your F90 program with some constraints
+\item Write your F90 program with f90charmmain() as main program;
+\item Write implementation of Chare entry functions in f90 program;
 \item Compile and Link with Charm's Fortran library
 \item Run it !
 \end{enumerate}
@@ -61,15 +68,21 @@ You can think of this module as a chare declaration. Type [Hello] defines
 arbitary user program data and HelloPtr defines the Chare pointer which 
 fortran program will use later to communicate with the f90charm runtime 
 library, the [aid] is the handle of array returned by f90charm library, user 
-shouldn't change it.. \\
+shouldn't change it..
+
 As same in C++ charm program, you need to write a .ci interface file
-so that charm translator will generate helper functions. However, for
-Fortran90 charm, the syntax is a little different. First, it only support
-Chare array(1D currently), you cannot define Chare and Group types. Second, 
-for the message declaration, you must list all the data fields explicitly in
-.ci files.  By this, the helper functions generated by translator know the 
-contents of the messages and thus can do the message marshalling and 
-unmarshalling for the fortran program. 
+so that charm translator will generate helper functions. The syntax of .ci files
+are the same as in Charm++, however, for Fortran90 charm, there are certain
+constraints. First, you don't need to declare the main chare as like in Charm++;
+Second, it currently only support 1D Chare array, you cannot define Chare and 
+Group types. Third, there is no message declaration in .ci files, all the entry
+functions must be declared in the parameter marshelling fashion as in Charm++.
+So, what you can do in the .ci files is to define readonly variables and 1D
+chare arrays with parameter marshelling entry functions.
+
+It is programmer's responsibility to write the implementation of chare's
+entry functions. The decl and def files generated by Charm++ translator define
+the interface functions programmer need to write.
 
 For each Chare defined in the .ci file, user must write these functions
 for charm++ f90 runtime:
@@ -78,38 +91,41 @@ for charm++ f90 runtime:
 
   You can think of this function as a constructor for each array element 
 with array index [index]. In this function user must allocate memory for 
-the Chare's user data. User can also initialize the data.      \\
-  For each chare entry method, you should write the fortran90 subroutine
-for it:
+the Chare's user data and perform initialization.
+
+  For each chare entry method you declared, you should write the corresponding 
+fortran90 subroutine for it:
 
   \verb+SUBROUTINE entry(charePtr, myIndex, data1, data2 ... )+
 
-  Note, the first argument is the Chare pointer as you declared previously, the second argument is the array index which will be passed from charm runtime. And you need to enumerate all the message fields declared in .ci file in the 
-subroutine.
+  Note, the first argument is the Chare pointer as you declared previously, the second argument is the array index which will be passed from charm runtime. 
+The rest of the parameters should be the same as you declare the entry function
+in .ci files.
 
-On the other side, for each Chare declared in .ci files, these subroutines are 
-available for user to call in Fortran90 program:
+On the other side, the decl/def files generated by Charm++ translator also
+provide these functions for Chare creation and remote method invocation. 
+for each Chare declared in .ci files, these subroutines are generated for use
+ in Fortran90 program:
 
   \verb+<ChareName>_CkNew(integer n, integer*8 aid)+
 
-  This subroutine creates the chare array.
+  This subroutine creates the chare array of size n.
 
-And for each entry method, this function is available for use:
+And for each entry method, this function is available for use in f90 program:
 
   \verb+SendTo_<ChareName>_<Entry>(charePtr, myIndex, data1, data2 ... )+
 
   This subroutine will send a message to the array element with the index
-as myIndex. Fortran90 charm runtime will pack the parameters into a message
-and sent to the chare array element.
+as myIndex. 
 
 There are several others things you need to know.
 
-First, as same in C++ Charm, each .ci file will generate two header files:
+First, as same in Charm++, each .ci file will generate two header files:
 .decl.h and .def.h. However, in Fortran90 charm, you are not able to include 
 these C++ files in Fortran90 code. Thus, currently, it is user's 
-responsibility to write a simple C++ code to include these two headers files. 
-You should also declare readonly variables in this file. This is as simple as 
-this:
+task to write a simple C++ code to include these two headers files. 
+You should also declare readonly variables as in C++ in this file. This is as 
+simple as this:
 
 \begin{verbatim}
 #include "hello.decl.h"
@@ -118,9 +134,12 @@ int chunkSize;     // readonly variables define here
 \end{verbatim}
 
 In future, this file can be generated automatically by translator.
+
 Second, you can still use readonly variables as in Charm++. However, since
-fortran90 lacks the concepts of global variables as in C, you have to use it
-explicitly. Here are the two helper functions that translator generates:
+there is no global variables as in C++ in fortran90, you have to access them
+explicitly via function call. Here are the two helper functions that 
+translator generates:
+
 take the readonly variable chunkSize as an example,
 \begin{verbatim}
 Set_Chunksize(chunkSize);
@@ -142,18 +161,47 @@ CkPrintf(...)    // note, the format string must terminated with '$$'
 Here is a summary of current constraints to write f90 binding charm++ programs:
 \begin{enumerate}
 \item in .ci files, only 1D Chare array is supported.
-\item messages defined in .ci files must be basic types or fixed size array.
-\item readonly variables must be basic types.
-\item instead of program main, your main program starts from subroutine 
+\item readonly variables must be basic types, ie. they have to be integer, 
+float, etc scalar types or array types of these basic scalar types.
+\item instead of program main, your f90 main program starts from subroutine 
 f90charmmain.
 \end{enumerate}
 
 All these are best explained with an example: the hello program.  It is a
 simple ring program.  When executed, an array of several parallel
-CHAREs is created.  Each chare "says" hello when it receives a
-message, and then sends a message to the next chare.  The Fortran main() 
+Chares is created.  Each chare "says" hello when it receives a
+message, and then sends a message to the next chare. The Fortran f90charmmain() 
 subroutine starts off the events.  And the SayHi() subroutine does the 
-say-hello and forward.
+say-hello and call next chare to forward.
+
+\section{Writing Charm++ Interface File}
+In this step, you need to write a Charm++ interface file with extension of
+.ci. In this file you can declare parallel Chare Arrays and their entry 
+functions. The syntax is same as in Charm++.
+\begin{verbatim}
+      ## Just replace Hello throughout with your chare's name. ##
+      ## and add your chare's entry points below where indicated ##
+      ## Everything else remains the same ##
+      mainmodule hello {
+        // declare readonly variables which once set is available to all
+        // Chares across processors.      
+        readonly int chunkSize;
+
+        array [1D] Hello {
+          entry Hello();
+
+          // Note how your Fortran function takes the above defined
+          // message instead of a list of parameters.
+          entry void SayHi(int a, double b, int n, int arr[n]);
+
+          // Other entry points go here
+
+        };              
+      };
+\end{verbatim}
+Note, you cannot declare main chare in the interface file, you also are not 
+supposed to declare messages. Furthermore, the entry functions must be 
+declared with explicit parameters instead of using messages. 
 
 \section{Writing F90 Program}
 To start, you need to create a Fortran Module to represent a chare,
@@ -167,8 +215,8 @@ e.g. \{ChareName\}Mod.
       MODULE HelloMod
 
       TYPE Hello
+      ## your chare's data goes here ##
       integer data
-      ## your chare's data goes here, the above integer is an example ##
       END TYPE
 
       TYPE HelloPtr
@@ -180,7 +228,7 @@ e.g. \{ChareName\}Mod.
 \end{verbatim}
 
 In the Fortran file you must write an allocate funtion for this chare
-with the name: \{ChareName\}\_allocate.
+with the name: Hello\_allocate.
 
 \begin{verbatim}
       ## Just replace Hello throughout with your chare's name. ##
@@ -198,108 +246,55 @@ with the name: \{ChareName\}\_allocate.
       END SUBROUTINE
 \end{verbatim}
 
-If you have written code for a chare array "Hello", as above, you will
-have the following subroutine available to you:
-
-  \verb+<ChareName>_CkNew(integer n, integer*8 aid)+
-     This function creates a chare array at runtime
-     where n is the number of items in the array, and
-           aid is the array ID which is returned to you.
-
-We will see an example of using this function below.
-
-\section{Writing Charm++ Interface File}
-
-Now that you have the chare, you need to write one or more ENTRY
-POINTs for it.  This is nothing but a Fortran subroutine that uses the
-above module.
+Now that you have the chare and the chare constructor function, you can start
+ to write one or more entry functions as declared in .ci files.
 \begin{verbatim}
       ## p1, p2, etc represent user parameters
       ## the "objPtr, myIndex" stuff is required in every Entry Point.
       ## CkExit() must be called by the chare to terminate.
-      SUBROUTINE SayHi(objPtr, myIndex, p1)
+      SUBROUTINE SayHi(objPtr, myIndex, data, data2, len, s)
       USE HelloMod
       IMPLICIT NONE
 
       TYPE(HelloPtr) objPtr
       integer myIndex
-      integer p1
+      integer data
+      double precision data2
+      integer len
+      integer s(len)
 
       objPtr%obj%data = 20
       if (myIndex < 4) then
-          call SendTo_Hello_SayHi(objPtr%aid, myIndex+1, 1);
+          call SendTo_Hello_SayHi(objPtr%aid, myIndex+1, 1, data2, len, s);
       else 
           call CkExit()
       endif
 \end{verbatim}
-Once you have written code for an Entry Point, you now have available
-to you the following subroutine:
-\begin{verbatim}
-   SendTo_<ChareName>_<SubroutineName>(integer*8 aid, integer myIndex,
-                          other parameters ....)
-     where aid is the target chare array ID
-           myIndex is the specific within the array
-                   we wish to send a message to
-           other parameters are the parameters in the above function.
-\end{verbatim}
 
-\section{Compile and Link}
-You must have a Fortran f90charmmain() subroutine where execution starts.
-Typically this main function will create a chare array and send a
-message to one of its members to get the computation started.
+Now, you can write the main program to create the chare array and start the 
+program by sending the first message.
 \begin{verbatim}
       SUBROUTINE f90charmmain()
       USE HelloMod
       integer i
+      double precision d
       integer*8 aid
-
-      call CkPrintf("Hello\n $$")
+      integer  s(8)
 
       call Hello_CkNew(5, aid)
 
-      call SendTo_Hello_SayHi(aid, 0, 1);
+      call set_ChunkSize(10);
 
-      END
-\end{verbatim}
-\section{Writing Charm++ Interface File}
-Now we move on to Step 2, the Charm Interface file.  This file must
-have a different name from the Fortran file, and must have an
-extension of .ci, e.g. if the above Fortran file is hellof.f90, this
-file could be called hello.ci.  Basically, its purpose is to tell
-Charm what you've done in the Fortran file, since Charm cannot read
-Fortran as of now.
-\begin{verbatim}
-      ## Just replace Hello throughout with your chare's name. ##
-      ## and add your chare's entry points below where indicated ##
-      ## Everything else remains the same ##
-      mainmodule hello {
-      
-        // Create some arbitrary message to hold your parameters
-        // The message must have a unique name for each Entry Point.
-        message HiMsg { int } ;
-      
-        array Hello {
-          entry Hello();
-
-          // Note how your Fortran function takes the above defined
-          // message instead of a list of parameters.
-          entry void SayHi(HiMsg *);
-
-          // Other entry points go here
+      do i=1,8
+          s(i) = i;
+      enddo
+      d = 2.50
+      call SendTo_Hello_SayHi(aid, 0, 1, d, 4, s(3:6));
 
-        };              
-      };
-\end{verbatim}
-If the function has more parameters: e.g. A Fortran function FF(int,
-int, long) in module H, would be described in the .ci file as:
-\begin{verbatim}
-  message MarshalParams { int, int, long };
-  array H {
-    entry H();
-    entry void FF(MarshalParams *);
-  }
+      END
 \end{verbatim}
-As mentioned above, the message must have a unique name.
+This main program creates an chare array Hello of size 5 and send a message with
+an integer, an double and array of integers to the array element of index 0.
 
 \section{Compile and Link}
 Lastly, you need to compile and link the Fortran program with the
@@ -328,11 +323,10 @@ hello.ci and hello.C)
 
 \section{Run Program}
 
-Finally, to run the program, type:
+To run the program, type:
 
 ./charmrun +p2 hello
 
 which will run 'hello' on two virtual processors.
 
-
 \end{document}