Defines, Structures, Typedefs, Functions. More...

Files
file	clCkptApi.h
	Header file of Server based Checkpoint Service Related APIs.
file	clCkptErrors.h
	Header file of Ckpt Service defined Errors.

Classes
struct	ClCkptCallbacksT
	This structure is the only location where all the callbacks converge. More...
struct	ClCkptCheckpointCreationAttributesT
	This structure represents the properties of checkpoint that can be specified during the creation process. More...
struct	ClCkptCheckpointDescriptorT
	This structure is used to describe a checkpoint. More...
struct	ClCkptIOVectorElementT
	This structure represents an IO vector which will be used for dealing with more than zero sections. More...
struct	ClCkptSectionCreationAttributesT
	This structure represents section attributes that can be specified during the creation process. More...
struct	ClCkptSectionDescriptorT
	This structure represents a section in a checkpoint. More...
struct	ClCkptSectionIdT
	This structure represents a section identifier. More...

Macros
#define	CL_CKPT_ALL_OPEN_ARE_REPLICAS 0x40
	OpenClovis extension.
#define	CL_CKPT_CHECKPOINT_COLLOCATED 0X8
	Collocated checkpoint.
#define	CL_CKPT_CHECKPOINT_CREATE 0X4
	Checkpoint open for create.
#define	CL_CKPT_CHECKPOINT_READ 0X1
	Checkpoint open for read.
#define	CL_CKPT_CHECKPOINT_WRITE 0X2
	Checkpoint open for write.
#define	CL_CKPT_DEFAULT_SECTION_ID {0, NULL}
	NULL Section ID.
#define	CL_CKPT_DISTRIBUTED 0X10
	Hot stanby checkpoint.
#define	CL_CKPT_ERR_NO_SECTIONS 0x101
	While iterating the sections on the checkpoint, if no more sections are available this error will be returned.
#define	CL_CKPT_GENERATED_SECTION_ID {0, NULL}
	Default ID for generated section.
#define	CL_CKPT_PEER_TO_PEER_CACHE_DISABLE 0x100
	OpenClovis extension.
#define	CL_CKPT_PEER_TO_PEER_REPLICA 0x80
	OpenClovis extension.
#define	CL_CKPT_WR_ACTIVE_REPLICA 0X2
	Asynchronous checkpoint.
#define	CL_CKPT_WR_ACTIVE_REPLICA_WEAK 0X4
	Asynchronous checkpoint.
#define	CL_CKPT_WR_ALL_REPLICAS 0X1
	Synchronous checkpoint.
#define	CL_CKPT_WR_ALL_SAFE 0X20
	Safe Asynchronous checkpoint.

Typedefs
typedef void(*	ClCkptCheckpointOpenCallbackT )(ClInvocationT invocation, ClCkptHdlT checkpointHandle, ClRcT error)
	This function gets called When clCkptCheckpointOpenAsync() call returns on the server.
typedef void(*	ClCkptCheckpointSynchronizeCallbackT )(ClInvocationT invocation, ClRcT error)
	This function gets called When clCkptCheckpointSynchronizeAsync() call returns on the server.
typedef ClUint32T	ClCkptCreationFlagsT
	Flags to indicate various attributes of a checkpoint on creation.
typedef ClHandleT	ClCkptHdlT
	The handle used to identify a checkpoint.
typedef 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.
typedef ClUint32T	ClCkptOpenFlagsT
	Flags to indicate open mode such as read, write or create.
typedef ClHandleT	ClCkptSecItrHdlT
	The handle used to identify a section in a checkpoint.
typedef ClUint32T	ClCkptSelectionObjT
	Selection object.
typedef ClHandleT	ClCkptSvcHdlT
	The type of the handle for the the checkpoint service library.

Enumerations
enum	ClCkptSectionsChosenT { CL_CKPT_SECTIONS_FOREVER = 1, CL_CKPT_SECTIONS_LEQ_EXPIRATION_TIME = 2, CL_CKPT_SECTIONS_GEQ_EXPIRATION_TIME = 3, CL_CKPT_SECTIONS_CORRUPTED = 4, CL_CKPT_SECTIONS_ANY = 5 }
	This enum is used for selection of sections while iterating through all the sections. More...
enum	ClCkptSectionStateT { CL_CKPT_SECTION_VALID = 1, CL_CKPT_SECTION_CORRUPTED = 2 }
	This enum represents the state of a section in a replica. More...

Functions
ClRcT	clCkptActiveReplicaSet (CL_IN ClCkptHdlT checkpointHandle)
	Sets the local replica to be active replica.
ClRcT	clCkptCheckpointClose (CL_IN ClCkptHdlT checkpointHandle)
	Closes the checkpoint designated by the checkpointHandle.
ClRcT	clCkptCheckpointDelete (CL_IN ClCkptSvcHdlT ckptHandle, CL_IN const ClNameT *checkpointName)
	Removes the checkpoint from the system and frees all resources allocated to it.
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	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	clCkptCheckpointRead (CL_IN ClCkptHdlT checkpointHandle, CL_INOUT ClCkptIOVectorElementT ioVector, CL_IN ClUint32T numberOfElements, CL_OUT ClUint32T erroneousVectorIndex)
	Reads multiple sections at a time.
ClRcT	clCkptCheckpointRetentionDurationSet (CL_IN ClCkptHdlT checkpointHandle, CL_IN ClTimeT retentionDuration)
	Sets the retention duration of a checkpoint.
ClRcT	clCkptCheckpointStatusGet (CL_IN ClCkptHdlT checkpointHandle, CL_OUT ClCkptCheckpointDescriptorT *checkpointStatus)
	Returns the status and the various attributes of the checkpoint.
ClRcT	clCkptCheckpointSynchronize (CL_IN ClCkptHdlT ckeckpointHandle, CL_IN ClTimeT timeout)
	Synchronizes the replicas of a checkpoint.
ClRcT	clCkptCheckpointSynchronizeAsync (CL_IN ClCkptHdlT checkpointHandle, CL_IN ClInvocationT invocation)
	Synchronizes the replicas of a Checkpoint asynchronously.
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	clCkptDispatch (CL_IN ClCkptSvcHdlT ckptHandle, CL_IN ClDispatchFlagsT dispatchFlags)
	Invokes the pending callback in context of the EO.
ClRcT	clCkptFinalize (CL_IN ClCkptSvcHdlT ckptHandle)
	Closes the checkpoint service client and cancels all pending callbacks related to the handle.
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	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	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	clCkptSectionDelete (CL_IN ClCkptHdlT checkpointHandle, CL_IN const ClCkptSectionIdT *sectionId)
	Deletes a section in the given checkpoint.
ClRcT	clCkptSectionExpirationTimeSet (CL_IN ClCkptHdlT checkpointHandle, CL_IN const ClCkptSectionIdT *sectionId, CL_IN ClTimeT expirationTime)
	Sets the expiration time of a section.
ClRcT	clCkptSectionIterationFinalize (CL_IN ClHandleT sectionIterationHandle)
	Frees resources associated with the iteration.
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	clCkptSectionIterationNext (CL_IN ClHandleT sectionIterationHandle, CL_OUT ClCkptSectionDescriptorT *sectionDescriptor)
	Returns the next section in the list of sections.
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	clCkptSelectionObjectGet (CL_IN ClCkptSvcHdlT ckptHandle, CL_OUT ClSelectionObjectT *selectionObject)
	Helps detect pending callbacks.

Detailed Description

Defines, Structures, Typedefs, Functions.

Macro Definition Documentation

#define CL_CKPT_ALL_OPEN_ARE_REPLICAS 0x40

OpenClovis extension.

If this flag is set, all nodes that open this checkpoint will become a replica. Good for 1+N redundancy

#define CL_CKPT_DISTRIBUTED 0X10

Hot stanby checkpoint.

This is not defined by SAF but an extension by OpenClovis ASP.

#define CL_CKPT_PEER_TO_PEER_CACHE_DISABLE 0x100

OpenClovis extension.

To be used with CL_CKPT_PEER_TO_PEER_REPLICA flag to disable the client side cache for ckpt clients. Use it preferably with 1+N (N > 1) hot-standby checkpoints and CL_CKPT_PEER_TO_PEER_REPLICA option

#define CL_CKPT_PEER_TO_PEER_REPLICA 0x80

OpenClovis extension.

If this flag is set, the writes are sent peer to peer for hot-standby or CL_CKPT_DISTRIBUTED checkpoints.

#define CL_CKPT_WR_ACTIVE_REPLICA_WEAK 0X4

Asynchronous checkpoint.

Rest of the replicas updation need not be atomic.

#define CL_CKPT_WR_ALL_SAFE 0X20

Safe Asynchronous checkpoint.

This is not defined by SAF but an extension by OpenClovis ASP.

Typedef Documentation

typedef void(* ClCkptCheckpointOpenCallbackT)(ClInvocationT invocation, ClCkptHdlT checkpointHandle, ClRcT error)

This function gets called When clCkptCheckpointOpenAsync() call returns on the server.

Header File:: clCkptApi.h

Parameters

invocation	(in) invocation value of the call. This is basically an identification about the call.
checkpointHandle	(in) contains handle of the opened checkpoint, if the clCkptCheckpointOpenAsync() was succesfull.
error	(in) return value of the clCkptCheckpointOpenAsync() call

Return values

CL_OK	The checkpoint is opened successfully.
CL_ERR_NOT_EXIST	`CL_CKPT_CHECKPOINT_CREATE` flag is not set in creation flags and the checkpoint does not exist.
CL_ERR_ALREADY_EXIST	`CL_CKPT_CHECKPOINT_CREATE` flag is set in creation flags but the Checkpoint already exists and was originally created with different attributes than specified by CheckpointCreation attributes.
CL_ERR_TIMEOUT	An implementation defined timeout occurred before the call could complete.
CL_ERR_TRY_AGAIN	The service could not be provided at this time. The process may try later.
CL_ERR_NO_MEMORY	Either the Checkpoint Service library or some other module of Ckpt Service is out of memory. Thus service can not be provided at this time. This may be a transient problem.
CL_ERR_NO_RESOURCE	Either the Checkpoint Service library or some other module of Checkpoint Service is out of resources (other than memory). Thus, service can not be provided at this time. This may be a transient problem.

Description:: This CheckpointOpe callback function is getting called, when clCkptCheckpointOpenAsync() call returns from the server. It carries the invocation to identify the call and return code for indicating the status of the call. If the retcode is CL_OK, then checkpoint handlE will be carrying the proper handle of the checkpoint which was opened on the particular invocation.

Library File:: ClCkpt

See Also: clCkptCheckpointOpenAsync()

typedef void(* ClCkptCheckpointSynchronizeCallbackT)(ClInvocationT invocation, ClRcT error)

This function gets called When clCkptCheckpointSynchronizeAsync() call returns on the server.

Header File:: clCkptApi.h

Parameters

invocation	(in) invocation value of the call. This is basically an identification about the call.
error	(in) return value of the clCkptCheckpointSynchronizeAsync() call

Return values

CL_OK	The checkpoint is opened successfully.
CL_ERR_TIMEOUT	An implementation defined timeout occurred before the call could complete.
CL_ERR_TRY_AGAIN	The service could not be provided at this time. The process may try later.
CL_ERR_NO_MEMORY	Either the Checkpoint Service library or some other module of Ckpt Service is out of memory. Thus service can not be provided at this time. This may be a transient problem.
CL_ERR_NO_RESOURCE	Either the Checkpoint Service library or some other module of Checkpoint Service is out of resources (other than memory). Thus, service can not be provided at this time. This may be a transient problem.

Description:: Applications which use asynchronous checkpoint option will be notified about the asynchronous write or open status with a callback. If any problem occurs with the asynchronous write, the application asks checkpointing to synchronize all the replicas. This is an asynchronous call. So the applications can register another optional callback which will enable them to know the status of 'synchronize-all-replicas' call.

Library File:: ClCkpt

See Also: clCkptCheckpointSynchronizeAsync()

typedef 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.

Provided the application has been registered for the checkpoint update.

Header File:: clCkptApi.h

Parameters

ckptHdl	(in) Handle of the updated checkpoint.
pName	(in) Name of the checkpoint has been updated locally.
pIoVector	(in) List of updated sections and data of the checkpoint.
numSections	(in) Number of sections are being updated on this checkpoint.
pCookie	(in) Cookie which got from clCkptImmediateConsumptionRegister will be given back to application via this variable.

Return values

CL_OK	The Log stream is opened successfully.
CL_ERR_TIMEOUT	An implementation defined timeout occurred before the call could complete.
CL_ERR_NO_MEMORY	Either the Ckpt Service library or some other module of Ckpt Service is out of memory. Thus service can not be provided at this time. This may be a transient problem.

Description:: This notification callback is getting called, whenever the particular checkpoint has been updated on the local server.This callback will be called for whoever registers for the checkpoint update. Thie notication callback will be registered through clCkptImmediateConsumptionRegister() call. This function carries information about all updated sections and number of sections. This is mainly used for HOT stanby applications on which the stanby application will be notified immediately.

Library File:: ClCkpt

See Also: clCkptImmediateConsumptionRegister

Enumeration Type Documentation

enum ClCkptSectionsChosenT

This enum is used for selection of sections while iterating through all the sections.

Enumerator:

CL_CKPT_SECTIONS_FOREVER	All sections with expiration time set to CL_TIME_END.
CL_CKPT_SECTIONS_LEQ_EXPIRATION_TIME	All sections with expiration time less than or equal to the value of expirationTime.
CL_CKPT_SECTIONS_GEQ_EXPIRATION_TIME	All sections with expiration time greater than or equal to the value of expiration time.
CL_CKPT_SECTIONS_CORRUPTED	All corrupted sections.
CL_CKPT_SECTIONS_ANY	All sections.

enum ClCkptSectionStateT

This enum represents the state of a section in a replica.

Enumerator:

CL_CKPT_SECTION_VALID	Indicates that the section is fine.
CL_CKPT_SECTION_CORRUPTED	Indicates that the section has been corrupted.

Function Documentation

ClRcT clCkptActiveReplicaSet ( CL_IN ClCkptHdlT checkpointHandle )

Sets the local replica to be active replica.

Header File:: clCkptApi.h

Parameters

checkpointHandle The handle checkpointHandle obtained by invoking clCkptCheckpointOpen() function.

Return values

CL_OK	The API executed successfully.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to set the local replica to be active replica if no active replica has been set for the checkpoint.

Library File:: ClCkpt

ClRcT clCkptCheckpointClose ( CL_IN ClCkptHdlT checkpointHandle )

Closes the checkpoint designated by the checkpointHandle.

Header File:: clCkptApi.h

Parameters

checkpointHandle The handle checkpointHandle must have been obtained previously by the invocation of the clCkptCheckpointOpen() function.

Return values

CL_OK	The API executed successfully.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_NO_MEMORY	On memory allocation failure.

Description:: This function closes the checkpoint, designated by checkpointHandle, which was opened by an earlier invocation of the clCkptCheckpointOpen() or clCkptCheckpointOpenAsync() function.

: After this invocation, the handle checkpointHandle is no longer valid. The deletion of a checkpoint frees all resources allocated by the Checkpoint Service for it. When a process is terminated, all of its opened checkpoints are closed. This call cancels all pending callbacks that refer directly or indirectly to the handle checkpointHandle.

: In case clCkptCheckpointDelete() has already been called, then by calling the clCkptCheckpointClose() function, the reference count to this checkpoint becomes zero and the checkpoint is deleted. After this call, if the reference count becomes 0, and clCkptCheckpointDelete() has not been called, then the retention timer associated with the checkpoint [ and provided during invocation of clCkptCheckpointOpenAsync() or clCkptCheckpointOpen() functions ] is started. On expiration of the timer the checkpoint is deleted.

Library File:: ClCkpt

See Also: clCkptCheckpointOpen(), clCkptCheckpointOpenAsync(), clCkptCheckpointDelete()

ClRcT clCkptCheckpointDelete	(	CL_IN ClCkptSvcHdlT	ckptHandle,
		CL_IN const ClNameT *	checkpointName
	)

Removes the checkpoint from the system and frees all resources allocated to it.

Header File:: clCkptApi.ht

Parameters

ckptHandle	The handle, obtained through the clCkptInitialize() function, designating this particular initialization of the Checkpoint Service.
checkpointName	Pointer to the name of the checkpoint to be deleted.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	If the parameters passed are NULL pointers.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_ERR_INUSE	If the checkpoint is already in use.

Description:: This function deletes an existing checkpoint, identified by checkpointName from the cluster.

After completion of the invocation,

The name checkpointName is no longer valid, that is, any invocation of a function of the Checkpoint Service that uses the checkpoint name returns an error, unless a checkpoint is re-created with this name. The checkpoint is re-created by specifying the same name of the checkpoint to be unlinked in an open call with the CL_CKPT_CHECKPOINT_CREATE flag set. This way, a new instance of the checkpoint is created, while the old instance of the checkpoint is not yet finally deleted. Note that this is similar to the way POSIX treats files.
If no process has the checkpoint open when clCkptCheckpointDelete() is invoked, the checkpoint is immediately deleted.
Any process that has the checkpoint open can still continue to access it. Deletion of the checkpoint will occur when the last clCkptCheckpointClose() operation is performed.

: The deletion of a checkpoint frees all resources allocated by the Checkpoint Service for it. This function can be invoked by any process, and the invoking process need not be the creator or opener of the checkpoint.

Library File:: ClCkpt

See Also: clCkptCheckpointOpen(), clCkptCheckpointOpenAsync(), clCkptCheckpointClose()

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.

If there is no existing checkpoint, then this function creates a new checkpoint and opens it.

Header File:: clCkptApi.h

Parameters

ckptHandle	The handle, obtained through the clCkptInitialize() function, designating this particular initialization of the Checkpoint Service.
ckeckpointName	Name of the checkpoint to be opened.
checkpointCreationAttributes	A pointer to the create attributes of a the checkpoint. Refer to ClCkptCheckpointCreationAttributesT structure. This parameter must be filled only when the `CREATE` flag is set.
checkpointOpenFlags	Flags to indicate the desired mode to open. It can have the following values: `CL_CKPT_CHECKPOINT_READ` `CL_CKPT_CHECKPOINT_WRITE` `CL_CKPT_CHECKPOINT_CREATE`
timeout	clCkptCheckpointOpen is considered to be failed if not completed within the timeout. A checkpoint replica may still be created. [It is not supported currently]
checkpointHandle	(out) A pointer to the checkpoint handle, allocated in the address space of the invoking process. If the checkpoint is opened successfully, the Checkpoint Service stores in checkpointHandle the handle that the process uses to access the checkpoint in subsequent invocations of the functions of the Checkpoint Service.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	When the parameters passed are NULL pointers.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_ALREADY_EXIST	If the checkpoint is already existing.
CL_ERR_NO_MEMORY	If there is not enough memory.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: The clCkptCheckpointOpen() function opens a checkpoint. If the checkpoint does not exist, the checkpoint is created first. An invocation of clCkptCheckpointOpen() is blocking. A new checkpoint handle is returned upon completion. A checkpoint can be opened multiple times for reading and/or writing in the same process or in different processes.

: When a checkpoint is opened using the clCkptCheckpointOpen() or clCkptCheckpointOpenAsync() function, some combination of the creation flags, defined in ClCkptCheckpointCreationFlagsT, are bitwise OR-ed together to provide the value of the creationFlags field of the checkpointCreationAttributes parameter.

Library File:: ClCkpt

See Also: clCkptCheckpointOpenAsync(), clCkptCheckpointClose()

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.

Header File:: clCkptApi.h

Parameters

ckptHandle	The handle, obtained through the clCkptInitialize() function, designating this particular initialization of the Checkpoint Service.
invocation	This parameter is used by the application to identify the callback.
checkpointName	Name of the checkpoint to be opened.
checkpointCreationAttributes	Pointer to the create attributes of a the checkpoint. Refer to ClCkptCheckpointCreationAttributesT structure.
checkpointOpenFlags	Flags to indicate the desired mode to open. It can have the following values: `CL_CKPT_CHECKPOINT_READ` `CL_CKPT_CHECKPOINT_WRITE` `CL_CKPT_CHECKPOINT_CREATE`

Return values

CL_OK	The API executed successfully.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to create and open a checkpoint asynchronously.

Library File:: ClCkpt

See Also: clCkptCheckpointOpen(), clCkptCheckpointClose()

ClRcT clCkptCheckpointRead	(	CL_IN ClCkptHdlT	checkpointHandle,
		CL_INOUT ClCkptIOVectorElementT *	ioVector,
		CL_IN ClUint32T	numberOfElements,
		CL_OUT ClUint32T *	erroneousVectorIndex
	)

Reads multiple sections at a time.

Header File:: clCkptApi.h

Parameters

checkpointHandle	The handle to the checkpoint that is to be read. The handle checkpointHandle obtained by invoking either clCkptCheckpointOpen() or clCkptCheckpointOpenCallback() function.
ioVector	Pointer to an IO Vector containing the section IDs and the data to be written.
numberOfElements	Total number of elements in ioVector. Each element is of the type ClCkptIOVectorElementT, and containing the following fields: sectionId: The identifier of the section to be read from. dataBuffer: (in/out) A pointer to a buffer containing the data to be read to. If dataBuffer is NULL, the value of datasize provided by the invoker is ignored and the buffer is provided by the Checkpoint Service library. The buffer must be deallocated by the invoker. dataSize: Size of the data to be read to the buffer designated by dataBuffer. The size is at most maxSectionSize, as specified in the creation attributes of the checkpoint. dataOffset: Offset in the section that marks the start of the data that is to be read. readSize: (out) Used by clCkptCheckpointRead() to record the number of bytes of data that have been read; otherwise, this field is not used.
erroneousVectorIndex	(out) Pointer to the index for errors in ioVector. This is an index in the caller's address space, of the first vector element that causes the invocation to fail. If the invocation succeeds, then erroneousVectorIndex is `NULL` and should be ignored.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	When the parameters passed are NULL pointers.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to read multiple sections at a time. It can be used to read a single section.

Library File:: ClCkpt

ClRcT clCkptCheckpointRetentionDurationSet	(	CL_IN ClCkptHdlT	checkpointHandle,
		CL_IN ClTimeT	retentionDuration
	)

Sets the retention duration of a checkpoint.

Header File:: clCkptApi.h

Parameters

checkpointHandle	The checkpoint whose retention time is being set. This handle is obtained by invoking clCkptCheckpointOpen() function.
retentionDuration	Duration for which the checkpoint can be retained in nanoseconds.

Return values

CL_OK The API executed successfully.

Description:: This function is used to set the retention duration of a checkpoint. If by invocation of clCkptCheckpointClose(), the reference count becomes 0, and clCkptCheckpointDelete() has not been called, then the retention timer associated with the checkpoint ( and provided during invocation of clCkptCheckpointOpenAsync() or clCkptCheckpointOpen() functions ) is started. On expiration of the timer, the checkpoint is deleted.

Library File:: ClCkpt

ClRcT clCkptCheckpointStatusGet	(	CL_IN ClCkptHdlT	checkpointHandle,
		CL_OUT ClCkptCheckpointDescriptorT *	checkpointStatus
	)

Returns the status and the various attributes of the checkpoint.

Header File:: clCkptApi.ht

Parameters

checkpointHandle	The handle of the checkpoint obtained by invoking clCkptCheckpointOpen() function.
checkpointStatus	(out) Pointer to checkpoint descriptor in the address space of the invoking process, that contains the checkpoint status information to be returned. Refer to ClCkptCheckpointDescriptorT structure.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	If the checkpointStatus parameter passed is a NULL pointer.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to return the status and the various attributes of the checkpoint. The list of attributes are defined by the ClCkptCheckpointDescriptorT structure. This function retrieves the checkpointStatus of the checkpoint designated by checkpointHandle.

: If the checkpoint was created using either CL_CKPT_WR_ACTIVE_REPLICA or CL_CKPT_WR_ACTIVE_REPLICA_WEAK option, the checkpoint status is obtained from the active replica. If the checkpoint was created using the CL_CKPT_WR_ALL_REPLICAS option, the Checkpoint Service determines the replica from which to obtain the checkpoint status.

Library File:: ClCkpt

ClRcT clCkptCheckpointSynchronize	(	CL_IN ClCkptHdlT	ckeckpointHandle,
		CL_IN ClTimeT	timeout
	)

Synchronizes the replicas of a checkpoint.

Header File:: clCkptApi.h

Parameters

checkpointHandle	Checkpoint handle returned as part of clCkptCheckpointOpen.
timeout	Time-out to execute the operation.[It is not supported currently]

Return values

CL_OK	The API executed successfully.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to synchronize the replicas of a checkpoint.

Library File:: ClCkpt

See Also: clCkptCheckpointSynchronizeAsync()

ClRcT clCkptCheckpointSynchronizeAsync	(	CL_IN ClCkptHdlT	checkpointHandle,
		CL_IN ClInvocationT	invocation
	)

Synchronizes the replicas of a Checkpoint asynchronously.

Header File:: clCkptApi.h

Parameters

checkpointHandle	Checkpoint handle returned as part of clCkptCheckpointOpen().
invocation	Identifies the call when the callback is called.

Return values

CL_OK The API executed successfully.

Description:: This function is used to synchronize the replicas of a Checkpoint asynchronously.

Library File:: ClCkpt

See Also: clCkptCheckpointSynchronize()

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.

Header File:: clCkptApi.h

Parameters

checkpointHandle	The handle to the checkpoint that is to be written to. The handle checkpointHandle obtained by invoking either clCkptCheckpointOpen() or clCkptCheckpointOpenAsync() function.
ioVector	Pointer to the IO Vector containing the section IDs and the data to be written.
numberOfElements	Total number of elements in ioVector.
erroneousVectorIndex	(out) A pointer to an index, stored in the caller's address space, of the first iovector element that makes the invocation fail. If the index is set to NULL or if the invocation succeeds, the field remains unchanged. Updated if the clCkptCheckpointWrite() call fails.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	When the parameters passed are NULL pointers.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_NO_MEMORY	On memory allocation failure.

Description:

This function writes data from the memory regions specified by ioVector into a checkpoint:

If this checkpoint is created with the CL_CKPT_WR_ALL_REPLICAS property, all of the checkpoint replicas gets updated when the invocation returns. If the invocation does not complete or returns with an error, nothing is written at all.
If the checkpoint is created with the CL_CKPT_WR_ACTIVE_REPLICA property, the active checkpoint replica gets updated when the invocation returns. Other checkpoint replicas are updated asynchronously. If the invocation does not complete or returns with an error, nothing is written.
If the checkpoint is created with the CL_CKPT_WR_ACTIVE_REPLICA_WEAK property, the active checkpoint replica gets updated when the invocation returns. Other checkpoint replicas are updated asynchronously. If the invocation returns with an error, nothing is written at all. However, if the invocation does not complete, the operation may be partially completed and some sections may be corrupted in the active checkpoint replica.

: In a single invocation, several sections and several portions of sections can be updated simultaneously. The elements of the ioVectors are written in order from ioVector[0] to ioVector [numberOfElements - 1]. As a result of this invocation, some sections may grow.

Library File:: ClCkpt

See Also: clCkptSectionCreate(), clCkptSectionDelete(), clCkptSectionExpirationTimeSet(), clCkptSectionIterationInitialize(), clCkptSectionIterationNext(), clCkptSectionIterationFinalize(), clCkptSectionOverwrite()

ClRcT clCkptDispatch	(	CL_IN ClCkptSvcHdlT	ckptHandle,
		CL_IN ClDispatchFlagsT	dispatchFlags
	)

Invokes the pending callback in context of the EO.

Header File:: clCkptApi.h

Parameters

ckptHandle	The handle, obtained through the clCkptInitialize() function, designating this particular initialization of the Ckpt Service.
dispatchFlags	Flags that specify the callback execution behavior clCkptDispatch() function, which have the values `CL_DISPATCH_ONE`, `CL_DISPATCH_ALL` or `CL_DISPATCH_BLOCKING`, as defined in clCommon.h.

Return values

CL_OK	The function completed successfully.
CL_ERR_NOT_INITIALIZED	On initialization failure.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_INVALID_PARAMETER	On passing an invalid parameter.

Description:: This function invokes, in the context of the calling EO, pending callbacks for handle ckptHandle in a way that is specified by the dispatchFlags parameter.

Library File:: ClCkpt

See Also: clCkptSelectionObjectGet()

ClRcT clCkptFinalize ( CL_IN ClCkptSvcHdlT ckptHandle )

Closes the checkpoint service client and cancels all pending callbacks related to the handle.

Header File:: clCkptApi.h

Parameters

ckptHandle The handle, obtained through the clCkptInitialize() function, designating this particular initialization of the Checkpoint Service.

Return values

CL_OK The API executed successfully.

Description:: The clCkptFinalize() function closes the association, represented by the ckptHandle parameter, between the invoking process and the Checkpoint Service. The process must have invoked clCkptInitialize() before it invokes this function. A process must invoke this function once for each handle acquired by invoking clCkptInitialize().

: If the clCkptFinalize() function returns successfully, the clCkptFinalize() function releases all resources acquired when clCkptInitialize() was called. Moreover, it closes all checkpoints that are open for the particular handle. Furthermore, it cancels all pending callbacks related to the particular handle.

: After clCkptFinalize() is called, the selection object is no longer valid. Note that because the callback invocation is asynchronous, it is still possible that some callback calls are processed after this call returns successfully.

Library File:: ClCkpt

See Also: clCkptInitialize()

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.

Header File:: clCkptApi.h

Parameters

checkpointHandle	Checkpoint handle returned as part of clCkptCheckpointOpen().
\param	invocation Identifies the call when the callback is called.

Return values

CL_OK The API executed successfully.

Description:: This function is used to register a callback function that is called. whenever the specified checkpoint data is updated.

Library File:: ClCkpt

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.

Header File:: clCkptApi.h

Parameters

ckptSvcHandle	(out) Checkpoint service handle created by the checkpoint client and returned to the application. This handle designates this particular initialization of the the Checkpoint Service. The application must not modify or interpret this.
callbacks	Optional callbacks for applications which use asynchronous checkpoints.
version	(in/out) As an input parameter, version is a pointer to the required Checkpoint Service version. As an output parameter, the version actually supported by the Checkpoint Service is delivered.

Return values

CL_OK	The API executed successfully.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.
CL_ERR_NULL_POINTER
CL_ERR_VERSION_MISMATCH

Description:: This function initializes the Checkpoint library for the invoking process and registers the various callback functions. This function must be invoked prior to the invocation of any other Checkpoint Service functionality. The handle ckptSvcHandle is returned as the reference to this association between the process and the Checkpoint Service. The process uses this handle in subsequent communication with the Checkpoint Service.

*x

Library File:: ClCkpt

See Also: clCkptFinalize()

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.

Header File:: clCkptApi.h

Parameters

checkpointHandle	The handle checkpointHandle obtained by invoking clCkptCheckpointOpen() function.
sectionCreationAttributes	A pointer to a ClCkptSectionCreationAttributesT structure, that contains the (in/out) field sectionId and the (in) field expirationTime.
initialData	Pointer to the location in the address space of the invoking process that contains the initial data of the section to be created.
initialDataSize	The size in bytes of the initial data of the section to be created. Initial size can be at most maxSectionSize, as specified by the checkpoint creation attributes in clCkptCheckpointOpen().

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	When either of the parameters sectionCreationAttributes or initialData passed are NULL pointers.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_ALREADY_EXIST	If the checkpoint is already existing.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function creates a new section in the checkpoint referred to by checkpointHandle as long as the total number of existing sections is less than the maximum number of sections specified by the clCkptCheckpointOpen() or clCkptCheckpointOpenAsync() function call. Unlike a checkpoint, a section need not be opened for access. The section will be deleted by the Checkpoint Service when its expiration time is reached.

: If a checkpoint is created to have only one section, it is not necessary to create that section. The default section is identified by the special identifier CL_CKPT_DEFAULT_SECTION_ID. If the checkpoint was created with the CL_CKPT_WR_ALL_REPLICAS property, the section is created in all of the checkpoint replicas when the invocation returns; otherwise, the section has been created at least in the active checkpoint replica, when the invocation returns and will be created asynchronously in the other checkpoint replicas.

Library File:: ClCkpt

See Also: clCkptSectionDelete(), clCkptSectionExpirationTimeSet(), clCkptSectionIterationInitialize(), clCkptSectionIterationNext(), clCkptSectionIterationFinalize(), clCkptCheckpointWrite(), clCkptSectionOverwrite()

ClRcT clCkptSectionDelete	(	CL_IN ClCkptHdlT	checkpointHandle,
		CL_IN const ClCkptSectionIdT *	sectionId
	)

Deletes a section in the given checkpoint.

Header File:: clCkptApi.ht

Parameters

checkpointHandle	The handle to the checkpoint holding the section to be deleted. The handle to the checkpoint holding the section to be deleted. The handle checkpointHandle obtained by invoking clCkptCheckpointOpen() function.
sectionId	A pointer to the identifier of the section to be deleted.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	When the parameter sectionId passed is a NULL pointer.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function deletes a section in the checkpoint referred to by checkpointHandle. If the checkpoint was created with the CL_CKPT_WR_ALL_REPLICAS property, the section has been deleted in all of the checkpoint replicas when the invocation returns; otherwise, the section has been deleted at least in the active checkpoint replica when the invocation returns. The default section, identified by CL_CKPT_DEFAULT_SECTION_ID, cannot be deleted by invoking the clCkptSectionDelete() function.

Library File:: ClCkpt

See Also: clCkptSectionCreate(), clCkptSectionExpirationTimeSet(), clCkptSectionIterationInitialize(), clCkptSectionIterationNext(), clCkptSectionIterationFinalize(), clCkptCheckpointWrite(), clCkptSectionOverwrite()

ClRcT clCkptSectionExpirationTimeSet	(	CL_IN ClCkptHdlT	checkpointHandle,
		CL_IN const ClCkptSectionIdT *	sectionId,
		CL_IN ClTimeT	expirationTime
	)

Sets the expiration time of a section.

Header File:: clCkptApi.h

Parameters

checkpointHandle	The handle checkpointHandle obtained by invoking clCkptCheckpointOpen() function.
sectionId	Section identifier.
expirationTime	Expiration time of the section.

Return values

CL_OK	The API executed successfully.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to set the expiration time of a section.

Library File:: ClCkpt

See Also: clCkptSectionCreate(), clCkptSectionDelete(), clCkptSectionIterationInitialize(), clCkptSectionIterationNext(), clCkptSectionIterationFinalize(), clCkptCheckpointWrite(), clCkptSectionOverwrite()

ClRcT clCkptSectionIterationFinalize ( CL_IN ClHandleT sectionIterationHandle )

Frees resources associated with the iteration.

Header File:: clCkptApi.h

Parameters

sectionIterationHandle Handle of the iteration.

Return values

CL_OK The API executed successfully.

Description:: This function is used to free resources associated with the iteration identified by the sectionIterationHandle.

Library File:: ClCkpt

See Also: clCkptSectionCreate(), clCkptSectionDelete(), clCkptSectionExpirationTimeSet(), clCkptSectionIterationInitialize(), clCkptSectionIterationNext(), clCkptCheckpointWrite(), clCkptSectionOverwrite()

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.

Header File:: clCkptApi.h

Parameters

checkpointHandle	The handle checkpointHandle obtained by invoking clCkptCheckpointOpen() function.
sectionsChosen	Rule for the iteration. Refer the ClCkptSectionChosenT enum.
expirationTime	Expiration time used along with the rule.
sectionIterationHandle	(out) Handle used to identify a present section.

Return values

CL_OK	The API executed successfully.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to enable the application to iterate through the sections in a checkpoint.

Library File:: ClCkpt

See Also: clCkptSectionCreate(), clCkptSectionDelete(), clCkptSectionExpirationTimeSet(), clCkptSectionIterationNext(), clCkptSectionIterationFinalize(), clCkptCheckpointWrite(), clCkptSectionOverwrite()

ClRcT clCkptSectionIterationNext	(	CL_IN ClHandleT	sectionIterationHandle,
		CL_OUT ClCkptSectionDescriptorT *	sectionDescriptor
	)

Returns the next section in the list of sections.

Header File:: clCkptApi.h

Parameters

sectionIterationHandle	Checkpoint handle returned as part of clCkptCheckpointOpen().
sectionDescriptor	(out) Pointer to the descriptor of a section. Refer the ClCkptSectionDescriptorT structure.

Return values

CL_OK	The API executed successfully.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to retrieve the next section in the list of sections matching the clCkptSectionIterationInitialize() call.

Library File:: ClCkpt

See Also: clCkptSectionCreate(), clCkptSectionDelete(), clCkptSectionExpirationTimeSet(), clCkptSectionIterationInitialize(), clCkptSectionIterationFinalize(), clCkptCheckpointWrite(), clCkptSectionOverwrite

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.

Header File:: clCkptApi.h

Parameters

checkpointHandle	The handle that designates the checkpoint that is written to. The handle checkpointHandle is obtained by invoking either clCkptCheckpointOpen() or clCkptCheckpointOpenAsync() functions.
sectionId	A pointer to an identifier for the section that is to be overwritten. If this pointer points to `CL_CKPT_DEFAULT_SECTION_ID`, the default section is updated.
dataBuffer	Pointer to the buffer from where the data is being copied.
dataSize	The size in bytes of the data to be written, which becomes the new size for this section.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	When the parameters sectionId and dataBuffer passed are NULL pointers.
CL_ERR_NOT_INITIALIZED	If the checkpoint server is not completely initialized.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_ERR_TRY_AGAIN	System is in a transitory unstable state, please try later.

Description:: This function is used to write a single section in a given checkpoint. This function is similar to clCkptCheckpointWrite() except that it overwrites only a single section. As a result of this invocation, the previous data and size of the section will change. This function may be invoked, even if there was no prior invocation of clCkptCheckpointWrite().

Library File:: ClCkpt

See Also: clCkptSectionCreate(), clCkptSectionDelete(), clCkptSectionExpirationTimeSet(), clCkptSectionIterationInitialize(), clCkptSectionIterationNext(), clCkptSectionIterationFinalize(), clCkptCheckpointWrite()

ClRcT clCkptSelectionObjectGet	(	CL_IN ClCkptSvcHdlT	ckptHandle,
		CL_OUT ClSelectionObjectT *	selectionObject
	)

Helps detect pending callbacks.

Header File:: clCkptApi.h

Parameters

ckptHandle	The handle, obtained through the clCkptInitialize() function, designating this particular initialization of the Ckpt Service.
pSelectionObject	(out) A pointer to the operating system handle that the invoking EO can use to detect pending callbacks.

Return values

CL_OK	The function completed successfully.
CL_ERR_NOT_INITIALIZED	On initialization failure.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_INVALID_PARAMETER	On passing an invalid parameter.

Description:: This function returns the operating system handle, pSelectionObject, associated with the handle ckptHandle. The invoking EO can use this handle to detect pending callbacks, instead of repeatedly invoking clCkptDispatch() for this purpose.

: The pSelectionObject returned by this function, is a file descriptor that can be used with poll() or select() systems call detect incoming callbacks.

: The selectionObject returned by this function is valid until clCkptFinalize() is invoked on the same handle ckptHandle.

Library File:: ClCkpt

See Also: clCkptDispatch()

Files

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation