Added documentation for the new POSE checkpoint command line parameters to the POSE...
[charm.git] / doc / pose / configure.tex
1 \section{Configuring \pose{}}
2
3 \pose{} can be configured in two different ways.  Fundamental
4 behaviors are controlled by altering values in the {\tt
5 pose\_config.h} file in the \pose{} installation, and rebuilding
6 \pose{}.  Many of these configuration options can (and should) be
7 controlled by command line options.  These will be designated here by
8 an asterisk ($*$).  See section~\ref{sec:posecommand} for the command line
9 options.  
10
11 \begin{itemize}
12 \item {\tt {\bf POSE\_STATS\_ON $*$}}\\
13         $\circ$ Turn on timing and statistics gathering for internal \pose{}
14         operations.  Produces a small slowdown in program.\\
15 \item {\tt {\bf POSE\_DOP\_ON $*$}}\\
16         $\circ$ Turn on timing and statistics gathering for degree of parallelism calculations.  Generates log files that can be loaded by ploticus scripts to produce graphs plotting active entities over time.  Slows down program dramatically.\\
17 \item {\tt {\bf POSE\_COMM\_ON}}\\
18         $\circ$ Turn on streaming communication optimization for small message packing.\\
19 \item {\tt {\bf COMM\_TIMEOUT}}\\
20         $\circ$ Used by streaming communication library. Time to wait (in ?) before sending buffered messages.\\
21 \item {\tt {\bf COMM\_MAXMSG}}\\
22         $\circ$ Used by streaming communication library.  Number of messages to buffer before packing and sending as one.\\
23 \item {\tt {\bf LB\_ON $*$}}\\
24         $\circ$ Turn on \pose{} load balancing.\\
25 \item {\tt {\bf STORE\_RATE $*$}}\\
26         $\circ$ Default checkpointing rate: 1 for every {\tt STORE\_RATE} events.\\
27 \item {\tt {\bf SPEC\_WINDOW $*$}}\\
28         $\circ$ Speculative window size: this is how far (in virtual time units) ahead of GVT posers are allowed to go.\\
29 \item {\tt {\bf MIN\_LEASH $*$}} and {\tt {\bf MAX\_LEASH $*$}}\\
30         $\circ$ Bounds on the speculative window, these are adjusted by adaptive synchronization strategies.\\
31 \item {\tt {\bf LEASH\_FLEX $*$}}\\
32         $\circ$ Granularity of flexibility when speculative window is shrunk or expanded.\\
33 \item {\tt {\bf MAX\_POOL\_SIZE}}\\
34         $\circ$ Memory used by event messages is recycled.  This controls how many messages of a particular size will be kept on hand.
35 \item {\tt {\bf MAX\_RECYCLABLE}}\\
36         $\circ$ This is the largest size of message that will be recycled.
37 \item {\tt {\bf LB\_SKIP $*$}}\\
38         $\circ$ This controls the frequency of load balance invocation.  1 in every {\tt LB\_SKIP} executions of the GVT algorithm will invoke load balancing.
39 \item {\tt {\bf LB\_THRESHOLD $*$}}\\
40         $\circ$ What the heck does this number mean?  I can't remember.  I'll have to look through the code... later.  Meanwhile, I think this indicates some sort of threshold a single processor has to cross before we even bother with analyzing the load.\\
41 \item {\tt {\bf LB\_DIFF $*$}}\\
42         $\circ$ Once the load has been analyzed, we compute the difference between the max and min PE loads.  Only if this difference exceeds {\tt LB\_DIFF} do we bother migrating posers.\\
43 \end{itemize}
44
45 Several of the above flags and constants will be eliminated as the adaptive strategy is expanded.  What remains will eventually become run-time options.
46
47 \subsection{\pose{} Command Line Options}
48 \label{sec:posecommand}
49
50 Command line options are handled like \charmpp{} command line
51 parameters.  For namespace purity all \pose{} command line options
52 have a \_pose suffix.  They can be inspected by appending a -h to an
53 execution of a \pose{} program.  Command line options override any
54 defaults set in the {\tt pose\_config.h} file
55
56 \begin{itemize}
57 \item {\tt {\bf +stats\_pose}}\\
58         $\circ$ Turn on timing and statistics gathering for internal \pose{}
59         operations.  Produces a small slowdown in program.\\
60 \item {\tt {\bf +dop\_pose}}\\
61         $\circ$ Turn on timing and statistics gathering for degree of parallelism calculations.  Generates log files that can be loaded by ploticus scripts to produce graphs plotting active entities over time.  Slows down program dramatically.\\
62 \item {\tt {\bf +lb\_on\_pose}}\\
63         $\circ$ Turn on \pose{} load balancing.\\
64 \item {\tt {\bf +store\_rate\_pose N}}\\
65         $\circ$ Default checkpointing rate: 1 for every {\tt STORE\_RATE} events.\\
66 \item {\tt {\bf +spec\_window\_pose N}}\\
67         $\circ$ Speculative window size: this is how far (in virtual time units) ahead of GVT posers are allowed to go.\\
68 \item {\tt {\bf +min\_leash\_pose N}} and {\tt {\bf +min\_leash\_pose N}}\\
69         $\circ$ Bounds on the speculative window, these are adjusted by adaptive synchronization strategies.\\
70 \item {\tt {\bf +leash\_flex\_pose N}}\\
71         $\circ$ Granularity of flexibility when speculative window is shrunk or expanded.\\
72 \item {\tt {\bf +lb\_skip\_pose N}}\\
73         $\circ$ This controls the frequency of load balance invocation.  1 in every {\tt LB\_SKIP} executions of the GVT algorithm will invoke load balancing.
74 \item {\tt {\bf +lb\_threshold\_pose N}}\\
75         $\circ$ Minimum threshold for load balancing, default is 4000
76 \item {\tt {\bf +lb\_diff\_pose N}}\\
77         $\circ$ Once the load has been analyzed, we compute the difference between the max and min PE loads.  Only if this difference exceeds {\tt LB\_DIFF} do we bother migrating posers.\\
78 \item {\tt {\bf +checkpoint\_gvt\_pose N}}\\
79         $\circ$ Checkpoint to disk approximately every N GVT ticks (N is an integer).  The default is 0, which indicates no checkpointing.
80 \item {\tt {\bf +checkpoint\_time\_pose N}}\\
81         $\circ$ Checkpoint to disk every N seconds (N is an integer).  The default is 0, which indicates no checkpointing.  If both this parameter and +checkpoint\_gvt\_pose are greater than 0, a warning will be given, the value of this parameter will be set to 0, and POSE will checkpoint based on GVT ticks.
82 \end{itemize}
83
84 As a technical point, pose command line parsing is done inside the
85 {\tt POSE\_init()} call.  Therefore, the most consistent behavior for
86 interleaving pose command line options with user application options
87 will be achieved by calling {\tt POSE\_init()} before handling user
88 application command line arguments.