Docs: refer to illinois.edu, not uiuc.edu
[charm.git] / doc / charm++ / checkpoint.tex
1 \charmpp{} offers a couple of checkpoint/restart mechanisms. Each
2 of these targets a specific need in parallel programming. However,
3 both of them are based on the same infrastructure.
4
5 Traditional chare-array-based \charmpp{} applications, including AMPI
6 applications, can be checkpointed to storage buffers (either files or
7 memory regions) and be restarted later from those buffers. The basic
8 idea behind this is straightforward: checkpointing an application is
9 like migrating its parallel objects from the processors onto buffers,
10 and restarting is the reverse. Thanks to the migration utilities like
11 PUP methods (Section~\ref{sec:pup}), users can decide what data to
12 save in checkpoints and how to save them. However, unlike migration
13 (where certain objects do not need a PUP method), checkpoint requires
14 all the objects to implement the PUP method.
15
16 The two checkpoint/restart schemes implemented are:
17 \begin{itemize}
18 \item Shared filesystem: provides support for \emph{split execution}, where the
19 execution of an application is interrupted and later resumed.
20 \item Double local-storage: offers an online \emph{fault
21 tolerance} mechanism for applications running on unreliable machines.
22 \end{itemize}
23
24 \section{Split Execution}
25
26 There are several reasons for having to split the execution of an
27 application. These include protection against job failure, a single
28 execution needing to run beyond a machine's job time limit, and
29 resuming execution from an intermediate point with different
30 parameters. All of these scenarios are supported by a mechanism to
31 record execution state, and resume execution from it later. 
32
33 Parallel machines are assembled from many complicated components, each
34 of which can potentially fail and interrupt execution
35 unexpectedly. Thus, parallel applications that take long enough to run
36 from start to completion need to protect themselves from losing work
37 and having to start over. They can achieve this by periodically taking
38 a checkpoint of their execution state from which they can later
39 resume.
40
41 Another use of checkpoint/restart is where the total execution
42 time of the application exceeds the maximum allocation time for a job
43 in a supercomputer. For that case, an application may checkpoint
44 before the allocation time expires and then restart from the
45 checkpoint in a subsequent allocation.
46
47 A third reason for having a split execution is when an application
48 consists in \emph{phases} and each phase may be run a different number
49 of times with varying parameters. Consider, for instance, an
50 application with two phases where the first phase only has a possible
51 configuration (it is run only once). The second phase may have several
52 configuration (for testing various algorithms). In that case, once the
53 first phase is complete, the application checkpoints the
54 result. Further executions of the second phase may just resume from
55 that checkpoint.
56
57 An example of \charmpp{}'s support for split execution can be seen
58 in \testrefdir{chkpt/hello}.
59
60 \subsection{Checkpointing}
61
62 \label{sec:diskcheckpoint}
63         The API to checkpoint the application is:
64
65 \begin{alltt} 
66   void CkStartCheckpoint(char* dirname,const CkCallback& cb);
67 \end{alltt}
68
69 The string {\it dirname} is the destination directory where the
70 checkpoint files will be stored, and {\it cb} is the callback function
71 which will be invoked after the checkpoint is done, as well as when
72 the restart is complete. Here is an example of a typical use:
73
74 \begin{alltt} 
75   . . .  CkCallback cb(CkIndex_Hello::SayHi(),helloProxy);
76   CkStartCheckpoint("log",cb);
77 \end{alltt}
78
79 A chare array usually has a PUP routine for the sake of migration.
80 The PUP routine is also used in the checkpointing and restarting
81 process.  Therefore, it is up to the programmer what to save and
82 restore for the application. One illustration of this flexbility is a
83 complicated scientific computation application with 9 matrices, 8 of
84 which hold intermediate results and 1 that holds the final results
85 of each timestep.  To save resources, the PUP routine can well omit
86 the 8 intermediate matrices and checkpoint the matrix with the final
87 results of each timestep.
88
89 Group and nodegroup objects (Section~\ref{sec:group}) are normally not
90 meant to be migrated. In order to checkpoint them, however, the user
91 has to write PUP routines for the groups and declare them as {\tt
92 [migratable]} in the .ci file. Some programs use {\it mainchares} to
93 hold key control data like global object counts, and thus mainchares
94 need to be checkpointed too. To do this, the programmer should write a
95 PUP routine for the mainchare and declare them as {\tt [migratable]}
96 in the .ci file, just as in the case of Group and NodeGroup. In
97 addition, the programmer also needs to put the proxy to the mainchare
98 (usually noted as mainproxy) as a read-only variable in the code, and make
99 sure processor 0, which holds the mainchare, initiates the checkpoint.
100
101 After {\tt CkStartCheckpoint} is executed, a directory of the
102 designated name is created and a collection of checkpoint files are
103 written into it.
104
105 \subsection{Restarting}
106
107 The user can choose to run the \charmpp{} application in restart mode,
108 i.e., restarting execution from a previously-created checkpoint. The
109 command line option {\tt +restart DIRNAME} is required to invoke this
110 mode. For example:
111
112 \begin{alltt}
113   > ./charmrun hello +p4 +restart log
114 \end{alltt}
115
116 Restarting is the reverse process of checkpointing. \charmpp{} allows
117 restarting the old checkpoint on a different number of physical
118 processors.  This provides the flexibility to expand or shrink your
119 application when the availability of computing resources changes.
120
121 Note that on restart, if an array or group reduction client was set to a static
122 function, the function pointer might be lost and the user needs to
123 register it again. A better alternative is to always use an entry method
124 of a chare object. Since all the entry methods are registered
125 inside \charmpp{} system, in the restart phase, the reduction client
126 will be automatically restored.
127
128 After a failure, the system may contain fewer or more
129 processors. Once the failed components have been repaired, some
130 processors may become available again. Therefore, the user may need
131 the flexibility to restart on a different number of processors than in
132 the checkpointing phase. This is allowable by giving a different {\tt
133 +pN} option at runtime. One thing to note is that the new load
134 distribution might differ from the previous one at checkpoint time, so
135 running a load balancer (see Section~\ref{loadbalancing}) after
136 restart is suggested.
137
138 If restart is not done on the same number of processors, the
139 processor-specific data in a group/nodegroup branch cannot (and
140 usually should not) be restored individually. A copy from processor 0
141 will be propagated to all the processors.
142
143 \subsection{Choosing What to Save}
144
145 In your programs, you may use chare groups for different types of
146 purposes.  For example, groups holding read-only data can avoid
147 excessive data copying, while groups maintaining processor-specific
148 information are used as a local manager of the processor. In the
149 latter situation, the data is sometimes too complicated to save and
150 restore but easy to re-compute. For the read-only data, you want to
151 save and restore it in the PUP'er routine and leave empty the
152 migration constructor, via which the new object is created during
153 restart.  For the easy-to-recompute type of data, we just omit the
154 PUP'er routine and do the data reconstruction in the group's migration
155 constructor.
156
157 A similar example is the program mentioned above, where there are two
158 types of chare arrays, one maintaining intermediate results while the
159 other type holds the final result for each timestep. The programmer
160 can take advantage of the flexibility by leaving PUP'er routine empty
161 for intermediate objects, and do save/restore only for the important
162 objects.
163
164 \section{Online Fault Tolerance}
165 \label{sec:MemCheckpointing}
166 As supercomputers grow in size, their reliability decreases
167 correspondingly. This is due to the fact that the ability to assemble
168 components in a machine surpasses the increase in reliability per
169 component. What we can expect in the future is that applications will
170 run on unreliable hardware.
171
172 The previous disk-based checkpoint/restart can be used as a fault
173 tolerance scheme. However, it would be a very basic scheme in that
174 when a failure occurs, the whole program gets killed and the user has
175 to manually restart the application from the checkpoint files.  The
176 double local-storage checkpoint/restart protocol described in this
177 subsection provides an automatic fault tolerance solution. When a
178 failure occurs, the program can automatically detect the failure and
179 restart from the checkpoint.  Further, this fault-tolerance protocol
180 does not rely on any reliable external storage (as needed in the previous
181 method).  Instead, it stores two copies of checkpoint data to two
182 different locations (can be memory or local disk).  This double
183 checkpointing ensures the availability of one checkpoint in case the
184 other is lost.  The double in-memory checkpoint/restart scheme is
185 useful and efficient for applications with small memory footprint at
186 the checkpoint state.  The double in-disk variant stores checkpoints
187 into local disk, thus can be useful for applications with large memory
188 footprint.
189 %Its advantage is to reduce the recovery
190 %overhead to seconds when a failure occurs.
191 %Currently, this scheme only supports Chare array-based Charm++ applications.
192
193
194 \subsection{Checkpointing}
195
196 The function that application developers can call to record a checkpoint in a
197 chare-array-based application is:
198 \begin{alltt}
199       void CkStartMemCheckpoint(CkCallback &cb)
200 \end{alltt}
201 where {\it cb} has the same meaning as in
202 section~\ref{sec:diskcheckpoint}.  Just like the above disk checkpoint
203 described, it is up to the programmer to decide what to save.  The
204 programmer is responsible for choosing when to activate checkpointing
205 so that the size of a global checkpoint state, and consequently the
206 time to record it, is minimized.
207
208 In AMPI applications, the user just needs to call the following
209 function to record a checkpoint:
210 \begin{alltt}
211       void AMPI_MemCheckpoint()
212 \end{alltt}
213
214 \subsection{Restarting}
215
216 When a processor crashes, the restart protocol will be automatically
217 invoked to recover all objects using the last checkpoints. The program
218 will continue to run on the surviving processors. This is based on the
219 assumption that there are no extra processors to replace the crashed
220 ones.
221
222 However, if there are a pool of extra processors to replace the
223 crashed ones, the fault-tolerance protocol can also take advantage of
224 this to grab one free processor and let the program run on the same
225 number of processors as before the crash.  In order to achieve
226 this, \charmpp{} needs to be compiled with the macro option {\it
227 CK\_NO\_PROC\_POOL} turned on.
228
229 \subsection{Double in-disk checkpoint/restart}
230
231 A variant of double memory checkpoint/restart, {\it double in-disk
232 checkpoint/restart}, can be applied to applications with large memory
233 footprint.  In this scheme, instead of storing checkpoints in the
234 memory, it stores them in the local disk.  The checkpoint files are
235 named ``ckpt[CkMyPe]-[idx]-XXXXX'' and are stored under the /tmp
236 directory.
237
238 Users can pass the runtime option {\it +ftc\_disk} to activate this
239 mode.  For example:
240
241 \begin{alltt}
242    ./charmrun hello +p8 +ftc_disk
243 \end{alltt} 
244
245 \subsection{Building Instructions}
246 In order to have the double local-storage checkpoint/restart
247 functionality available, the parameter \emph{syncft} must be provided
248 at build time:
249
250 \begin{alltt}
251    ./build charm++ net-linux-x86_64 syncft
252 \end{alltt} 
253
254 At present, only a few of the machine layers underlying the \charmpp{}
255 runtime system support resilient execution. These include the
256 TCP-based \texttt{net} builds on Linux and Mac OS X.
257
258 \subsection{Failure Injection}
259 To test that your application is able to successfully recover from
260 failures using the double local-storage mechanism, we provide a
261 failure injection mechanism that lets you specify which PEs will fail
262 at what point in time. You must create a text file with two
263 columns. The first colum will store the PEs that will fail. The second
264 column will store the time at which the corresponding PE will
265 fail. Make sure all the failures occur after the first checkpoint. The
266 runtime parameter \emph{kill\_file} has to be added to the command
267 line along with the file name:
268
269 \begin{alltt}
270    ./charmrun hello +p8 +kill_file <file>
271 \end{alltt} 
272
273 An example of this usage can be found in the \texttt{syncfttest}
274 targets in \testrefdir{jacobi3d}.