Group Services Programming Guide and Reference

ha_gs_protocol_approved_callback subroutine

Purpose

ha_gs_protocol_approved_callback - A callback routine that the Group Services subsystem calls to deliver a protocol approved notification to a GS client

Library

GSAPI Thread-Safe Library (libha_gs_r.a)

GSAPI Library (not thread-safe) (libha_gs.a)

Syntax

#include <ha_gs.h>
 
void
    ha_gs_protocol_approved_callback(
        const   ha_gs_protocol_approved_notification_t      *notification)
 

Parameters

notification

A pointer to a protocol approved notification block.

Description

The ha_gs_protocol_approved_callback subroutine defines a GS client's protocol approved callback routine. The GS client uses it to handle protocol approved notifications from the Group Services subsystem. The process provides the address of the protocol approved callback routine to the Group Services subsystem on the ha_gs_join subroutine when it joins the group as a provider.

The Group Services subsystem then calls the protocol approved callback routine when it has a protocol approved notification to deliver to the GS client. For an n-phase protocol, this notification is delivered after the protocol has been approved by voting. All one-phase protocols are automatically approved.

On input, the protocol approved callback routine receives information that specifies the changes that have been made to the group, such as its membership or its state value, as well as other control information for the protocol, such as the number of phases that were run.

On input, the protocol approved callback routine receives a pointer to the protocol approved notification block. The protocol approved notification block has the following definition:

typedef struct {
    ha_gs_notification_type_t   gs_notification_type;
    ha_gs_token_t               gs_provider_token;
    ha_gs_request_t             gs_protocol_type;
    ha_gs_summary_code_t        gs_summary_code;
    ha_gs_proposal_t            *gs_proposal;
} ha_gs_approved_notification_t;

The gs_notification_type field contains the type of notification. For a protocol approved notification, it contains a value of HA_GS_APPROVED_NOTIFICATION.

The gs_provider_token field contains a token that identifies the caller as a provider of the group. This token was previously initialized when the provider joined the group using the ha_gs_join subroutine.

The gs_protocol_type field contains the type of request for which this protocol approved notification is being delivered.

HA_GS_JOIN

One or more providers are attempting to join the group.

HA_GS_FAILURE_LEAVE

One or more providers has failed and is leaving the group.

HA_GS_LEAVE

A provider is voluntarily leaving the group.

HA_GS_EXPEL

A provider is attempting to expel one or more providers from the group.

HA_GS_STATE_VALUE_CHANGE

A provider is trying to change the group's state value.

HA_GS_PROVIDER_MESSAGE

A provider is broadcasting a message to the group.

HA_GS_CAST_OUT

One or more source-group providers have left the source-group, requiring these target-group providers to leave also. The source-group's state value is contained in the gs_source_state_value field of the proposal information block.

HA_GS_SOURCE_STATE_REFLECTION

The source-group has modified its state value, and this is being reflected to the target-groups. The source-group's state value is contained in the gs_source_state_value field of the proposal information block.

HA_GS_GROUP_ATTRIBUTE_CHANGE

A provider has requested to change the group's attributes via the ha_gs_change_attributes() interface.

The gs_summary_code field contains one or more flags that indicate whether any default votes were recorded during any previous voting phase. It can contain one or more of the following flags:

HA_GS_EXPLICIT_APPROVE

This flag is set for a protocol approved notification if all approval votes in the tally were explicitly submitted by the providers. No other flags are set with this flag.

HA_GS_DEFAULT_APPROVE

This flag is set for a protocol approved notification if one or more approval votes in the tally were recorded by default. If this flag is set, the HA_GS_TIME_LIMIT_EXCEEDED flag, the HA_GS_PROVIDER_FAILED flag, or both flags are also set.

HA_GS_TIME_LIMIT_EXCEEDED

This flag is set when a default approval vote was recorded because one or more providers failed to vote in time.

HA_GS_PROVIDER_FAILED

This flag is set when a default approval vote was recorded because one or more providers failed (because the node or process failed). The reason for the failure will be provided during the subsequent failure leave protocol.

HA_GS_DEACTIVATE_UNSUCCESSFUL

This flag is set when a deactivate script exited with an unsuccessful return value.

HA_GS_DEACTIVATE_TIME_LIMIT_EXCEEDED

This flag is set when a deactivate script did not exit within the specified time limit.

The gs_proposal field points to the proposal block for the proposal on which the vote is requested. For information about this block, see the ha_gs_n_phase_callback man page.

Restrictions

For important information about multiprocessing considerations that apply to all callback routines, see the ha_gs_n_phase_callback man page.

Return Values

None.

Error Values

None.

Synchronous Errors

None.

Asynchronous Errors

None.

Files

ha_gs.h

Prerequisite Information

Understanding Group Services.

Related Information

Subroutines: ha_gs_init, ha_gs_join, ha_gs_change_state_value, ha_gs_send_message, ha_gs_leave, ha_gs_expel, ha_gs_change_attributes, ha_gs_goodbye