Description of CPM. More...

Description of CPM.

If you have not already done so, please read the high availability section of OpenClovis SDK user guide to get an idea of the architecture of the AMF in general and CPM in particular.

The functions exposed by the CPM

The functions exposed by the CPM can be classified as SAF APIs and non SAF APIs. Non SAF APIs include other utility APIs provided by the CPM.

SAF APIs

CPM exposes most of the SAF defined interfaces, which can be used by the application developers to develop highly available applications.

Note: In the following sections the term AMF is used whenever providing the API functionality involves both the CPM and AMS, even if the exposed API name contains only CPM. For e.g. clCpmHAStateGet() APIs is actually serviced by AMS, even though the name indicates that it is a CPM's exposed API. This is true for most of the SAF APIs exposed by the CPM.

The APIs in this section fall into various category as defined in the SAF AMF specification.

Library Life Cycle.

The application begins its life cycle by calling clCpmClientInitialize() API. It can call the clCpmSelectionObjectGet() to get a OS specific object on which to wait for the callbacks that are or will be invoked by the CPM. To actually execute the callback in the applications context, the application can call clCpmDispatch() API. When the process is terminating gracefully, it should call the clCpmClientFinalize() API to indicate its end of association with the CPM client.

Component Registration and Unregistration

The application can call clCpmComponentRegister() to notify to the AMF that it is now ready to provide service. It should call the clCpmComponentUnregister while terminating. The clCpmComponentNameGet() API returns the name of calling component. This is the name that should be used while registration and unregistration.

Component Service Instance Management

The application can call clCpmHAStateGet() API to query AMF about the HA state of the component for a particular component service instance. The application should call the clCpmCSIQuiescingComplete() API to indicate to AMF that it has serviced all the pending requests since being moved to the quiesced state and can now be terminated.

See Also: ClCpmCSISetCallbackT, ClCpmCSIRmvCallbackT and Callbacks invoked by the CPM.

Component Life Cycle

See Also: Callbacks invoked by the CPM

Protection Group Management

To request the AMF to track the changes in the protection group associated with a component service instance, the application should call clCpmProtectionGroupTrack() API. Different kinds of track are supported via different flags. To request the AMF to stop tracking the changes in the protection group associated with a component service instance, the application should call clCpmProtectionGroupTrackStop() API.

See Also: ClCpmProtectionGroupTrackCallbackT

Error Reporting

A component can report error on either itself or some other component using the clCpmComponentFailureReport() API.

Component Response to Framework Requests

The application can call clCpmResponse() API to indicate the status of carrying out the AMFs request (Callbacks invoked by the CPM) in the applications context. a

Callbacks invoked by the CPM

The AMF assigns work to a component by invoking ClCpmCSISetCallbackT. To be more specific, the AMF requests the application to assume a particular HA state for component on behalf of a component service instance by invoking this callback. Depending on the HA state which is passed by this callback, the application can start providing service.

The AMF removes work assigned to a component by invoking ClCpmCSIRmvCallbackT. The AMF requests that the component stop providing service for a particular component service instance, by invoking this callback.

The AMF invokes the ClCpmProtectionGroupTrackCallbackT in the applications context, whenever there is a change in the protection group associated with a component service instance and the application has called clCpmProtectionGroupTrack() API to track changes in the same protection group.

The AMF requests the component to gracefully terminate by invoking ClCpmTerminateCallbackT. The application is supposed to call clCpmComponentUnregister() and clCpmClientFinalize() API after doing all the component specific finalization.

The AMF requests a proxy component to instantiate a proxied component by invoking ClCpmProxiedComponentInstantiateCallbackT callback of the proxy component.

The AMF requests a proxy component to abruptly terminate a proxied component by invoking ClCpmProxiedComponentCleanupCallbackT callback of the proxy component.

Non SAF APIs

The clCpmComponentIdGet() API returns an ID which is guaranteed to be unique in the cluster.

The clCpmComponentAddressGet() API can be called by the application to find out the communication port of some other component, by giving the name of the component and address of the node where the component is present.

To find out the address of the active system controller node in the cluster the application can call clCpmMasterAddressGet() API. To check whether it is running on active system controller node it can call clCpmIsMaster() API. To find the name of the node where the application is running it can call the clCpmLocalNodeNameGet() API.