protocolcheckpoint.h

Path MPICH-V for MPICH the MPI Implementation

/** @file protocolCheckpoint.h defines the checkpoint high level API for daemon
  * giving all necessary structures to define a protocol specific checkpoint
  * implementation.
  */
#ifndef _PROTOCHECKPOINT_H_
#define _PROTOCHECKPOINT_H_

#include <netinet/in.h>

#include "config.h"
#include "debug.h"
#include "genericCheckpoint.h"
#include "simple_list.h"
#include "vtypes.h"


struct _CkptInfo;
typedef int (*Ftp_CkptFunc)(struct _CkptInfo *, void *);

/** checkpoint management structure
 */
typedef struct _CkptInfo
{
  int group;            /**< group of the checkpointed process */
  int rank;             /**< rank of the checkpointed process */
  int seq;              /**< sequence number of the checkpoint image */
  int pipe;             /**< pipe where to read checkpoint image generated by condor */
  CkptSock sock;        /**<  socket connected to the checkpoint server */
  int np;               /**< number of MPI processes */
  long h;               /**< H date of the begining of the checkpoint (may not be usefull for all protocols) */
  int datasize;         /**< total size of data transmited to checkpoint server trough data link */

  int ifunc;            /**< counter indicating wich function has to be called */
  int nfunc;            /**< number of checkpoint functions to call */
  Ftp_CkptFunc ckpt_func[0];    /**< Array of checkpoint functions to call and their arguments. Must be filled after call to ckpt_begin.  */
} CkptInfo;

/** Initialize checkpoint lib
  * @param addr: address of checkpoint server to use, beware that this is not mcopied
  * @param uselocal: boolean value, true indicates the use of a local checkpoint file
  * @param group: group of this MPI application
  * @param rank: rank of this MPI process
  * @param np: number of MPI processes in this application
  * @return -1 on failure, 0 on succes
  */ 
int pckpt_init(struct sockaddr *addr, int uselocal, int group, int rank, int np);

/** Finalize Checkpoint lib
  * @return -1 on failure, 0 on success
  */
int pckpt_finalize(void);

/** Get the cin variable containing current checkpoint informations.
  * This result may change over checkpoint, and not be assumed to be the same 
  * during the whole execution. 
  * @return pointer to a cin struct if it exist one, may be NULL if no such structure exist (wich is not an error but only indicates that no checkpoint is taking place)
  */
extern CkptInfo *_pckpt_cin;
#define pckpt_getCkptInfo() _pckpt_cin
/*inline CkptInfo *pckpt_getCkptInfo(void);*/

/** Set writefunc of a CkptInfo struct.
  * @param ifunc: the index of the function to set in the struct
  * @param func: the function to store in the func array of the CkptInfo struct
  */
void pckpt_setCkptfunc(int ifunc, Ftp_CkptFunc func);
/** Set writeargs of a CkptInfo struct.
  * @param cin: target CkptInfo
  * @param ifunc: the index of the arguments to set in the struct
  * @param func: the function to store in the args array of the CkptInfo struct
  */
void pckpt_setCkptargs(int iargs, void *args);
/** Get currently selected writefunc of a CkptInfo struct.
  * @return currently selected writefunc of cin structure
  */
Ftp_CkptFunc pckpt_getCkptfunc(void);
/** Get currently selected writeargs of a CkptInfo struct.
  * @return currently selected writeargs of cin structure
  */
void *pckpt_getCkptargs(void);

/** Set Logical clock field of a CkptInfo struct. This field may not be usefull
  * for all protocols.
  * @param h: value of the logical clock to store in cin
  */
void pckpt_setH(long h);
/** Set the static variable Sequence number describing the number of checkpoint
  */
void pckpt_setSeqnumber(int seqnumber);
/** Get the static variable Sequence number describing the number of checkpoint
  */
int pckpt_getSeqnumber(void);

/** This function indicates if checkpoint pipe socket should be added to readset of select
  * @return 0 when this socket has not to be set, cin->sock.pipe otherwise
  */
int pckpt_rfdset(void);
/** This function indicates if checkpoint socket should be added to writeset of select
  * @return 0 when this socket has not to be set, cin->sock.data otherwise
  */
int pckpt_wfdset(void);

/** This function indicates wether a checkpoint can be performed, or not at this
  * time
  * @return CP_START indicates that a checkpoint could be started now, 0 otherwise
  */
int pckpt_try(void);
/** This function indicates wether a checkpoint can be performed, or not at this
  * time, and begin it NOW. 
  * @return CP_START indicates that a checkpoint could be started now, 0 otherwise
  */
int pckpt_atomic_try_and_begin(void);

/** Begin a checkpoint : Connection to the checkpoint server is estabished,
  * protocol data are sent.
  * @return A CkptInfo struct suitable for subsequent calls to pckpt funcs. Structure is mallocated with sufficient space to
  * set ftp_ckpt_*write functions. These fields must be manualy filled after this function.
  */
CkptInfo *pckpt_begin(void);

/** A generic write function about checkpoint. This function calls each
  * function set by set_pckpt_writefunc with args set by set_pckpt_writeargs
  * @return -1 on error, 0 if something is remaining to be sent, 1 if all checkpoint data were sent.
  */
int pckpt_genericwrite(void);

/** Finalize a checkpoint. Sends and retrieve all necessary acknowlegdes and
  * close all connexions to checkpoint server.
  * @return -1 on error, 0 otherwise
  */
int pckpt_end(void);



/** Initialize a checkpoint. Connection to the checkpoint server is estabished,
  * protocol data are read.
  * @return A CkptInfo struct suitable for subsequent calls to pckpt funcs. Structure is mallocated with sufficient space to
  * set ftp_ckpt_*read functions. These fields must be manualy filled after this function.
  */
CkptInfo *prestart_begin(void);

/** A generic restart read function. This function calls each
  * function set by pckpt_setckptfunc with args set by pckpt_setckptargs
  * @return -1 on error, 0 if something is remaining to be sent, 1 if all checkpoint data were sent.
  */
int prestart_genericread(void);

/** Finalize a restart. Sends and retrieve all necessary acknowlegdes and
  * close all connexions to checkpoint server.
  * @return -1 on error, 0 otherwise
  */
int prestart_end(void);




/** A generic checkpoint image sending function. This should always be used in the ckpt_writefunc list.
  * This function could be taken as an exemple of async ftp_ckpt_*writefunc.
  * @param cin: Checkpoint info structure as returned by pckpt_begin()
  * @param dummy: useless for this function as input a read from pipe given in cin
  * @return: -1 on error, 0 if some checkpoint data are remaining to send, 1 if all data are sent.
  */
int pckpt_writeimgfunc(CkptInfo *cin, void *dummy);
/** A generic checkpoint image sending function. This should always be used in the ckpt_writefunc list.
  * This function could be taken as an exemple of sync ftp_ckpt_*readfunc.
  * @param cin: Checkpoint info structure as returned by pckpt_begin()
  * @param dummy: useless for this function as input a read from pipe given in cin
  * @return: -1 on error, 0 if some checkpoint data are remaining to send, 1 if all data are sent.
  */
int prestart_readimgfunc(CkptInfo *cin, void *dummy);



#endif