Understanding the Structure of Notifications

Applications that you write can register a callback function to handle notification messages. The callback function SaClmClusterTrackCallbackT must be used and is registered during the library initialization. Notification tracking is started by calling the function saClmClusterTrack() with either the SA_TRACK_CHANGES or SA_TRACK_CHANGES_ONLY flag. The first flag requires notification including information about all the cluster members, including those that left the cluster after the last notification. The second flag asks for notifications including information about only the nodes that suffered any change. The flags are mutually exclusive.The callback function receives the following three parameters.

The notification buffer has the following members.

Each element of the notification array is of the structure type SaClmClusterNotification with the following fields.

Nodes can be changed as follows:

• SA_CLM_NODE_NO_CHANGE: No change in the node.

• SA_CLM_NODE_JOINED : The node joined the cluster.

• SA_CLM_NODE_LEFT : The node left the cluster.

• SA_CLM_NODE_RECONFIGURED : Some data changed in the node.

The following example presents a simple application showing all the notifications received:

#include <stdio.h>
#include <stdlib.h>
#include <saClm.h>
 
#include "common.h"
 
 
static void notif_callback(
                          const SaClmClusterNotificationBufferT 
                          *notificationBuffer,
                          SaUint32T numberOfMembers,
                          SaAisErrorT error)
{
      if (error != SA_AIS_OK) {
	    printf("Callback received error %s\n", 
           errString(error));
	    return;
      }
 
	print_notif_buffer(notificationBuffer);
}
 
int main(void)
{
	SaClmHandleT       clmHandle;
	SaAisErrorT        res;
	SaVersionT         version;
	SaClmCallbacksT    callbacks;
 
	version.releaseCode  = VERSION_RELEASE;
	version.majorVersion = VERSION_MAJOR;
	version.minorVersion = VERSION_MINOR;
 
	callbacks.saClmClusterNodeGetCallback = NULL;
	callbacks.saClmClusterTrackCallback = notif_callback;
 
	res = saClmInitialize(&clmHandle, &callbacks, &version);
	if (res != SA_AIS_OK) {
		printf("Failed to initialize the library: %s\n",
		       errString(res));
		exit(1);
	}
 
	res = saClmClusterTrack(clmHandle, SA_TRACK_CHANGES_ONLY, 
           NULL);
	if (res != SA_AIS_OK) {
		printf("Track call failed: %s\n", errString(res));
		exit(1);
	}
 
	res = saClmDispatch(clmHandle, SA_DISPATCH_BLOCKING);
	if (res != SA_AIS_OK) {
 
		printf("Dispatch failed: %s\n", errString(res));
		exit(1);
	}
 
	          (void) saClmFinalize(clmHandle);
 
 
	return 0;
}

In this example, the selection object is not used to poll for data. Instead, saClmDispatch() is called with the flag SA_DISPATCH_BLOCKING. Any thread calling saClmDispatch() with this flag remains within dispatch and executes the callbacks as they become pending. The thread does not return until the corresponding saClmFinalize() function is executed by another thread. Because this example has no other thread, this situation would require you to kill the process.Applications that are configured to keep track of the cluster's state must rely on the notifications. To initially get the state of the cluster, the track function must be called with the SA_DISPATCH_CURRENT flag. However, between both calls, some notification could be missed. To avoid this, combine both flags in the same call to the track function.