sun.com | docs.sun.com | How To Buy | My Sun | Worldwide Sites |  |

| Previous Contents Index 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 During Changes in the Cluster State ## 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
--- | ---
nodeid | This field represents the node on which the change occurs if the notification is made for each node.
cmchange | This 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_notification | This 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_data | This 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
--- | ---
`in` | A peer node with a role other than the `CMM_OUT_OF_CLUSTER` role.
`master` | A node has the `CMM_MASTER` role.
`vice-master` | A node has the `CMM_VICEMASTER` role.
`out` | A 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: Cluster Initialization Notifications. Vice-Master Removal Notifications. Vice-Master Excluded Notification. Peer Node Removal Notification. Master Node Excluded Notifications. Node Other Than Master Excluded Notification. Switchover Notifications. Failover Notifications. Stale Cluster Notification. Amnesia. Split Brain.
Previous Contents Index Next

Copyright 1994-2004 Sun Microsystems