improved f90charm manual, explained some new features and constraints in more details.
authorGengbin Zheng <gzheng@illinois.edu>
Sat, 3 Mar 2001 07:42:24 +0000 (07:42 +0000)
committerGengbin Zheng <gzheng@illinois.edu>
Sat, 3 Mar 2001 07:42:24 +0000 (07:42 +0000)
doc/f90charm/manual.tex

index f462a444d0574185a3285c30a0922921d078e27b..4e4762f1a817b9bf6d891a5e271f20a718fcde9d 100644 (file)
@@ -16,7 +16,7 @@
 
 \pagestyle{headings}
 
-\title{Fortran90 Bindings for Charm++}
+\title{Fortran90 Bindings for Charm++\footnote{last modified 3/3/2001 by Gengbin Zheng}}
 \author{Gengbin Zheng, Jayant Desouza}
 
 \begin{document}
@@ -35,7 +35,7 @@ your program you need to do the following things:
 \section{Overview}
 
 Here I suppose you've already known most concepts in charm++ and done some 
-charm++ programing.  \\
+charm++ programming.  \\
 Unlike in C++, we don't have class here in Fortran90. Thus, Chare is 
 represented as a fortran type structure. Here is an example:
 
@@ -47,8 +47,8 @@ represented as a fortran type structure. Here is an example:
       MODULE HelloMod
 
       TYPE Hello
+      ## your chare's data goes here, the integer below is an example ##
       integer data
-      ## your chare's data goes here, the above integer is an example ##
       END TYPE
 
       TYPE HelloPtr
@@ -58,26 +58,28 @@ represented as a fortran type structure. Here is an example:
 
       END MODULE
 \end{verbatim}
-You can think of this module as a chare declaration. Type Hello defines 
+You can think of this module as a chare declaration. Type [Hello] defines 
 arbitary user private data and HelloPtr defines the Chare pointer which 
 fortran program will use later to communicate with the f90charm runtime 
 library. \\
 As same in C++ charm program, you need to write a .ci interface file
-so that charm translator will generate some helper functions. However, for
+so that charm translator will generate helper functions. However, for
 Fortran90 charm, the syntax is a little different. First, it only support
-Chare array, you cannot define Chare and Group types. Second, for the 
-message declaration, you must list all the data fields explicitly.
-By this, the translator generated helper functions will know the contents
-of the messages and do the message marshalling and unmarshalling for 
-the fortran program. 
+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. 
 
-For each Chare defined in the .ci file, you must define these functions
-for charm++ runtime use:
+For each Chare defined in the .ci file, user must write these functions
+for charm++ f90 runtime:
 
-  \verb+SUBROUTINE <ChareName>_allocate(objPtr, aid)+
+  \verb+SUBROUTINE <ChareName>_allocate(objPtr, aid, index)+
 
-  this function will allocate the chare user data.
-And for each chare entry method, you should define the fortran90 subroutine
+  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:
 
   \verb+SUBROUTINE entry(charePtr, myIndex, data1, data2 ... )+
@@ -85,8 +87,8 @@ for it:
   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.
 
-On the other side, for each Chare declared, these subroutines are available
-for use in Fortran90 program:
+On the other side, for each Chare declared in .ci files, these subroutines are 
+available for user to call in Fortran90 program:
 
   \verb+<ChareName>_CkNew(integer n, integer*8 aid)+
 
@@ -95,6 +97,7 @@ for use in Fortran90 program:
 And for each entry method, this function is available for use:
 
   \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.
@@ -102,10 +105,11 @@ and sent to the chare array element.
 There are several others things you need to know.
 
 First, as same in C++ Charm, each .ci file will generate two header files:
-.decl.h and .def.h. However, in Fortran90 charm, you cannot use 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. This is as simple
-as this:
+.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:
 
 \begin{verbatim}
 #include "hello.decl.h"
@@ -113,10 +117,11 @@ int chunkSize;    // readonly variables define here
 #include "hello.def.h"
 \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:
-take the chunkSize as an example,
+take the readonly variable chunkSize as an example,
 \begin{verbatim}
 Set_Chunksize(chunkSize);
 Get_Chunksize(chunkSize);
@@ -134,6 +139,15 @@ CkNumPes(integer pes)
 CkPrintf(...)    // note, the format string must terminated with '$$'
 \end{verbatim}
 
+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 
+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
@@ -171,13 +185,16 @@ with the name: \{ChareName\}\_allocate.
 \begin{verbatim}
       ## Just replace Hello throughout with your chare's name. ##
       ## Everything else remains the same ##
-      SUBROUTINE Hello_allocate(objPtr, aid)
+      SUBROUTINE Hello_allocate(objPtr, aid, index)
       USE HelloMod
       TYPE(HelloPtr) objPtr 
       integer*8 aid
+      integer index
 
       allocate(objPtr%obj)
       objPtr%aid = aid;
+      ## you can initialize the Chare user data here
+      objPtr%obj%data = index
       END SUBROUTINE
 \end{verbatim}
 
@@ -236,7 +253,7 @@ message to one of its members to get the computation started.
       integer i
       integer*8 aid
 
-      print *, "hello"
+      call CkPrintf("Hello\n $$")
 
       call Hello_CkNew(5, aid)
 
@@ -296,7 +313,7 @@ hello.ci and hello.C)
 \begin{verbatim}
   charmc -c hello.C
 \end{verbatim}
-    will compile the hello.decl.h, hello.def.h.
+    will compile the hello.C with hello.decl.h, hello.def.h.
 
 \begin{verbatim}
   charmc -c hellof.f90
@@ -306,20 +323,16 @@ hello.ci and hello.C)
 \begin{verbatim}
   charmc -o hello hello.o hellof.o -language f90charm
 \end{verbatim}
-    will link hellof.o, hello.o and Charm's Fortran library
+    will link hellof.o, hello.o against Charm's Fortran90 library
     to create your executable program 'hello'.
 
 \section{Run Program}
 
-Finally, to run the program, make sure you have a nodelist file called
-"nodelist" and containing, for example,
-
-group main
-host <computername>.cs.uiuc.edu <login>
-
-and then type
+Finally, to run the program, type:
 
 ./charmrun +p2 hello
 
 which will run 'hello' on two virtual processors.
+
+
 \end{document}