OpenClovis Logo

clCkptApi.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2002-2012 OpenClovis Solutions Inc. All Rights Reserved.
3  *
4  * This file is available under a commercial license from the
5  * copyright holder or the GNU General Public License Version 2.0.
6  *
7  * The source code for this program is not published or otherwise
8  * divested of its trade secrets, irrespective of what has been
9  * deposited with the U.S. Copyright office.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * General Public License for more details.
15  *
16  * For more information, see the file COPYING provided with this
17  * material.
18  */
19 /*******************************************************************************
20  * ModuleName : ckpt
21  * File : clCkptApi.h
22  *******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  * File : clCkptApi.h
27 * This file contains Checkpoint service APIs defined by SAF
28 *
29 *
30 *****************************************************************************/
31 
44 #ifndef _CL_CKPT_API_H_
45 #define _CL_CKPT_API_H_
46 
47 # ifdef __cplusplus
48 extern "C" {
49 # endif
50 
51 #include <clCommon.h>
52 #include <clIocApi.h>
53 
54 /********************************
55  C O N S T A N T S
56 ********************************/
57 
61 #define CL_CKPT_WR_ALL_REPLICAS 0X1
62 
66 #define CL_CKPT_WR_ACTIVE_REPLICA 0X2
67 
71 #define CL_CKPT_WR_ACTIVE_REPLICA_WEAK 0X4
72 
73 
77 #define CL_CKPT_CHECKPOINT_COLLOCATED 0X8
78 
82 #define CL_CKPT_DISTRIBUTED 0X10
86 #define CL_CKPT_WR_ALL_SAFE 0X20
87 
91 #define CL_CKPT_ALL_OPEN_ARE_REPLICAS 0x40
92 
97 #define CL_CKPT_PEER_TO_PEER_REPLICA 0x80
98 
105 #define CL_CKPT_PEER_TO_PEER_CACHE_DISABLE 0x100
106 
110 #define CL_CKPT_CHECKPOINT_READ 0X1
111 
115 #define CL_CKPT_CHECKPOINT_WRITE 0X2
116 
120 #define CL_CKPT_CHECKPOINT_CREATE 0X4
121 
125 #define CL_CKPT_DEFAULT_SECTION_ID {0, NULL}
129 #define CL_CKPT_GENERATED_SECTION_ID {0, NULL}
130 
131 
132 
136 typedef ClHandleT ClCkptSvcHdlT;
137 
141 typedef ClHandleT ClCkptHdlT;
142 
146 typedef ClHandleT ClCkptSecItrHdlT;
147 
151 typedef ClUint32T ClCkptCreationFlagsT;
152 
156 typedef ClUint32T ClCkptOpenFlagsT;
160 typedef ClUint32T ClCkptSelectionObjT;
161 
165 typedef struct {
166 
171 
176 
181 
185  ClUint32T maxSections;
186 
191 
197 
201 typedef struct {
202 
206  ClUint16T idLen;
207 
211  ClUint8T *id;
212 
214 
218 typedef struct {
219 
224 
230 
234 typedef enum {
235 
240 
246 
250 typedef struct {
251 
256 
261 
266 
271 
277 
281 typedef enum {
305 
309 typedef struct {
310 
315 
319  ClPtrT dataBuffer;
320 
325 
330 
336 
340 typedef struct {
341 
346 
350  ClUint32T numberOfSections;
351 
355  ClUint32T memoryUsed;
357 
404  ClCkptHdlT ckptHdl,
405  ClNameT *pName,
406  ClCkptIOVectorElementT *pIOVector,
407  ClUint32T numSections,
408  ClPtrT pCookie );
464  ClInvocationT invocation,
465  ClCkptHdlT checkpointHandle,
466  ClRcT error);
467 
512  ClInvocationT invocation,
513  ClRcT error);
514 
518 typedef struct {
519 
524 
530 
531 
568 extern ClRcT clCkptInitialize( CL_OUT ClCkptSvcHdlT *ckptSvcHandle, /* Checkpoint service handle */
569  CL_IN const ClCkptCallbacksT *callbacks, /* Optional callbacks */
570  CL_INOUT ClVersionT *version); /* Version */
571 
572 
573 
574 
612 
670 extern ClRcT clCkptCheckpointOpen( CL_IN ClCkptSvcHdlT ckptHandle, /* Service handle */
671  CL_IN const ClNameT *ckeckpointName, /* Name of the checkpoint */
672  CL_IN const ClCkptCheckpointCreationAttributesT *checkpointCreationAttributes,
673  CL_IN ClCkptOpenFlagsT checkpointOpenFlags, /* Open flags */
674  CL_IN ClTimeT timeout, /* Time out */
675  CL_IN ClCkptHdlT *checkpointHandle); /* Return handle */
676 
677 
678 
715  CL_IN ClInvocationT invocation,
716  CL_IN const ClNameT *checkpointName,
717  CL_IN const ClCkptCheckpointCreationAttributesT *checkpoiNtCreationAttributes,
718  CL_IN ClCkptOpenFlagsT checkpointOpenFlags);
719 
761 extern ClRcT clCkptCheckpointClose(CL_IN ClCkptHdlT checkpointHandle);
762 
811 extern ClRcT clCkptCheckpointDelete( CL_IN ClCkptSvcHdlT ckptHandle, /* checkpoint svc handle */
812  CL_IN const ClNameT *checkpointName);
813 
839  CL_IN ClTimeT retentionDuration);
840 
862 extern ClRcT clCkptActiveReplicaSet(CL_IN ClCkptHdlT checkpointHandle);
863 
901  CL_OUT ClCkptCheckpointDescriptorT *checkpointStatus);
960 extern ClRcT clCkptSectionCreate( CL_IN ClCkptHdlT checkpointHandle,
961  CL_IN ClCkptSectionCreationAttributesT *sectionCreationAttributes,
962  CL_IN const ClUint8T *initialData,
963  CL_IN ClSizeT initialDataSize);
964 
965 
1006 extern ClRcT clCkptSectionDelete( CL_IN ClCkptHdlT checkpointHandle,
1007  CL_IN const ClCkptSectionIdT *sectionId);
1008 
1041  CL_IN const ClCkptSectionIdT* sectionId,
1042  CL_IN ClTimeT expirationTime);
1078  CL_IN ClCkptSectionsChosenT sectionsChosen,
1079  CL_IN ClTimeT expirationTime,
1080  CL_OUT ClHandleT *sectionIterationHandle);
1081 
1113 extern ClRcT clCkptSectionIterationNext( CL_IN ClHandleT sectionIterationHandle,
1114  CL_OUT ClCkptSectionDescriptorT *sectionDescriptor);
1115 
1144 extern ClRcT clCkptSectionIterationFinalize(CL_IN ClHandleT sectionIterationHandle);
1145 
1206 extern ClRcT clCkptCheckpointWrite( CL_IN ClCkptHdlT checkpointHandle,
1207  CL_IN const ClCkptIOVectorElementT *ioVector,
1208  CL_IN ClUint32T numberOfElements,
1209  CL_OUT ClUint32T *erroneousVectorIndex);
1210 
1255  CL_IN const ClCkptSectionIdT *sectionId,
1256  CL_IN const void *dataBuffer,
1257  CL_IN ClSizeT dataSize);
1258 
1307 extern ClRcT clCkptCheckpointRead( CL_IN ClCkptHdlT checkpointHandle,
1308  CL_INOUT ClCkptIOVectorElementT *ioVector,
1309  CL_IN ClUint32T numberOfElements,
1310  CL_OUT ClUint32T *erroneousVectorIndex);
1311 
1335  CL_IN ClTimeT timeout);
1358  CL_IN ClInvocationT invocation);
1382  CL_IN ClPtrT pCookie);
1383 
1423  CL_OUT ClSelectionObjectT *selectionObject);
1424 
1425 
1457  CL_IN ClDispatchFlagsT dispatchFlags);
1458 
1459 #ifdef __cplusplus
1460 }
1461 #endif
1462 
1463 #endif /* _CL_CKPT_API_H_*/
1464 
Typical defines found in any software project.
Header file of Ioc Data Structures and APIs.
ClRcT clCkptCheckpointClose(CL_IN ClCkptHdlT checkpointHandle)
Closes the checkpoint designated by the checkpointHandle.
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 clCkptImmediateConsumptionRegister(CL_IN ClCkptHdlT checkpointHandle, CL_IN ClCkptNotificationCallbackT callback, CL_IN ClPtrT pCookie)
Registers a callback function to be called to notify change in the checkpoint data.
ClRcT clCkptSectionExpirationTimeSet(CL_IN ClCkptHdlT checkpointHandle, CL_IN const ClCkptSectionIdT *sectionId, CL_IN ClTimeT expirationTime)
Sets the expiration time of a section.
ClCkptSectionsChosenT
This enum is used for selection of sections while iterating through all the sections.
Definition: clCkptApi.h:281
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.
ClRcT clCkptCheckpointStatusGet(CL_IN ClCkptHdlT checkpointHandle, CL_OUT ClCkptCheckpointDescriptorT *checkpointStatus)
Returns the status and the various attributes of the checkpoint.
ClUint32T ClCkptCreationFlagsT
Flags to indicate various attributes of a checkpoint on creation.
Definition: clCkptApi.h:151
ClRcT clCkptCheckpointOpenAsync(CL_IN ClCkptSvcHdlT ckptHandle, CL_IN ClInvocationT invocation, CL_IN const ClNameT *checkpointName, CL_IN const ClCkptCheckpointCreationAttributesT *checkpoiNtCreationAttributes, CL_IN ClCkptOpenFlagsT checkpointOpenFlags)
Creates and opens a checkpoint asynchronously.
ClRcT clCkptCheckpointSynchronize(CL_IN ClCkptHdlT ckeckpointHandle, CL_IN ClTimeT timeout)
Synchronizes the replicas of a checkpoint.
ClRcT clCkptSectionIterationInitialize(CL_IN ClCkptHdlT checkpointHandle, CL_IN ClCkptSectionsChosenT sectionsChosen, CL_IN ClTimeT expirationTime, CL_OUT ClHandleT *sectionIterationHandle)
Enables the application to iterate through sections in 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.
ClHandleT ClCkptSecItrHdlT
The handle used to identify a section in a checkpoint.
Definition: clCkptApi.h:146
ClRcT clCkptActiveReplicaSet(CL_IN ClCkptHdlT checkpointHandle)
Sets the local replica to be active replica.
ClRcT clCkptCheckpointDelete(CL_IN ClCkptSvcHdlT ckptHandle, CL_IN const ClNameT *checkpointName)
Removes the checkpoint from the system and frees all resources allocated to it.
void(* ClCkptCheckpointSynchronizeCallbackT)(ClInvocationT invocation, ClRcT error)
This function gets called When clCkptCheckpointSynchronizeAsync() call returns on the server.
Definition: clCkptApi.h:511
ClHandleT ClCkptSvcHdlT
The type of the handle for the the checkpoint service library.
Definition: clCkptApi.h:136
ClRcT clCkptSectionDelete(CL_IN ClCkptHdlT checkpointHandle, CL_IN const ClCkptSectionIdT *sectionId)
Deletes a section in the given checkpoint.
ClCkptSectionStateT
This enum represents the state of a section in a replica.
Definition: clCkptApi.h:234
ClRcT clCkptSectionIterationNext(CL_IN ClHandleT sectionIterationHandle, CL_OUT ClCkptSectionDescriptorT *sectionDescriptor)
Returns the next section in the list of sections.
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 clCkptDispatch(CL_IN ClCkptSvcHdlT ckptHandle, CL_IN ClDispatchFlagsT dispatchFlags)
Invokes the pending callback in context of the EO.
ClRcT clCkptCheckpointRetentionDurationSet(CL_IN ClCkptHdlT checkpointHandle, CL_IN ClTimeT retentionDuration)
Sets the retention duration of a 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.
ClUint32T ClCkptOpenFlagsT
Flags to indicate open mode such as read, write or create.
Definition: clCkptApi.h:156
ClRcT clCkptCheckpointWrite(CL_IN ClCkptHdlT checkpointHandle, CL_IN const ClCkptIOVectorElementT *ioVector, CL_IN ClUint32T numberOfElements, CL_OUT ClUint32T *erroneousVectorIndex)
Writes multiple sections on to a given checkpoint.
ClRcT clCkptFinalize(CL_IN ClCkptSvcHdlT ckptHandle)
Closes the checkpoint service client and cancels all pending callbacks related to the handle.
ClRcT clCkptSelectionObjectGet(CL_IN ClCkptSvcHdlT ckptHandle, CL_OUT ClSelectionObjectT *selectionObject)
Helps detect pending callbacks.
void(* ClCkptCheckpointOpenCallbackT)(ClInvocationT invocation, ClCkptHdlT checkpointHandle, ClRcT error)
This function gets called When clCkptCheckpointOpenAsync() call returns on the server.
Definition: clCkptApi.h:463
ClRcT clCkptCheckpointSynchronizeAsync(CL_IN ClCkptHdlT checkpointHandle, CL_IN ClInvocationT invocation)
Synchronizes the replicas of a Checkpoint asynchronously.
ClRcT clCkptSectionIterationFinalize(CL_IN ClHandleT sectionIterationHandle)
Frees resources associated with the iteration.
ClUint32T ClCkptSelectionObjT
Selection object.
Definition: clCkptApi.h:160
ClRcT(* ClCkptNotificationCallbackT)(ClCkptHdlT ckptHdl, ClNameT *pName, ClCkptIOVectorElementT *pIOVector, ClUint32T numSections, ClPtrT pCookie)
This function gets called whenever a checkpoint is getting updated on the local server.
Definition: clCkptApi.h:403
@ CL_CKPT_SECTIONS_CORRUPTED
All corrupted sections.
Definition: clCkptApi.h:299
@ CL_CKPT_SECTIONS_LEQ_EXPIRATION_TIME
All sections with expiration time less than or equal to the value of expirationTime.
Definition: clCkptApi.h:290
@ CL_CKPT_SECTIONS_GEQ_EXPIRATION_TIME
All sections with expiration time greater than or equal to the value of expiration time.
Definition: clCkptApi.h:295
@ CL_CKPT_SECTIONS_FOREVER
All sections with expiration time set to CL_TIME_END.
Definition: clCkptApi.h:285
@ CL_CKPT_SECTIONS_ANY
All sections.
Definition: clCkptApi.h:303
@ CL_CKPT_SECTION_CORRUPTED
Indicates that the section has been corrupted.
Definition: clCkptApi.h:244
@ CL_CKPT_SECTION_VALID
Indicates that the section is fine.
Definition: clCkptApi.h:239
ClUint32T ClRcT
Clovis return code type.
Definition: clCommon.h:168
#define CL_INOUT
CL_INOUT macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:108
ClInt64T ClTimeT
Time duration specified in nanoseconds.
Definition: clCommon.h:154
#define CL_OUT
CL_OUT macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:110
ClInt64T ClOffsetT
Offset of a buffer or object within another
Definition: clCommon.h:159
ClDispatchFlagsT
Dispatch flags.
Definition: clCommon.h:260
ClUint64T ClSizeT
Definition: clCommon.h:157
#define CL_IN
CL_IN macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:106
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
ClSizeT checkpointSize
Total size of application data in a replica.
Definition: clCkptApi.h:175
ClSizeT maxSectionSize
Maximum size of a section.
Definition: clCkptApi.h:190
ClTimeT retentionDuration
Checkpoint which is inactive (not opened anywhere) for this duration (in nanoseconds) is deleted.
Definition: clCkptApi.h:180
ClCkptCreationFlagsT creationFlags
Create time attributes.
Definition: clCkptApi.h:170
ClSizeT maxSectionIdSize
Maximum length of the section identifier.
Definition: clCkptApi.h:195
ClUint32T maxSections
Maximum sections for this checkpoint.
Definition: clCkptApi.h:185
This structure represents a section identifier.
Definition: clCkptApi.h:201
ClUint16T idLen
Length of the section identifier.
Definition: clCkptApi.h:206
ClUint8T * id
Section identifier.
Definition: clCkptApi.h:211
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
ClTimeT expirationTime
Section expiration time.
Definition: clCkptApi.h:228
This structure represents a section in a checkpoint.
Definition: clCkptApi.h:250
ClSizeT sectionSize
Size of the section.
Definition: clCkptApi.h:265
ClTimeT expirationTime
Expiration time for the section.
Definition: clCkptApi.h:260
ClCkptSectionIdT sectionId
Section identifier.
Definition: clCkptApi.h:255
ClCkptSectionStateT sectionState
Indicates whether a section has a valid or an invalid state.
Definition: clCkptApi.h:270
ClTimeT lastUpdate
Last time the section is updated.
Definition: clCkptApi.h:275
This structure represents an IO vector which will be used for dealing with more than zero sections.
Definition: clCkptApi.h:309
ClSizeT dataSize
Size of the data.
Definition: clCkptApi.h:324
ClSizeT readSize
Number of bytes read.
Definition: clCkptApi.h:334
ClOffsetT dataOffset
Offset.
Definition: clCkptApi.h:329
ClCkptSectionIdT sectionId
Identifier of the section.
Definition: clCkptApi.h:314
ClPtrT dataBuffer
Pointer to the data.
Definition: clCkptApi.h:319
This structure is used to describe a checkpoint.
Definition: clCkptApi.h:340
ClUint32T memoryUsed
Memory used by the checkpoint.
Definition: clCkptApi.h:355
ClUint32T numberOfSections
Total number of sections.
Definition: clCkptApi.h:350
ClCkptCheckpointCreationAttributesT checkpointCreationAttributes
Creates attribute.
Definition: clCkptApi.h:345
This structure is the only location where all the callbacks converge.
Definition: clCkptApi.h:518
ClCkptCheckpointSynchronizeCallbackT checkpointSynchronizeCallback
Synchronize callback.
Definition: clCkptApi.h:528
ClCkptCheckpointOpenCallbackT checkpointOpenCallback
Asynchronous open callback.
Definition: clCkptApi.h:523

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