Group Services Programming Guide and Reference

ha_gs_protocol_rejected_callback subroutine

Purpose

ha_gs_protocol_rejected_callback - A callback routine that the Group Services subsystem calls to deliver a protocol rejected 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_rejected_callback(
        const   ha_gs_rejected_notification_t      *notification)
 

Parameters

notification

A pointer to a protocol rejected notification block.

Description

The ha_gs_protocol_rejected_callback subroutine defines a GS client's protocol rejected callback routine. The GS client uses it to handle protocol rejected notifications from the Group Services subsystem. The process provides the address of the protocol rejected 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 rejected callback routine when it has a protocol rejected notification to deliver to the GS client. This occurs after a n-phase protocol has been rejected by voting. One-phase protocols cannot be rejected; they are all automatically approved.

On input, the protocol rejected callback routine receives information that specifies the proposed changes to the group, such as its membership or its state value, as well as other control information for the protocol, such as the reason for the rejection.

A protocol can be rejected for several reasons, which include:

• At least one of the providers explicitly voted to reject it
• A default reject vote was recorded for a failing provider
• A default reject vote was recorded because a provider failed to vote within the specified time limit.

When a protocol is rejected because a provider failed, the Group Services subsystem initiates a separate failure leave protocol to allow the group to handle the failure. The failure leave protocol specifies the list of failing providers.

When a protocol is rejected because votes were not submitted within the voting time limit, the Group Services subsystem delivers an announcement notification that lists the tardy providers.

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

typedef struct  {
    ha_gs_notification_type_t   ha_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_rejected_notification_t;

The gs_notification_type field contains the type of notification. For a protocol rejected notification, it contains a value of HA_GS_REJECTED_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 rejected notification is being delivered.

HA_GS_JOIN

One or more providers is 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_REJECT

This flag is set for a protocol rejected notification if one or more rejection votes in the tally were explicitly submitted by the providers.

HA_GS_DEFAULT_REJECT

This flag is set for a protocol rejected notification if one or more rejection 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 rejection vote was recorded because one or more providers failed to vote in time.

HA_GS_PROVIDER_FAILED

This flag is set when a default rejection 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_attributesha_gs_goodbye