Group Services Programming Guide and Reference

GSAPI design considerations

This section includes some things to think about as you design your application to use the GSAPI. It provides guidelines for:

• Coding callback routines
• Coding for performance
• Migration and coexistence

Coding callback routines

The GSAPI provides a number of separate callback routines, each of which expects to receive a different type of notification. However, each notification block also specifies its type. This design allows you to code callback routines using either of the two following strategies, or a combination of the two:

• Code a number of specialized callback routines. This reduces the amount of checking each callback routine must perform when it receives a notification. You could use this approach if performance and path length are considerations when your application handles a notification.
• Code a general callback routine that parses the notifications it receives. This reduces the number of callback routines you need to code, but increases the amount of work each must do to determine the type of notification it has received.

Refer to the ha_gs_dispatch Subroutine Description for additional information related to invoking callback functions and handling notifications.

Coordination of multiple notifications

The discussion of multiprocessing considerations in this section applies to all callback routines.

The Group Services subsystem presents all notifications to all providers in a single group in the same order. The providers should try to invoke the same callback routines in the same order. However, the Group Services subsystem verifies that, for n-phase protocols, all of the group's providers have reached the same control point before continuing to the next notification. In other cases, the providers may not receive and react to the notifications at the same time. For example, a provider might not receive a notification immediately because it is busy and not reading the socket.

If GS clients are providers in multiple groups, there is no guarantee that every provider will receive the notifications from different groups in the same order.

For multi-threaded clients, it is assumed that the callback routines are thread-safe and reentrant. If the same callback routines are specified for multiple groups, a multi-threaded client can process notifications by invoking the callback routines for more than one group at a time. For single-threaded providers, if they are acting as providers for multiple groups, they must also be coded to handle simultaneously running protocols in all groups.

In all cases where GS clients are acting as providers in multiple groups, it is the responsibility of the providers to ensure that they do not create deadlock situations across groups. An example of a deadlock is when one provider blocks before voting, waiting for another provider to take some action. Meanwhile, the second provider is blocked on another group protocol, waiting for the first provider to take some action.

The Group Services subsystem invokes callback routines only on the same thread or threads that are used to call the ha_gs_dispatch subroutine.

Coding for performance

To get the best performance from your application, keep the following guidelines in mind:

• Minimize the number of groups, providers, and nodes your application requires. The performance of your application depends on its size and distribution in the system. The greater the number of groups, the greater the number of providers joined to those groups. The greater the number of nodes across which each group is spread, the longer it will take to coordinate your application's activities.

  To the extent that it is possible, keep your application as small as possible.

• Minimize the size of the provider-broadcast messages that your application uses. The larger the messages, the greater the load on the network, particularly when a message must be broadcast to every provider in a group and a large number of subscribers as well.
• If possible, select the batching option to allow the Group Services subsystem to batch multiple join requests together. During group initialization, when all of the providers are joining their groups, each join request requires the invocation of a separate protocol. To decrease the load on the system, batch them together whenever possible.
• The actions taken during the barriers that are imposed by an n-phase protocol should be idempotent (designed so that they can run one or more times with no loss of correctness).

  Suppose that the providers of an application have been taking external actions during the barriers that are imposed by a multi-phase protocol, and that these actions must be completed for the application to be operational. Now suppose that the protocol terminates because of a failure. If the actions that the providers have already taken are not designed to be idempotent, the providers must explicitly undo the actions before they restart the protocol. Such an undo phase can be time-consuming and may require additional phases of coordination among the providers. However, if the actions are idempotent, there is no need for an explicit undo phase. The protocol can simply be restarted.

Migration and coexistence

This book documents the level of Group Services provided by PSSP 3.4 and by HACMP/ES at the HACMP 4.4 level. The changes from the previous level are:

• Addition of two new APIs: ha_gs_get_node_number(), which gives the local node number, and ha_gs_get_adapter_info(), which gives the node number and the adapter interface name corresponding to a given IP address.
• Addition of HA_CSS1_MEMBERSHIP_GROUP for the high performance switch adapters.
• Addition of HA_ML0_MEMBERSHIP_GROUP for the aggregate switch group between HA_CSS0_MEMBERSHIP_GROUP and HA_CSS1_MEMBERSHIP_GROUP. This can be supported only by PSSP 3.3 and later releases.

The changes from the level provided by PSSP 3.1 to the level provided by PSSP 3.2 are:

• FFDC ID retrieval subroutine ha_gs_get_ffdc_id when ha_gs_dispatch returns a failure.

GS clients that were written to any previous level of Group Services run without having to be recompiled, and without change on the latest level.

However, if you wish your GS client to take advantage of the new support available in the latest level of Group Services, you must change the code to use the function, recompile it, and relink it using the latest Group Services library and header. In addition, your GS client must run on nodes at the latest level of PSSP or HACMP/ES, and all of the nodes in the system partition must be running the latest level of PSSP or HACMP/ES. It is the responsibility of the GS client to ensure that all binaries are at the same level. GS clients can use group attributes, provider instance numbers, and group state values to ensure this.