bug fix: handle failure detected during checkpoint
[charm.git] / doc / charisma / ldb.tex
1 \subsection{Coding}
2
3 To activate load balancing module and prepare objects for migration, there are 3
4 things that needs to be added in Charisma code. 
5
6 First, the programmer needs to inform Charisma about the load balancing with a
7 "\code{define ldb;}" statement in the header section of the orchestration code.
8 This will make Charisma generates extra Charm++ code to do load balancing such
9 as \code{PUP} methods.
10
11 Second, the user has to provide a \code{PUP} function for each class with
12 sequential data that needs to be moved when the object migrates. When choosing
13 which data items to \code{pup}, the user has the flexibility to leave the dead
14 data behind to save on communication overhead in migration. The syntax for the
15 sequential \code{PUP} is similar to that in a Charm++ program. Please refer to
16 the load balancing section in Charm++ manual for more information on \code{PUP}
17 functions. A typical example would look like this in user's sequential \code{.C}
18 file: 
19
20 \begin{SaveVerbatim}{foodecl}
21   void JacobiWorker::sequentialPup(PUP::er& p){
22     p|myLeft; p|myRight; p|myUpper; p|myLower;
23     p|myIter;
24     PUParray(p,(double *)localData,1000);
25   }
26 \end{SaveVerbatim}
27 \smallfbox{\BUseVerbatim{foodecl}}
28
29 Thirdly, the user will make the call to invoke load balancing session in the
30 orchestration code. The call is \code{AtSync();} and it is invoked on all
31 elements in an object array. The following example shows how to invoke load
32 balancing session every 4th iteration in a for-loop. 
33
34 \begin{SaveVerbatim}{foodecl}
35   for iter = 1 to 100
36     // work work
37     if(iter % 4 == 0) then
38       foreach i in workers
39         workers[i].AtSync();
40       end-foreach
41     end-if
42   end-for
43 \end{SaveVerbatim}
44 \smallfbox{\BUseVerbatim{foodecl}}
45
46 If a while-loop is used instead of for-loop, then the test-condition in the
47 \code{if} statement is a local variable in the program's MainChare. In the
48 sequential code, the user can maintain a local variable called \code{iter} in
49 MainChare and increment it every iteration. 
50
51
52 \subsection{Compiling and Running}
53 Unless linked with load balancer modules, a Charisma program will not perform
54 actual load balancing. The way to link in a load balancer module is adding
55 \code{-module EveryLB} as a link-time option. 
56
57 At run-time, the load balancer is specified in command line after the
58 \code{+balancer} option. If the balancer name is incorrect, the job launcher will
59 automatically print out all available load balancers. For instance, the following
60 command uses \code{RotateLB}. 
61
62 \begin{SaveVerbatim}{foodecl}
63     > ./charmrun ./pgm +p16 +balancer RotateLB
64 \end{SaveVerbatim}
65 \smallfbox{\BUseVerbatim{foodecl}}
66
67
68