Sun Microsystems
Products & Services
 
Support & Training
 
 

Previous Previous     Contents     Index     Next Next
Chapter 6

Understanding Change Notifications

This chapter describes how the CMM API indicates changes in the state of the cluster by sending notifications to system services and applications. For more information, see the following topics:

Introduction to Change Notifications

Notifications are information messages sent by the nhcmmd daemon on a node to services or applications registered to receive them. Notifications are sent when there is a change in the membership of the cluster.

In a cluster, the master node is aware of all changes in the state of peer nodes. The cluster state information held by the nhcmmd daemon on the master node is propagated to all peer nodes.

Cluster notifications enable a service or application to maintain an accurate view of the state of the cluster and of the state of any peer node. An application or service can use notifications to coordinate changes in system services when a peer node joins or leaves the cluster.

A single change in the cluster state can cause an application or service to receive several associated cluster change notifications. This can be due to the fact that a change in the membership of one node can effect changes in the membership of several other nodes.

A cluster change notification does not contain any information about the previous role of a node. Therefore, for example, when a callback is invoked with the CMM_MEMBER_LEFT notification, the indicated node could have been in the cluster with no role, or could have had the CMM_MASTER or CMM_VICE_MASTER role.

Several scenarios in which there are changes in the state of the cluster, and the associated notifications sent during these changes, are described in Notifications During Changes in the Cluster State.

For an example of how to retrieve notifications about changes in the cluster state, see Example 7-2.

To verify that the nhcmmd daemon is running on your peer nodes, see the Netra High Availability Suite Foundation Services 2.1 6/03 Cluster Administration Guide. For information about the nhcmmd daemon, see the nhcmmd(1M) man page.

Understanding the Structure of Notifications

Applications that you write can register a callback function to handle notification messages. The cmm_notify_t callback receives the cluster membership change (cmc) callback function. The cmm_cmc_register() function takes the service or application data and this callback function. You must provide relevant data when registering. The code in Example 6-1 details the related structure, called the cmm_cmc_notification_t structure.

Example 6-1 The cmm_cmc_notification_t Structure

typedef struct { cmm_cmchanges_t cmchange; cmm_nodeid_t nodeid; } cmm_cmc_notification_t;

The fields in this structure detail the cluster change and specify the node concerned. These fields are described in Table 6-1.

Table 6-1 Description of Fields of the cmm_cmc_notification_t Structure

Field Description 
nodeidThis field represents the node on which the change occurs if the notification is made for each node. 
cmchangeThis field indicates the type of change that occurs. 

This structure is used by the cmm_notify_t callback function. The cmm_notify_t callback function contains the parameters described in Table 6-2.

Table 6-2 Description of the Parameters of the cmm_notify_t Callback Function

Parameter Description 
change_notificationThis parameter is a pointer to a structure describing the specific membership change and the affected cluster member's identity. This is either the nodeid of a specific node, or 0 when the change affects all peer nodes.
client_dataThis parameter is a service or application-defined value given to the cmm_cmc_register() function. The CMM API does not use this parameter internally.

If change notification data is required for longer than the duration of the callback, it must be handled by the client application or service.

Notification Values

Change notification messages contain the nodeid of the affected node and a cmm_cmchanges_t data type. The cmm_cmchanges_t data type describes the change notification. The following table lists the notifications of the cmm_cmchanges_t structure:

Table 6-3 Change Notifications

Value

Description

CMM_INVALID_CLUSTER

A critical problem occurred. For example, there are two master nodes. One node must be rebooted as soon as possible. The nodeid field is not useful in this case.

CMM_MASTER_DEMOTED

The nodeid represents a previous master node that has been demoted. For more information, see Administrative Attributes.

CMM_MASTER_ELECTED

The nodeid is that of the newly elected master node. A cluster election has selected a new master and the previous master (if any) quits its role. The new node might have just joined the cluster and there might not have been a previous master.

CMM_MEMBER_JOINED

A peer node has joined the cluster. The nodeid is that of the new peer node.

CMM_MEMBER_LEFT

A peer node has the CMM_OUT_OF_CLUSTER role.

CMM_STALE_CLUSTER

The master node sends a membership frame every 4 seconds to inform other nodes of the current state of the cluster. If no frames are received by a node for more than 10 seconds, the CMM on this node notifies the local applications. The CMM_STALE_CLUSTER notification means that, even if the CMM API is available, the returned information from a node might not reflect the current state of the cluster. Operations involving the master, such as a new node joining the cluster, might fail because the master is unreachable. This situation is abnormal and recovery actions must be taken. The nodeid field is not useful in this case. Calls that return the CMM_OK value before this notification return CMM_EAGAIN after it while the cluster is in a stale state.

CMM_VICEMASTER_DEMOTED

The nodeid represents a previous vice-master node that has been demoted. This is only sent if the vice-master node is disqualified.

CMM_VICEMASTER_ELECTED

A new vice-master is elected. The node no longer has its previous role. The previous vice-master (if any) is demoted. The nodeid is that of the newly elected vice-master node.

CMM_VALID_STATE

The state of the cluster is now valid and running correctly. The nodeid field is not useful for this notification.

Notifications During Changes in the Cluster State

There are many scenarios in which the state of a cluster changes and registered applications and services receive notifications of changes in the cluster state.

A change in the state of a single node can cause the states of other nodes to change. For example, if a new master node is elected, the roles of both the new master node and the former master node change. When a scenario involves a change in the state of more than one node, several notifications can be sent. When several notifications are sent, the notifications are sent in the order in which the changes occur. The nhcmmd daemon sends the minimum number of notifications that describe a new cluster situation. Instead of sending a notification for each change of state for each node, the nhcmmd daemon bundles the information into the minimum number of notifications.

If peer nodes are communicating correctly, the same notification is sent to all nodes, regardless of their membership role.

In each of the scenarios described in this section, there are two example peer nodes: node A and node B. The roles of these nodes are shown in Table 6-4. The transition from one role to another is represented as (Role_A) --> (Role_B).

Table 6-4 Description of the Roles of Example Nodes A and B

Node Role Description 
inA peer node with a role other than the CMM_OUT_OF_CLUSTER role.
masterA node has the CMM_MASTER role.
vice-masterA node has the CMM_VICEMASTER role.
outA node has the CMM_OUT_OF_CLUSTER role.

For a summary of the membership roles that a node can have, see Membership Roles.

This section describes scenarios of cluster state change and these related notifications:

Previous Previous     Contents     Index     Next Next