OpenClovis Logo

API Usage Examples

Code Examples.

Code Examples.

The below code example shows the usage of server based checkpointing.

The usage model of this example is to to have 2 applications running in 1+1 redundancy on 2 worker nodes. The Active application keeps writing a counter value inthe checkpoint and the standby application will be idle. After some time we kill the node running the active instance, which triggers the standby application to now take over as Active. At this point the new active application reads the checkpoint, and starts updating counter from the point where the old active had left it.

Note that the below code snippets are been tested. However please follow the instructions given in the comment blocks before each function.

#include "ckptTest.h"
/*********************************************************************
* Definitions: Below are the datastructure definitions used
* in this application
*/
#define CKPT_NAME "SampleCkptTest" /* Checkpoint Name */
#define CKPT_SID_NAME "1" /* Checkpoint section id */
ClUint32T seq; /* The sequence no which will be
written into the checkpoint */
ClCkptSvcHdlT ckpt_svc_handle; /* Checkpointing service handle */
ClCkptHdlT ckpt_handle; /* Checkpoint handle */
ClCkptSectionIdT ckpt_sid = { /* Section id for checkpoints */
(ClUint16T)sizeof(CKPT_SID_NAME)-1,
(ClUint8T*)CKPT_SID_NAME
};
int running = 1;
int exiting = 0;
ClAmsHAStateT ha_state = CL_AMS_HA_STATE_NONE;
/**********************************************************************
* INIT: The below function initializes the checkpoint service client
* and opens a collocated checkpoint in read, write mode. This function
* should be invoked from the AppInitialize of the application before
* doing a clCpmRegister
*/
ClRcT checkpoint_initialize()
{
ClRcT rc = CL_OK;
ClVersionT ckpt_version = {'B', 1, 1};
ClNameT ckpt_name = { strlen(CKPT_NAME), CKPT_NAME };
.checkpointSize = sizeof(ClUint32T),
.retentionDuration = (ClTimeT)0,
.maxSections = 2, /* Default section,
plus section we create */
.maxSectionSize = sizeof(ClUint32T),
.maxSectionIdSize = (ClSizeT)64
};
clOsalPrintf("Initializing the checkpoint\n");
/* Initialize checkpointing service instance */
rc = clCkptInitialize(&ckpt_svc_handle, /* Checkpoint service handle */
NULL, /* Optional callbacks table */
&ckpt_version); /* Required verison number */
if (rc != CL_OK)
{
clOsalPrintf("clCkptInitialize failed with rc 0x%x\n",rc);
return rc;
}
clOsalPrintf("Checkpoint service initialized [handle=0x%x]\n",
ckpt_svc_handle);
/* Create the checkpoint for read and write. */
rc = clCkptCheckpointOpen(ckpt_svc_handle, /* Service handle */
&ckpt_name, /* Checkpoint name */
&create_atts, /* Optional creation attr.*/
(ClTimeT)-1, /* No timeout */
&ckpt_handle); /* Checkpoint handle */
if (rc != CL_OK)
{
clOsalPrintf("clCkptCheckpointOpen failed with [rc=0x%x]\n",rc);
clCkptFinalize(ckpt_svc_handle);
return rc;
}
clOsalPrintf("Checkpoint opened [Checkpoint handle=0x%x]\n",
ckpt_handle);
return CL_OK;
}
/************************************************************************
* Finalize: The below function closes the checkpoint and finalizes the
* checkpoint svc handle. This should be called from AppTerminate function
* of the application.
*/
ClRcT checkpoint_finalize(void)
{
ClRcT rc;
rc = clCkptCheckpointClose(ckpt_handle);
if (rc != CL_OK)
{
clOsalPrintf("Checkpoint close failed with rc 0x%x\n",rc);
}
rc = clCkptFinalize(ckpt_svc_handle);
if (rc != CL_OK)
{
clOsalPrintf("Checkpoint Finalize failed with rc 0x%x\n",rc);
}
return rc;
}
/*************************************************************************
* active_replica_set: This function sets the local checkpoint db as the
* active replica. This will be initially called in the section_create
* function before creating the section into the checkpoint. However,
* this function also needs to be explicitly invoked by the application
* as soon as it takes over from Standby state to Active State.
*/
ClRcT active_replica_set()
{
ClRcT rc = CL_OK;
rc = clCkptActiveReplicaSet(ckpt_handle);
if (rc != CL_OK)
{
clOsalPrintf("Ckpt Active replica set failed with [rc = 0x%x\n",rc);
return rc;
}
return rc;
}
/*************************************************************************
* section_create: This function creates a section into the checkpoint.
*/
ClRcT checkpoint_section_create()
{
/*
Try to create a section so that updates can operate by overwriting
the section over and over again.
*/
ClRcT rc = CL_OK;
ClUint8T initData = 0;
.sectionId = &ckpt_sid,
.expirationTime = CL_TIME_END /* Setting an infinite time */
};
active_replica_set();
/* Create the section */
rc = clCkptSectionCreate(ckpt_handle, /* Checkpoint handle */
&section_atts, /* Section attributes */
&initData, /* Initial data */
(ClSizeT)sizeof(initData));
/* Size of data */
{
clOsalPrintf("CkptSectionCreate failed with rc 0x%x\n",rc);
clCkptCheckpointClose(ckpt_handle);
clCkptFinalize(ckpt_svc_handle);
return rc;
}
else if (rc != CL_OK && (CL_GET_ERROR_CODE(rc) == CL_ERR_ALREADY_EXIST))
{
/* Section already exists. So read the checkpointed value and
* continue to write from the point where it is left */
rc = checkpoint_read_seq(&seq);
if (rc != CL_OK)
{
clOsalPrintf("Checkpoint read failed with rc 0x%x\n",rc);
clCkptCheckpointClose(ckpt_handle);
clCkptFinalize(ckpt_svc_handle);
return rc;
}
clOsalPrintf("Sequence Number read from chekpoint %lu\n",seq);
}
else
{
clOsalPrintf("Section created successful\n");
}
return rc;
}
/*************************************************************************
* READ: This function reads the checkpointed data and stores
* in the global seq variable
*/
ClRcT checkpoint_read_seq(ClUint32T *seq)
{
ClRcT rc = CL_OK;
ClUint32T err_idx; /* Error index in ioVector */
ClUint32T seq_no = 0xffffffff;
.sectionId = ckpt_sid,
.dataBuffer = (ClPtrT)&seq_no,
.dataSize = sizeof(ClUint32T),
.dataOffset = (ClOffsetT)0,
.readSize = sizeof(ClUint32T)
};
rc = clCkptCheckpointRead(ckpt_handle, &iov, 1, &err_idx);
if (rc != CL_OK)
{
clOsalPrintf("CkptRead ERROR [rc = 0x%x]\n",rc);
}
*seq = ntohl(seq_no);
clOsalPrintf("CheckpointRead: seq = %lu\n", *seq);
fflush(stdout);
return rc;
}
/*************************************************************************
* WRITE: The below function writes the seq no into the checkpoint.
*/
ClRcT checkpoint_write_seq(ClUint32T seq)
{
ClRcT rc = CL_OK;
ClUint32T seq_no;
seq_no = htonl(seq);
clOsalPrintf("CkptWrite: seq = %lu\n", seq);
fflush(stdout);
/* Write checkpoint */
rc = clCkptSectionOverwrite(ckpt_handle,
&ckpt_sid,
&seq_no,
sizeof(ClUint32T));
if (rc != CL_OK)
{
clOsalPrintf("CheckpointSectionOverWrite failed with rc 0x%x\n",rc);
}
else
{
/* If write is successful, then synchronise the checkpoints on all
replicas */
if (rc != CL_OK)
{
clOsalPrintf("Failed [0x%x] to synchronize the checkpoint\n",
rc);
}
}
return rc;
}
/*************************************************************************
* LOOP: The below function is the critical part of the code. This
* function needs to be invoked at the end of the AppInitialize function
* of the application. On the active application,this function keeps
* writing the incremented sequence number into the checkpoint. Note that
* the seq no is a global variable. During the switchover, when the standby
* takes over as new active it first reads the latest value from the
* checkpoint into the global seq no, and then marks the ha_state variable
* to CL_AMS_HA_STATE_ACTIVE.This will make the below loop on the active
* application to start writing checkpoint with the new value.
*/
ClRcT get_into_loop()
{
ClRcT rc = CL_OK;
while (!exiting)
{
if (running && ha_state == CL_AMS_HA_STATE_ACTIVE)
{
/* Checkpoint new sequence number */
rc = checkpoint_write_seq(seq);
if (rc != CL_OK)
{
printf("Checkpoint write failed... Exiting..\n");
break;
}
seq++;
}
sleep(1);
}
return rc;
}
/*************************************************************************
* AppInit: Following code needs to be put into the AppInitialize function
* of the application
*/
{/*START*/
/* Initialize the checkpoint */
checkpoint_initialize();
/* Create the sections */
checkpoint_section_create();
/*
---END_APPLICATION_CODE---
*/
get_into_loop();
}/*END*/
/*************************************************************************
* StateChange: Following code needs to be put into the CSI Set function
* of the application. Please note that the other part of the
* auto generated code in the application SHOULD NOT be altered
*/
case CL_AMS_HA_STATE_ACTIVE:
{
/* Set this local checkpoint as active replica */
active_replica_set();
/* Read the value in the section so that u can start
from where it is left */
checkpoint_read_seq(&seq);
ha_state = haState;
}
case CL_AMS_HA_STATE_STANDBY:
{
ha_state = haState;
/*
---END_APPLICATION_CODE---
*/
}
/*************************************************************************
* Header File: Below code needs to be put into ckptTest.h file under
* same directory and this also needs to be included in
* the clCompAppMain.c file.
*/
#include <clCkptApi.h>
#include <clCommon.h>
#include <clOsalApi.h>
#include <clIocServices.h>
/*
ASP Client Includes.
*/
#include <clRmdApi.h>
#include <clDebugApi.h>
#include <clOmApi.h>
#include <clOampRtApi.h>
#include <clProvApi.h>
#include <clAlarmApi.h>
#include <clEoApi.h>
#include <clCpmApi.h>
#include <clIdlApi.h>
#include <string.h>
#include <netinet/in.h>
extern ClUint32T seq; /* The sequence no which will be
written into the checkpoint */
extern int running;
extern int exiting;
extern ClAmsHAStateT ha_state;
extern ClRcT checkpoint_initialize();
extern ClRcT checkpoint_finalize(void);
extern ClRcT checkpoint_section_create();
extern ClRcT checkpoint_read_seq(ClUint32T *seq);
extern ClRcT checkpoint_write_seq(ClUint32T seq);
extern ClRcT get_into_loop();
extern ClRcT active_replica_set();
Typical defines found in any software project.
Header file of Alarm Service related APIs.
Header file for the APIs and data types exposed by the CPM.
Header file of Server based Checkpoint Service Related APIs.
Header file of Debug Service Related APIs.
Header file of EO related APIs.
Header file of Reserved Communication Ports.
Operating System Abstraction Layer API.
Header file of Provision Library related APIs.
Header file of RMD Interface.
ClRcT clCkptCheckpointClose(CL_IN ClCkptHdlT checkpointHandle)
Closes the checkpoint designated by the checkpointHandle.
#define CL_CKPT_WR_ACTIVE_REPLICA_WEAK
Asynchronous checkpoint.
Definition: clCkptApi.h:71
ClHandleT ClCkptHdlT
The handle used to identify a checkpoint.
Definition: clCkptApi.h:141
ClRcT clCkptInitialize(CL_OUT ClCkptSvcHdlT *ckptSvcHandle, CL_IN const ClCkptCallbacksT *callbacks, CL_INOUT ClVersionT *version)
Initializes the checkpoint service client and registers the various callbacks.
ClRcT clCkptCheckpointOpen(CL_IN ClCkptSvcHdlT ckptHandle, CL_IN const ClNameT *ckeckpointName, CL_IN const ClCkptCheckpointCreationAttributesT *checkpointCreationAttributes, CL_IN ClCkptOpenFlagsT checkpointOpenFlags, CL_IN ClTimeT timeout, CL_IN ClCkptHdlT *checkpointHandle)
Opens an existing checkpoint.
#define CL_CKPT_CHECKPOINT_WRITE
Checkpoint open for write.
Definition: clCkptApi.h:115
ClRcT clCkptCheckpointSynchronize(CL_IN ClCkptHdlT ckeckpointHandle, CL_IN ClTimeT timeout)
Synchronizes the replicas of a checkpoint.
ClRcT clCkptCheckpointRead(CL_IN ClCkptHdlT checkpointHandle, CL_INOUT ClCkptIOVectorElementT *ioVector, CL_IN ClUint32T numberOfElements, CL_OUT ClUint32T *erroneousVectorIndex)
Reads multiple sections at a time.
#define CL_CKPT_CHECKPOINT_COLLOCATED
Collocated checkpoint.
Definition: clCkptApi.h:77
ClRcT clCkptActiveReplicaSet(CL_IN ClCkptHdlT checkpointHandle)
Sets the local replica to be active replica.
ClHandleT ClCkptSvcHdlT
The type of the handle for the the checkpoint service library.
Definition: clCkptApi.h:136
ClRcT clCkptSectionCreate(CL_IN ClCkptHdlT checkpointHandle, CL_IN ClCkptSectionCreationAttributesT *sectionCreationAttributes, CL_IN const ClUint8T *initialData, CL_IN ClSizeT initialDataSize)
Creates a section in the checkpoint.
ClRcT clCkptSectionOverwrite(CL_IN ClCkptHdlT checkpointHandle, CL_IN const ClCkptSectionIdT *sectionId, CL_IN const void *dataBuffer, CL_IN ClSizeT dataSize)
Writes a single section in a given checkpoint.
ClRcT clCkptFinalize(CL_IN ClCkptSvcHdlT ckptHandle)
Closes the checkpoint service client and cancels all pending callbacks related to the handle.
#define CL_CKPT_CHECKPOINT_READ
Checkpoint open for read.
Definition: clCkptApi.h:110
#define CL_CKPT_CHECKPOINT_CREATE
Checkpoint open for create.
Definition: clCkptApi.h:120
ClUint32T ClRcT
Clovis return code type.
Definition: clCommon.h:168
ClInt64T ClTimeT
Time duration specified in nanoseconds.
Definition: clCommon.h:154
ClInt64T ClOffsetT
Offset of a buffer or object within another
Definition: clCommon.h:159
#define CL_GET_ERROR_CODE(RC)
This macro extracts the error code from the return code.
Definition: clCommonErrors.h:297
ClUint64T ClSizeT
Definition: clCommon.h:157
#define CL_OK
Every thing is OK.
Definition: clCommonErrors.h:68
#define CL_TIME_END
In practice, this will never time out, since it is 292 years.
Definition: clCommon.h:149
#define CL_ERR_ALREADY_EXIST
An entry is already existing.
Definition: clCommonErrors.h:148
ClRcT clOsalPrintf(const ClCharT *fmt,...)
Prints to the standard output.
A name.
Definition: clCommon.h:197
Version Information for various services.
Definition: clCommon.h:250
This structure represents the properties of checkpoint that can be specified during the creation proc...
Definition: clCkptApi.h:165
ClCkptCreationFlagsT creationFlags
Create time attributes.
Definition: clCkptApi.h:170
This structure represents a section identifier.
Definition: clCkptApi.h:201
This structure represents section attributes that can be specified during the creation process.
Definition: clCkptApi.h:218
ClCkptSectionIdT * sectionId
Section identifier.
Definition: clCkptApi.h:223
This structure represents an IO vector which will be used for dealing with more than zero sections.
Definition: clCkptApi.h:309
ClCkptSectionIdT sectionId
Identifier of the section.
Definition: clCkptApi.h:314

Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen