OpenMPI  0.1.1
snapc.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004-2010 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2005 The University of Tennessee and The University
6  * of Tennessee Research Foundation. All rights
7  * reserved.
8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9  * University of Stuttgart. All rights reserved.
10  * Copyright (c) 2004-2005 The Regents of the University of California.
11  * All rights reserved.
12  * $COPYRIGHT$
13  *
14  * Additional copyrights may follow
15  *
16  * $HEADER$
17  */
18 /**
19  * @file
20  *
21  * Snapshot Coordination (SNAPC) Interface
22  *
23  * Terminology:
24  * ------------
25  * Global Snapshot Coordinator:
26  * - HNP(s) coordination function.
27  * Local Snapshot Coordinator
28  * - VHNP(s) [e.g., orted] coordination function
29  * Application Snapshot Coordinator
30  * - Application level coordinaton function
31  * Local Snapshot
32  * - Snapshot generated by a single process in the parallel job
33  * Local Snapshot Reference
34  * - A generic reference to the physical Local Snapshot
35  * Global Snapshot
36  * - Snapshot generated for the entire parallel job
37  * Global Snapshot Reference
38  * - A generic reference to the physical Global Snapshot
39  *
40  * General Description:
41  * ---------------------
42  * This framework is tasked with:
43  * - Initiating the checkpoint in the system
44  * - Physically moving the local snapshot files to a location
45  * Initially this location, is the node on which the Head Node Process (HNP)
46  * is running, but later this will be a replicated checkpoint server or
47  * the like.
48  * - Generating a 'global snapshot handle' that the user can use to restart
49  * the parallel job.
50  *
51  * Each component will have 3 teirs of behavior that must behave in concert:
52  * - Global Snapshot Coordinator
53  * This is the HNPs tasks. Mostly distributing the notification of the
54  * checkpoint, and then compiling the physical and virtual nature of the
55  * global snapshot handle.
56  * - Local Snapshot Coordinator
57  * This is the VHNPs (or orted, if available) tasks. This will involve
58  * working with the Global Snapshot Coordinator to route the physical
59  * and virtual 'local snapshot's from the application to the desired
60  * location. This process must also notify the Global Snapshot Coordinator
61  * when it's set of processes have completed the checkpoint.
62  * - Application Snapshot Coordinator
63  * This is the application level coordinator. This is very light, just
64  * a subscription to be triggered when it needs to checkpoint, and then,
65  * once finished with the checkpoint, notify the Local Snapshot Coordinator
66  * that it is complete.
67  * If there is no orted (so no bootproxy), then the application assumes the
68  * responsibility of the Local Snapshot Coordinator as well.
69  *
70  */
71 
72 #ifndef MCA_SNAPC_H
73 #define MCA_SNAPC_H
74 
75 #include "orte_config.h"
76 #include "orte/constants.h"
77 #include "orte/types.h"
78 
79 #include "opal/mca/mca.h"
80 #include "opal/mca/base/base.h"
81 #include "opal/mca/crs/crs.h"
82 #include "opal/mca/crs/base/base.h"
83 
84 #include "opal/class/opal_object.h"
86 #include "opal/util/output.h"
87 
88 #include "orte/mca/sstore/sstore.h"
89 
90 BEGIN_C_DECLS
91 
92 /**
93  * States that a process can be in while checkpointing
94  */
95 /* Reached an error */
96 #define ORTE_SNAPC_CKPT_STATE_ERROR 0
97 
98 /* Doing no checkpoint -- Quiet state */
99 #define ORTE_SNAPC_CKPT_STATE_NONE 1
100 /* There has been a request for a checkpoint from one of the applications */
101 #define ORTE_SNAPC_CKPT_STATE_REQUEST 2
102 /* There is a Pending checkpoint for this process */
103 #define ORTE_SNAPC_CKPT_STATE_PENDING 3
104 /* Running the checkpoint */
105 #define ORTE_SNAPC_CKPT_STATE_RUNNING 4
106 /* INC Prep Finished */
107 #define ORTE_SNAPC_CKPT_STATE_INC_PREPED 5
108 /* All Processes have been stopped */
109 #define ORTE_SNAPC_CKPT_STATE_STOPPED 6
110 /* Finished the checkpoint locally */
111 #define ORTE_SNAPC_CKPT_STATE_FINISHED_LOCAL 7
112 /* Migrating */
113 #define ORTE_SNAPC_CKPT_STATE_MIGRATING 8
114 /* Finished establishing the checkpoint */
115 #define ORTE_SNAPC_CKPT_STATE_ESTABLISHED 9
116 /* Processes continuing or have been recovered (finished post-INC) */
117 #define ORTE_SNAPC_CKPT_STATE_RECOVERED 10
118 /* Unable to checkpoint this job */
119 #define ORTE_SNAPC_CKPT_STATE_NO_CKPT 11
120 /* Unable to restart this job */
121 #define ORTE_SNAPC_CKPT_STATE_NO_RESTART 12
122 #define ORTE_SNAPC_CKPT_MAX 13
123 
124 /**
125  * Sufficiently high shift value to avoid colliding the process
126  * checkpointing states above with the ORTE process states
127  */
128 #define ORTE_SNAPC_CKPT_SHIFT 131072
129 
130 /* Uniquely encode the SNAPC state */
131 #define ORTE_SNAPC_CKPT_NOTIFY(state) (ORTE_SNAPC_CKPT_SHIFT + state)
132 
133 /* Decode the SNAPC state */
134 #define ORTE_SNAPC_CKPT_STATE(state) (state - ORTE_SNAPC_CKPT_SHIFT)
135 
136 /* Check whether a state is a SNAPC state or not. */
137 #define CHECK_ORTE_SNAPC_CKPT_STATE(state) (state >= ORTE_SNAPC_CKPT_SHIFT)
138 
139 /**
140  * Definition of a orte local snapshot.
141  * Similar to the opal_crs_base_snapshot_t except that it
142  * contains process contact information.
143  */
145  /** List super object */
147 
148  /** ORTE Process name */
150 
151  /** State of the checkpoint */
152  int state;
153 
154  /** Stable Storage Handle (must equal the global version) */
155  orte_sstore_base_handle_t ss_handle;
156 };
159 
161 
162 /**
163  * Definition of the global snapshot.
164  * Each component is assumed to have extened this definition
165  * in the same way they extern the orte_snapc_base_compoinent_t below.
166  */
168  /** This is an object, so must have super */
170 
171  /** A list of orte_snapc_base_snapshot_t's */
173 
174  /** Checkpoint Options */
176 
177  /** Stable Storage Handle */
178  orte_sstore_base_handle_t ss_handle;
179 };
182 
184 
186  /** Parent is an object type */
188 
189  /** Current epoch */
190  int epoch;
191  /** Requested CRS */
192  char * crs_name;
193  /** Handle for reference */
194  char * handle;
195  /** snapshot list */
197 
198  /** Stable Storage Handle */
199  orte_sstore_base_handle_t ss_handle;
200  /** Stable Storage Snapshot list */
202 
203  /** Target Directory */
204  char * target_dir;
205  /** Command Line */
206  char * cmdline;
207  /** State of operation if checkpointing */
209  /** Checkpointing? */
211  /** Restarting? */
213 
214  /** Migrating? */
215  bool migrating;
216  /** List of migrating processes */
218  opal_pointer_array_t migrating_procs;
219 };
222 
224 
225 /**
226  * Application request for a global checkpoint related operation
227  */
228 typedef enum {
229  ORTE_SNAPC_OP_NONE = 0,
230  ORTE_SNAPC_OP_INIT,
231  ORTE_SNAPC_OP_FIN,
232  ORTE_SNAPC_OP_FIN_ACK,
233  ORTE_SNAPC_OP_CHECKPOINT,
234  ORTE_SNAPC_OP_RESTART,
235  ORTE_SNAPC_OP_MIGRATE,
236  ORTE_SNAPC_OP_QUIESCE_START,
237  ORTE_SNAPC_OP_QUIESCE_CHECKPOINT,
238  ORTE_SNAPC_OP_QUIESCE_END
240 
242  /** Parent is an object type */
244 
245  /** Event to request */
247 
248  /** Is this request still active */
249  bool is_active;
250 
251  /** Leader of the operation */
252  int leader;
253 
254  /** Sequence Number */
255  int seq_num;
256 
257  /** Global Handle */
259 
260  /** Stable Storage Handle */
261  orte_sstore_base_handle_t ss_handle;
262 
263  /** Migrating vpid list of participants */
264  int mig_num;
265  int *mig_vpids;
266 
267  /** Migrating hostname preference list */
268  char (*mig_host_pref)[OPAL_MAX_PROCESSOR_NAME];
269 
270  /** Migrating vpid preference list */
272 
273  /** Info key */
275 };
278 
280 
281 /**
282  * Module initialization function.
283  * Returns ORTE_SUCCESS
284  */
286  (bool seed, bool app);
287 
288 /**
289  * Module finalization function.
290  * Returns ORTE_SUCCESS
291  */
293  (void);
294 
295 /**
296  * Setup the necessary structures for this job
297  * Returns ORTE_SUCCESS
298  */
299 typedef int (*orte_snapc_base_setup_job_fn_t)
300  (orte_jobid_t jobid);
301 
302 /**
303  * Setup the necessary structures for this job
304  * Returns ORTE_SUCCESS
305  */
307  (orte_jobid_t jobid);
308 
309 
310 /**
311  * Handle fault tolerance updates
312  *
313  * @param[in] state Fault tolerance state update
314  *
315  * @retval ORTE_SUCCESS The operation completed successfully
316  * @retval ORTE_ERROR An unspecifed error occurred
317  */
318 typedef int (*orte_snapc_base_ft_event_fn_t)(int state);
319 
320 /**
321  * Start a checkpoint originating from an internal source.
322  *
323  * This really only makes sense to call from an application, but in the future
324  * we may allow the checkpoint operation to use this function from the local
325  * coordinator.
326  *
327  * @param[out] epoch Epoch number to associate with this checkpoint operation
328  * Returns ORTE_SUCCESS
329  */
332 
333 /**
334  * Signal end of checkpoint epoch originating from an internal source.
335  *
336  * @param[in] epoch Epoch number to associate with this checkpoint operation
337  * Returns ORTE_SUCCESS
338  */
341 
342 /**
343  * Request a checkpoint related operation to take place
344  */
345 typedef int (*orte_snapc_base_request_op_fn_t)
347 
348 /**
349  * Structure for SNAPC components.
350  */
352  /** MCA base component */
354  /** MCA base data */
356 
357  /** Verbosity Level */
358  int verbose;
359  /** Output Handle for opal_output */
361  /** Default Priority */
362  int priority;
363 };
366 
367 /**
368  * Structure for SNAPC modules
369  */
371  /** Initialization Function */
373  /** Finalization Function */
375  /** Setup structures for a job */
377  /** Release job */
379  /** Handle any FT Notifications */
381  /** Handle internal request for checkpoint */
384  /** Handle a checkpoint related request */
386 };
389 
390 ORTE_DECLSPEC extern orte_snapc_base_module_t orte_snapc;
391 ORTE_DECLSPEC extern orte_snapc_base_component_t orte_snapc_base_selected_component;
392 
393 /**
394  * Macro for use in components that are of type SNAPC
395  */
396 #define ORTE_SNAPC_BASE_VERSION_2_0_0 \
397  MCA_BASE_VERSION_2_0_0, \
398  "snapc", 2, 0, 0
399 
400 END_C_DECLS
401 
402 #endif /* ORTE_SNAPC_H */
403 
bool restarting
Restarting?
Definition: snapc.h:212
Common type for all MCA components.
Definition: mca.h:250
orte_snapc_base_start_checkpoint_fn_t start_ckpt
Handle internal request for checkpoint.
Definition: snapc.h:382
opal_list_t local_snapshots
A list of orte_snapc_base_snapshot_t's.
Definition: snapc.h:172
OPAL output stream facility.
int * mig_vpid_pref
Migrating vpid preference list.
Definition: snapc.h:271
mca_base_component_t base_version
MCA base component.
Definition: snapc.h:353
opal_crs_state_type_t cr_state
State of operation if checkpointing.
Definition: snapc.h:208
opal_object_t super
Parent is an object type.
Definition: snapc.h:187
char * crs_name
Requested CRS.
Definition: snapc.h:192
int(* orte_snapc_base_start_checkpoint_fn_t)(orte_snapc_base_quiesce_t *datum)
Start a checkpoint originating from an internal source.
Definition: snapc.h:331
dynamic pointer array
Definition: opal_pointer_array.h:45
int(* orte_snapc_base_module_finalize_fn_t)(void)
Module finalization function.
Definition: snapc.h:293
char * global_handle
Global Handle.
Definition: snapc.h:258
mca_base_component_data_t base_data
MCA base data.
Definition: snapc.h:355
int(* orte_snapc_base_end_checkpoint_fn_t)(orte_snapc_base_quiesce_t *datum)
Signal end of checkpoint epoch originating from an internal source.
Definition: snapc.h:340
int epoch
Current epoch.
Definition: snapc.h:190
uint32_t orte_jobid_t
Set the allowed range for ids in each space.
Definition: types.h:76
Definition: types.h:146
char * cmdline
Command Line.
Definition: snapc.h:206
Structure for SNAPC components.
Definition: snapc.h:351
bool migrating
Migrating?
Definition: snapc.h:215
int(* orte_snapc_base_request_op_fn_t)(orte_snapc_base_request_op_t *datum)
Request a checkpoint related operation to take place.
Definition: snapc.h:346
int(* orte_snapc_base_ft_event_fn_t)(int state)
Handle fault tolerance updates.
Definition: snapc.h:318
Definition of the global snapshot.
Definition: snapc.h:167
See opal_bitmap.h for an explanation of why there is a split between OPAL and ORTE for this generic c...
opal_crs_base_ckpt_options_t * options
Checkpoint Options.
Definition: snapc.h:175
Distributed Stable Storage (SStore) Interface.
orte_sstore_base_handle_t ss_handle
Stable Storage Handle.
Definition: snapc.h:178
Structure for SNAPC modules.
Definition: snapc.h:370
orte_sstore_base_handle_t ss_handle
Stable Storage Handle (must equal the global version)
Definition: snapc.h:155
int verbose
Verbosity Level.
Definition: snapc.h:358
int priority
Default Priority.
Definition: snapc.h:362
Definition: snapc.h:241
orte_snapc_base_module_init_fn_t snapc_init
Initialization Function.
Definition: snapc.h:372
opal_object_t super
Parent is an object type.
Definition: snapc.h:243
orte_snapc_base_ft_event_fn_t ft_event
Handle any FT Notifications.
Definition: snapc.h:380
int seq_num
Sequence Number.
Definition: snapc.h:255
int leader
Leader of the operation.
Definition: snapc.h:252
Top-level interface for all MCA components.
Definition: opal_list.h:98
orte_snapc_base_global_snapshot_t * snapshot
snapshot list
Definition: snapc.h:196
int(* orte_snapc_base_setup_job_fn_t)(orte_jobid_t jobid)
Setup the necessary structures for this job Returns ORTE_SUCCESS.
Definition: snapc.h:300
int(* orte_snapc_base_module_init_fn_t)(bool seed, bool app)
Module initialization function.
Definition: snapc.h:286
int mig_num
Migrating vpid list of participants.
Definition: snapc.h:264
orte_process_name_t process_name
ORTE Process name.
Definition: snapc.h:149
orte_snapc_base_module_finalize_fn_t snapc_finalize
Finalization Function.
Definition: snapc.h:374
int num_migrating
List of migrating processes.
Definition: snapc.h:217
opal_list_item_t super
List super object.
Definition: snapc.h:146
orte_snapc_base_request_op_event_t event
Event to request.
Definition: snapc.h:246
char(* mig_host_pref)[OPAL_MAX_PROCESSOR_NAME]
Migrating hostname preference list.
Definition: snapc.h:268
Definition: snapc.h:185
orte_sstore_base_handle_t ss_handle
Stable Storage Handle.
Definition: snapc.h:199
Definition of a orte local snapshot.
Definition: snapc.h:144
orte_sstore_base_global_snapshot_info_t * ss_snapshot
Stable Storage Snapshot list.
Definition: snapc.h:201
Base object.
Definition: opal_object.h:182
orte_snapc_base_request_op_fn_t request_op
Handle a checkpoint related request.
Definition: snapc.h:385
opal_list_item_t super
This is an object, so must have super.
Definition: snapc.h:169
Meta data for MCA v2.0.0 components.
Definition: mca.h:309
Definition: opal_list.h:147
orte_snapc_base_request_op_event_t
Application request for a global checkpoint related operation.
Definition: snapc.h:228
orte_snapc_base_setup_job_fn_t setup_job
Setup structures for a job.
Definition: snapc.h:376
char * target_dir
Target Directory.
Definition: snapc.h:204
bool checkpointing
Checkpointing?
Definition: snapc.h:210
int output_handle
Output Handle for opal_output.
Definition: snapc.h:360
orte_sstore_base_handle_t ss_handle
Stable Storage Handle.
Definition: snapc.h:261
orte_snapc_base_release_job_fn_t release_job
Release job.
Definition: snapc.h:378
bool is_active
Is this request still active.
Definition: snapc.h:249
int(* orte_snapc_base_release_job_fn_t)(orte_jobid_t jobid)
Setup the necessary structures for this job Returns ORTE_SUCCESS.
Definition: snapc.h:307
Checkpoint and Restart Service (CRS) Interface.
int state
State of the checkpoint.
Definition: snapc.h:152
int * mig_off_node
Info key.
Definition: snapc.h:274
A simple C-language object-oriented system with single inheritance and ownership-based memory managem...
char * handle
Handle for reference.
Definition: snapc.h:194
#define OBJ_CLASS_DECLARATION(NAME)
Declaration for class descriptor.
Definition: opal_object.h:236
opal_crs_state_type_t
States of the module.
Definition: crs.h:60