bug fix: handle failure detected during checkpoint
[charm.git] / doc / charisma / libmodule.tex
1 Charisma is capable of producing library code for reuse with another Charisma
2 program. We explain this feature in the following section.
3
4 \section{Writing Module Library}
5
6 The programmer uses the keyword \code{module} instead of \code{program} in the
7 header section of the orchestration code to tell the compiler that it is a
8 library module. Following keyword \code{module} is the module name, then
9 followed by a set of configuration variables in a pair parentheses. The 
10 configuration variables are used in creating instances of the library, for
11 such info as problem size. 
12
13 Following the first line, the library's input and output parameters are posted
14 with keywords \code{inparam} and \code{outparam}. 
15
16 \begin{SaveVerbatim}{foodecl}
17   module FFT3D(CHUNK, M, N);
18   inparam indata;
19   outparam outdata1,outdata2;
20 \end{SaveVerbatim}
21 \smallfbox{\BUseVerbatim{foodecl}}
22
23 The body of the library is not very different from that of a normal program. It
24 takes input parameters and produces out parameters, as posted in the header
25 section. 
26
27 \section{Using Module Library}
28
29 To use a Charisma module library, the programmer first needs to create an
30 instance of the library. There are two steps: including the module and creating
31 an instance. 
32
33 \begin{SaveVerbatim}{foodecl}
34   use FFT3D;\81 
35   library f1 : FFT3D(CHUNK=10,M=10,N=100);\81 
36   library f2 : FFT3D(CHUNK=8,M=8,N=64);\81
37 \end{SaveVerbatim}
38 \smallfbox{\BUseVerbatim{foodecl}}
39
40 The keyword \code{use} and the module name includes the module in the program,
41 and the keyword \code{library} creates an instance with the instance name,
42 followed by the module name with value assignment of configuration variables. 
43 These statements must appear in the declaration section before the library
44 instance can be used in the main program's orchestration code. 
45
46 Invoking the library is like calling a publish statement; the input and output
47 parameters are the same, and the object name and function name are replaced with
48 the library instance name and the keyword \code{call} connected with a colon. 
49
50 \begin{SaveVerbatim}{foodecl}
51   (f1_outdata[*]) <- f1:call(f1_indata[*]);\81
52 \end{SaveVerbatim}
53 \smallfbox{\BUseVerbatim{foodecl}}
54
55 Multiple instances can be created out of the same module. Their execution can
56 interleave without interfering with one another.